126 lines
6.1 KiB
Markdown
126 lines
6.1 KiB
Markdown
# 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`
|
||
- 不在代码里硬编码密钥、店名、路径
|