laundry-desk/GEMINI.md

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
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

构建 & 发布命令

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
• 不在代码里硬编码密钥、店名、路径