From 20595a754581ce32363f6c5698f35935bf76451b Mon Sep 17 00:00:00 2001 From: manpengan Date: Thu, 23 Apr 2026 09:36:09 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20add=20README=20+=20=E4=B8=89=20AI=20?= =?UTF-8?q?=E5=85=A5=E5=9C=BA=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README.md: 项目状态 + 路线图 + 分工 - CLAUDE.md: Claude 职责 + 门禁清单 + Review 重点 - AGENTS.md: Codex 二审侧重（M1 安全 / M4 密钥 / 并发点） - GEMINI.md: Gemini 分期实施清单 + 红线 + 工作流 Co-Authored-By: Claude Opus 4.7 --- AGENTS.md | 61 +++++++++++++++++++++++++++ CLAUDE.md | 69 +++++++++++++++++++++++++++++++ GEMINI.md | 120 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 48 ++++++++++++++++++++++ 4 files changed, 298 insertions(+) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 100644 GEMINI.md create mode 100644 README.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..48a6190 --- /dev/null +++ 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 合并） diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..df931e5 --- /dev/null +++ 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-.md` + 更新 spec 版本 +- 路线图变更 → 更新本文件 & `README.md` 路线表 +- 新风险 → 补 spec §10 + +## 不做 + +- 不直接改 `src/` 下的实现代码（Gemini 负责） +- 不装 npm 依赖 +- 不跑 `pnpm build` +- 不跳阶段（按 M1 → M2 → M3 → M4 顺序） diff --git a/GEMINI.md b/GEMINI.md new file mode 100644 index 0000000..dd058b0 --- /dev/null +++ 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/_.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` +- 不在代码里硬编码密钥、店名、路径 diff --git a/README.md b/README.md new file mode 100644 index 0000000..d8fa887 --- /dev/null +++ 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 个人所有）。