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>
This commit is contained in:
manpengan
120
GEMINI.md
Normal file
120
GEMINI.md
Normal file
@@ -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`
|
||||
- 不在代码里硬编码密钥、店名、路径
|
||||
Reference in New Issue
Block a user