docs: add README + 三 AI 入场文档

- README.md: 项目状态 + 路线图 + 分工 - CLAUDE.md: Claude 职责 + 门禁清单 + Review 重点 - AGENTS.md: Codex 二审侧重（M1 安全 / M4 密钥 / 并发点） - GEMINI.md: Gemini 分期实施清单 + 红线 + 工作流 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-04-23 09:36:09 +08:00
parent 426fa54621
commit 20595a7545
4 changed files with 298 additions and 0 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -0,0 +1,61 @@
+# AGENTS.md — laundry-desk
+
+Codex 在本项目中的入场指引。
+
+## 你在这个项目里的角色
+
+**关键节点二审**。不做全量实现，不跟 Gemini 并行写 PR，避免冲突。
+
+职责：
+1. **架构审查**：每期开工前看 Claude 的 spec 与 Gemini 的初始 PR，发现重大架构问题
+2. **安全审查**：M1（IPC/CSP/sandbox）、M4（短信凭证加密、登录、审计完整性）重点介入
+3. **并发审查**：取件码生成、订单号生成、备份文件写入、SQLite WAL 等并发点
+4. **复杂 Bug 的二次定位**：Gemini 卡住时介入，给出 root cause 判断
+
+## 入场必读
+
+1. [`docs/superpowers/specs/2026-04-23-laundry-desk-design.md`](docs/superpowers/specs/2026-04-23-laundry-desk-design.md) — 设计真源
+2. `~/pro/kb/projects/laundry-desk/status.md` — 当前阶段
+3. `~/pro/kb/tools/codex.md` — Codex 本地协作规约（若存在）
+
+## 审查侧重点
+
+### 通用
+- **输入验证边界**：Zod schema 是否覆盖所有 IPC / 服务入口
+- **类型安全**：禁 `any`、禁不必要的 `as`、严守 `strict`
+- **事务**：多表写入（收件 / 取件 / 备份元数据更新）必须事务
+- **金额精度**：整型分、零浮点、汇总与明细一致性
+
+### M1（基础）
+- Electron 安全：`contextIsolation` / `sandbox` / `nodeIntegration` / CSP / preload 暴露面最小
+- DB 初始化 & migration 的幂等性
+- 取件码 / 订单号生成的并发安全（单实例进程内也要事务重试）
+- 备份 → zip → rotate 链路的原子性与失败回滚
+
+### M2（收款 & 统计）
+- 金额浮点陷阱（展示时再除 100）
+- 聚合查询性能（大表上的 `GROUP BY receive_date`）
+- Excel 导入的数据清洗与主键冲突处理
+
+### M3（照片 & 打印）
+- 大文件（照片）的磁盘占用与清理策略
+- 打印驱动抽象是否真能支持换型号
+- 打印失败是否阻塞业务流程（必须异步 / 可重试）
+
+### M4（员工 & SMS）
+- Argon2 参数（memory / time / parallelism）对 Windows 柜台 CPU 的影响
+- 会话机制（login 后怎么保持？Electron 单用户场景）
+- **短信 SecretKey 加密存储**：必须用 OS keychain（`keytar`），不入库明文
+- 审计日志完整性（所有写入是否都走审计）
+
+## 流程
+
+- Gemini 提 PR → Claude 先看一轮 → Claude 标记"需要 Codex 复审"的关键点
+- Codex 针对标记的点给出意见，直接在 PR 评论
+- 分歧由 manpengan 仲裁
+
+## 不做
+
+- 不抢 Gemini 的实现任务
+- 不改 spec（改由 Claude 经 brainstorm 流程）
+- 不合并 PR（manpengan 合并）
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,69 @@
+# CLAUDE.md — laundry-desk
+
+Claude（Opus 4.7）在本项目中的入场指引。
+
+## 你在这个项目里的角色
+
+**设计与门禁**。不写实现代码，不 scaffold，不装依赖。
+
+职责：
+1. **Brainstorm & Spec**：需求澄清、方案权衡、写设计文档
+2. **门禁验收**：每期结束对照验收清单判断是否可发版
+3. **Code Review**：审 Gemini 的 PR，重点看是否符合 spec 与架构约束
+4. **产品文档**：README / CHANGELOG / release notes
+
+**实现由 Gemini 负责**，见 `GEMINI.md`。**关键节点二审由 Codex 负责**，见 `AGENTS.md`。
+
+## 入场必读
+
+1. [`docs/superpowers/specs/2026-04-23-laundry-desk-design.md`](docs/superpowers/specs/2026-04-23-laundry-desk-design.md) — 设计真源
+2. `~/pro/kb/projects/laundry-desk/status.md` — 当前阶段
+3. `~/pro/kb/workflows/standard-dev-process/SKILL.md` — 10 阶段门禁流程
+4. `~/.claude/rules/common/coding-style.md` — 代码红线（文件 ≤ 400 行、函数 ≤ 50 行、嵌套 ≤ 4 层、金额零浮点、不可变优先）
+
+## 门禁清单（每期 Gemini 声明完成时用）
+
+### 质量
+- [ ] TypeScript `strict: true` 零错
+- [ ] ESLint + Prettier 零警告
+- [ ] 单文件 ≤ 400 行，函数 ≤ 50 行，嵌套 ≤ 4 层
+- [ ] 无硬编码密钥（短信凭证走 settings + keytar）
+- [ ] 所有 IPC handler 入参过 Zod，返回统一信封 `{ ok, data } | { ok, error }`
+- [ ] Renderer 零 Node/DB 直连（`contextIsolation: true` / `nodeIntegration: false` / `sandbox: true`）
+
+### 测试
+- [ ] Service 层 Vitest 覆盖率 ≥ 70%
+- [ ] Playwright E2E 覆盖本期核心路径
+- [ ] 备份文件可还原到全新安装
+
+### 交付
+- [ ] GH Actions `windows-latest` 构建绿灯
+- [ ] Windows 10/11 实机冒烟（manpengan 走查）
+- [ ] `.exe` 大小记录基线（防膨胀）
+- [ ] GitHub Release 附 NSIS 安装器 + SHA256
+
+### 文档
+- [ ] README 截图更新
+- [ ] `docs/CHANGELOG.md` 本期条目
+
+## Code Review 重点
+
+1. **边界**：Renderer 有无直接 `require('better-sqlite3')` 之类越界
+2. **输入验证**：IPC / 服务边界有无 Zod
+3. **事务**：收件 / 取件 / 备份等多表写入是否包事务
+4. **金额**：是否全程用 `int`（分），禁浮点
+5. **错误处理**：无 `catch` 吞异常、无裸 `any`、不静默失败
+6. **Apple HIG**：圆角 / 动效 / 配色 / 深色模式是否落地
+
+## 变更流程
+
+- 设计变更 → 追加 `docs/adr/YYYY-MM-DD-<topic>.md` + 更新 spec 版本
+- 路线图变更 → 更新本文件 & `README.md` 路线表
+- 新风险 → 补 spec §10
+
+## 不做
+
+- 不直接改 `src/` 下的实现代码（Gemini 负责）
+- 不装 npm 依赖
+- 不跑 `pnpm build`
+- 不跳阶段（按 M1 → M2 → M3 → M4 顺序）
--- a/GEMINI.md
+++ b/GEMINI.md
@@ -0,0 +1,120 @@
+# GEMINI.md — laundry-desk
+
+Gemini 在本项目中的入场指引。你是**主力实现者**。
+
+## 你在这个项目里的角色
+
+把 Claude 的 spec 落成能在 Windows 10/11 上跑的 exe。包括：
+- 代码实现（main / preload / renderer / shared / services）
+- 测试编写（Vitest + Playwright）
+- 构建配置（Vite / electron-vite / electron-builder）
+- 修 build、修测试、修 CI
+- 每期提一个 Pull Request，通过门禁后由 manpengan 合并并 tag release
+
+## 入场必读（按顺序）
+
+1. **设计真源**：[`docs/superpowers/specs/2026-04-23-laundry-desk-design.md`](docs/superpowers/specs/2026-04-23-laundry-desk-design.md)
+2. **当前阶段**：`~/pro/kb/projects/laundry-desk/status.md`
+3. **门禁清单**：`CLAUDE.md`（每期发版前对照逐项打勾）
+4. **代码红线**：`~/.claude/rules/common/coding-style.md`
+5. **审查侧重**：`AGENTS.md`（Codex 的关注点就是你要主动规避的坑）
+
+## 代码红线（硬性）
+
+| 项 | 红线 |
+|---|---|
+| TypeScript | `strict: true`，零 `any`，必要时用 `unknown` + Zod |
+| 文件 | ≤ 400 行 |
+| 函数 | ≤ 50 行 |
+| 嵌套 | ≤ 4 层 |
+| 金额 | 一律 `int`（分），禁浮点 |
+| 密钥 | 不入代码、不入库明文（M4 用 `keytar`） |
+| IPC | 入参过 Zod，返回 `{ ok: true, data } \| { ok: false, error: { code, message } }` |
+| Electron | `contextIsolation: true` / `nodeIntegration: false` / `sandbox: true` / 严格 CSP |
+| 不可变 | 数据操作返回新对象，避免就地修改 |
+
+## 目录骨架（M1 一次落盘）
+
+```
+src/
+  main/        # Node 主进程：index.ts / window.ts / db / services / ipc
+  preload/     # 桥接：暴露 window.api
+  renderer/    # React UI：routes / components / stores / lib / styles
+  shared/      # 共享类型 + Zod + 错误码
+tests/
+  unit/        # Vitest：对 services 单测
+  e2e/         # Playwright：覆盖本期核心路径
+```
+
+## 分期任务
+
+**按顺序做，不跳期。每期完成一轮"代码 → 测试 → CI 绿 → 实机冒烟 → 过门禁 → tag"。**
+
+### M1（v0.1.0）— 基础
+1. 脚手架：Electron + Vite + electron-vite + TS + Tailwind 4 + shadcn/ui + Framer Motion + Zustand + React Router 7
+2. Apple HIG 设计系统：字体、色彩 token、全局 CSS、基础组件（Button / Card / Input / Dialog / Sheet / Toast）
+3. DB 层：Drizzle schema + migrations（8 张表，见 spec §4）+ better-sqlite3 连接
+4. IPC 层：`orders` / `customers`（入参 Zod，返回统一信封）
+5. Service 层：`orderService`、`pickupCodeService`、`customerService`、`backupService`
+6. 页面：Home / Receive / Pickup / Orders / OrderDetail / Customers（暂空）/ Settings / Stats（暂空）/ Login（暂锁）
+7. 自动备份：node-cron 03:00 → WAL checkpoint → zip → rotate 30
+8. 构建：`electron-builder` NSIS，输出 `laundry-desk-Setup-0.1.0.exe`
+9. GitHub Actions：`windows-latest` 构建 + 上传 artifact
+10. 单测：`pickupCodeService` / `orderService.create` / `customerService.upsertByPhone`
+11. E2E：收件→取件的完整流程
+
+### M2（v0.2.0）— 收款 & 统计
+- `settings.price_templates` + 价格 autocomplete
+- 付款方式、折扣、欠款
+- 日/月报表（Recharts）、逾期未取列表
+- Excel 导入导出（exceljs）：客户 / 订单 / 明细
+
+### M3（v0.3.0）— 照片 & 打印
+- 收件页：调用摄像头 or 选本地文件，存 `userData/photos/YYYY-MM/<order>_<n>.jpg`
+- `PrinterDriver` 抽象 + 58mm ESC/POS 实现（`electron-pos-printer`）
+- 登记单模板：店名 / 单号 / 取件码 / 电话尾 4 位 / 明细表 / 总价
+- 取件条模板：取件码 / 单号 / 取件人 / 金额结清
+
+### M4（v0.4.0 → v1.0.0）— 员工 & 短信
+- Argon2 密码哈希，Login 页
+- 权限中间件（IPC handler 包装层）：admin 可进 Settings / Customers，staff 仅收件 / 取件
+- `audit_log` 全面绑定（每个写入 IPC）
+- 腾讯云 SMS Provider + settings 配置页 + `sms_log` + 订单详情"通知客户"按钮
+- **SecretKey 用 `keytar` 存 OS keychain，不入库**
+
+## 开发与提交流程
+
+1. 每期建一个分支：`feat/m1-base` / `feat/m2-payment-stats` / ...
+2. 小步提交，每个 commit 聚焦一件事
+3. 完成后本地跑：`pnpm typecheck && pnpm lint && pnpm test && pnpm test:e2e`
+4. Push → GH Actions `windows-latest` 绿灯 → 开 PR
+5. PR 描述里附 CLAUDE.md 的门禁清单勾选状态
+6. Claude 审 → Codex 关键点复审 → manpengan 走查 Windows 实机 → 合并 → tag release
+
+## 构建 & 发布命令
+
+```bash
+pnpm install              # 装依赖
+pnpm dev                  # Electron 开发态（Mac 用于开发）
+pnpm typecheck            # tsc --noEmit
+pnpm lint                 # eslint + prettier --check
+pnpm test                 # vitest run
+pnpm test:e2e             # playwright test
+pnpm build:win            # electron-builder --win nsis（本地冒烟）
+# 正式包走 GH Actions windows-latest workflow
+```
+
+## 遇到问题
+
+1. **better-sqlite3 native 模块**：`pnpm rebuild` + `electron-builder` 的 `buildDependenciesFromSource: false`
+2. **Apple 风样式在 Windows 下的降级**：`titleBarStyle` 和 vibrancy 在 Windows 下回退为实心圆角卡片，不强求毛玻璃
+3. **短信模板未审核**：M4 允许 `sms.enabled=false` 发版，模板过了再开
+4. **Bug 卡住 > 1 小时**：在 PR 评论 `@codex` 请求关键点二审
+
+## 不做
+
+- 不改 spec（有改动要求找 Claude 走 brainstorm 流程）
+- 不跳期做后面的功能
+- 不关 TS strict / 不用 `@ts-ignore` 压错
+- 不在 renderer 里 `require('better-sqlite3')` 或 `fs`
+- 不在代码里硬编码密钥、店名、路径
--- a/README.md
+++ b/README.md
@@ -0,0 +1,48 @@
+# laundry-desk
+
+洗衣店柜台管理系统 — 单店单机 Windows 桌面应用，Apple HIG 风格 UI。
+
+覆盖收件登记、取件、客户管理、收款、统计报表、物品拍照、58mm 热敏打印、腾讯云短信通知、多员工账号与审计全流程。
+
+## 状态
+
+| 项 | 值 |
+|---|---|
+| 阶段 | M0（设计完成，待 Gemini 实现 M1） |
+| 设计文档 | [docs/superpowers/specs/2026-04-23-laundry-desk-design.md](docs/superpowers/specs/2026-04-23-laundry-desk-design.md) |
+| 目标平台 | Windows 10 / 11（NSIS `.exe`） |
+| 开发平台 | macOS（GitHub Actions `windows-latest` 构建为准） |
+
+## 技术栈
+
+Electron 32 · React 19 · TypeScript 5 · Tailwind CSS 4 · shadcn/ui · Framer Motion 11 · Zustand · Drizzle ORM · better-sqlite3 · Vite · electron-builder · Recharts · Playwright · Vitest
+
+## 路线图
+
+| 期 | Tag | 范围 |
+|---|---|---|
+| M1 | `v0.1.0` | 骨架 + Apple UI + 收件/取件/列表/详情 + 客户去重 + 自动备份 + Windows 打包 |
+| M2 | `v0.2.0` | 价格模板 + 按件计费 + 付款/欠款 + 日/月报表 + 逾期 + Excel 导入导出 |
+| M3 | `v0.3.0` | 收件拍照 + 58mm 热敏打印登记单 / 取件条 |
+| M4 | `v0.4.0` → `v1.0.0` | 登录 + 权限 + 审计 + 腾讯云 SMS |
+
+## 分工
+
+- **Claude**（Opus 4.7）— brainstorm / spec / 门禁验收 / code review — 见 [CLAUDE.md](CLAUDE.md)
+- **Codex** — 关键节点技术二审（架构 / 安全 / 并发）— 见 [AGENTS.md](AGENTS.md)
+- **Gemini** — 主力实现、测试、修 build — 见 [GEMINI.md](GEMINI.md)
+- **manpengan** — 决策 / UI 走查 / 发版
+
+## 开发（Gemini 实现 M1 后补）
+
+```bash
+pnpm install
+pnpm dev            # Electron 开发态
+pnpm build:win      # 打包 Windows .exe
+pnpm test           # Vitest 单测
+pnpm test:e2e       # Playwright E2E
+```
+
+## License
+
+私有项目（manpengan 个人所有）。