171 lines
13 KiB
Markdown
171 lines
13 KiB
Markdown
---
|
||
title: laundry-desk 设计文档
|
||
date: 2026-04-23
|
||
status: approved (M0 — 待 Gemini 实现)
|
||
authors: claude (brainstorm), manpengan (decision)
|
||
---
|
||
|
||
# laundry-desk — 洗衣店柜台管理系统
|
||
|
||
## 1. 目标与场景
|
||
|
||
单店单机 Windows 桌面系统，覆盖洗衣店柜台全流程：收件登记 / 取件 / 客户 / 收款 / 统计 / 打印 / 短信。
|
||
|
||
- 运行：Windows 10/11（NSIS `.exe` 安装器）
|
||
- 开发：macOS 交叉打包（GitHub Actions `windows-latest` 为准）
|
||
- 数据：本地 SQLite（WAL + 每日自动备份）
|
||
|
||
**典型场景：**
|
||
|
||
- 收件：查回头客 → 录物品明细 → 计价收款 → 生成 4 位取件码 → 打印登记单
|
||
- 取件：客户报取件码 / 电话 / 单号 → 查询 → 收尾款 → 标记已取 → 打印取件条
|
||
- 管理：店主查看日/月营业额、逾期未取、回头率
|
||
|
||
## 2. 范围
|
||
|
||
**In Scope（v1.0.0）：** 收件、取件、订单列表、客户自动去重（按电话）、按件计费、付款方式与欠款、日/月统计、逾期未取、58mm 热敏打印、物品照片、腾讯云 SMS、多员工账号 + 审计日志、Excel 导入导出、自动备份。
|
||
|
||
**Out of Scope：** 多门店 / 云端同步 / 会员积分储值 / 微信小程序 / RFID / 自动称重。
|
||
|
||
## 3. 技术栈
|
||
|
||
| 层 | 选型 |
|
||
| -------- | -------------------------------------------------- |
|
||
| 应用框架 | Electron 32+ |
|
||
| 前端 | React 19 + TypeScript 5 (strict) |
|
||
| UI | Tailwind CSS 4 + shadcn/ui |
|
||
| 动效 | Framer Motion 11 |
|
||
| 字体 | SF Pro Display/Text + PingFang SC |
|
||
| 状态 | Zustand |
|
||
| 路由 | React Router 7 |
|
||
| 数据库 | better-sqlite3 + Drizzle ORM |
|
||
| 密码哈希 | @node-rs/argon2 |
|
||
| 构建 | Vite + electron-vite |
|
||
| 打包 | electron-builder（NSIS） |
|
||
| 图表 | Recharts |
|
||
| 打印 | electron-pos-printer（58mm ESC/POS） |
|
||
| 短信 | @tencentcloud/tencentcloud-sdk-nodejs-sms |
|
||
| Excel | exceljs |
|
||
| 测试 | Vitest（单测）+ Playwright（E2E） |
|
||
| CI | GitHub Actions（`windows-latest` 构建 + artifact） |
|
||
|
||
**UI 视觉规范（Apple HIG）：** SF Pro + PingFang SC、圆角 12–16px、半透明/毛玻璃卡片、macOS System Colors（`systemBlue #007AFF` 等）、Framer Motion 过渡、深色模式跟随系统、窗口 `titleBarStyle: 'hiddenInset'`（Mac 开发态）/ Windows 下降级为圆角无边框。
|
||
|
||
## 4. 数据模型（SQLite + Drizzle）
|
||
|
||
金额一律用**整数分**存储（杜绝浮点）。
|
||
|
||
| 表 | 关键字段 |
|
||
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `customers` | id, name, phone (unique), vip_level, total_orders, total_spent, created_at, updated_at |
|
||
| `orders` | id, order_no (unique, `YYYYMMDD-NNNN`), pickup_code (char(4)), customer_id (fk), status (pending/ready/picked_up/cancelled), total_amount, paid_amount, payment_method (cash/wechat/alipay/card/unpaid), receive_date, expected_pickup_date, actual_pickup_at, staff_id (fk), picked_up_by (fk nullable), notes, created_at, updated_at |
|
||
| `order_items` | id, order_id (fk cascade), item_type, service_type (wash/dry_clean/iron), quantity, unit_price, subtotal, item_notes |
|
||
| `order_photos` | id, order_id (fk cascade), file_path (相对 userData), taken_at |
|
||
| `staffs` | id, username (unique), password_hash (Argon2), display_name, role (admin/staff), is_active, created_at, last_login_at |
|
||
| `sms_log` | id, order_id (fk), phone, content, status (pending/sent/failed), provider_response (json), sent_at |
|
||
| `settings` | key (pk), value (json), updated_at |
|
||
| `audit_log` | id, staff_id (fk nullable), action (create/update/delete/pickup/cancel/login/export), entity, entity_id, diff (json), created_at |
|
||
|
||
**索引：** `orders(pickup_code)`、`orders(customer_id, status, receive_date)`、`audit_log(created_at)`、`customers(phone) unique`、`orders(order_no) unique`。
|
||
|
||
**取件码策略：** 00:00 重置当日池，随机 4 位数字，事务内冲突重试 ≤ 3 次（单店同日 1 万单封顶完全够用）。
|
||
|
||
**订单号策略：** `YYYYMMDD-NNNN` 顺序号（事务内 `SELECT max(nnnn)+1`，同日 9999 封顶）。
|
||
|
||
**默认 settings keys：** `shop.name`、`shop.address`、`printer.enabled`、`printer.width`、`sms.enabled`、`sms.tencent.secret_id`、`sms.tencent.secret_key`（M4 加密存储）、`sms.template_id`、`price_templates`（JSON 数组）。
|
||
|
||
**备份：** `%APPDATA%/laundry-desk/backups/` 下每日 03:00 zip `.db`，保留最新 30 份滚动删除；设置页提供"立即备份 / 从备份还原"。
|
||
|
||
## 5. 架构分层
|
||
|
||
```
|
||
src/
|
||
main/ # Node 主进程（持有 DB）
|
||
db/ # Drizzle schema / migrations / backup
|
||
services/ # 业务逻辑（无 Electron 依赖，可单测）
|
||
ipc/ # IPC handlers，按领域分组
|
||
window.ts
|
||
index.ts
|
||
preload/ # 桥接，暴露类型安全 window.api
|
||
renderer/ # React UI
|
||
routes/ # Home / Receive / Pickup / Orders / OrderDetail / Customers / Stats / Settings / Login
|
||
components/ui/ # shadcn/ui 定制
|
||
stores/ # Zustand
|
||
lib/api.ts # window.api 封装
|
||
styles/globals.css
|
||
shared/ # main ↔ renderer 共享类型 + Zod schema + 错误码
|
||
tests/
|
||
```
|
||
|
||
**硬约束：**
|
||
|
||
- `contextIsolation: true` / `nodeIntegration: false` / `sandbox: true` / CSP 严格
|
||
- Renderer 零 Node/DB 访问，全走 IPC
|
||
- IPC 命名 `<domain>:<action>`（如 `orders:create`）；入参一律过 Zod；返回 `{ ok: true, data } | { ok: false, error: { code, message } }`
|
||
- Service 层无 Electron 依赖；接受 db client 注入（测试用 in-memory SQLite）
|
||
- 单文件 ≤ 400 行、函数 ≤ 50 行、嵌套 ≤ 4 层；金额零浮点；无硬编码密钥
|
||
|
||
## 6. 核心工作流
|
||
|
||
### 6.1 收件
|
||
|
||
电话查回头客 → 明细多行 → 付款方式 + 实收 → 事务生成 `pickup_code` + `order_no` → 写 `orders` + `order_items`（+ 可选 `order_photos`）→ 更新 `customers.total_orders/total_spent` → `audit_log` → （M3）打印登记单。
|
||
|
||
### 6.2 取件
|
||
|
||
取件码（优先）/ 电话 / 单号 / 姓名查询 → 多条时列表选 → 有欠款先收 → `status = picked_up`、`actual_pickup_at`、`picked_up_by` → `audit_log` → （M3）打印取件条。
|
||
|
||
### 6.3 自动备份
|
||
|
||
`app.ready` 启动 `node-cron` 03:00 → `PRAGMA wal_checkpoint(TRUNCATE)` → 复制 `.db` → zip → 滚动保留 30 份。
|
||
|
||
### 6.4 短信通知（M4）
|
||
|
||
手动/批量触发 → Service 调腾讯云 SMS SDK → 写 `sms_log`（pending → sent/failed）→ 状态回填订单详情。
|
||
|
||
## 7. 分期路线图
|
||
|
||
| 期 | Tag | 交付 |
|
||
| ------ | ------------------- | ------------------------------------------------------------------------------------------------- |
|
||
| **M1** | `v0.1.0` | 项目骨架 + Apple HIG 设计系统 + 收件/取件/列表/详情 + 客户自动去重 + 自动备份 + Windows NSIS 打包 |
|
||
| **M2** | `v0.2.0` | 价格模板 + 按件计费 + 折扣 + 付款/欠款 + 日/月报表（Recharts）+ 逾期未取 + Excel 导入导出 |
|
||
| **M3** | `v0.3.0` | 收件拍照（1–3 张，存 `userData/photos/YYYY-MM/`）+ 58mm 热敏打印登记单 / 取件条 |
|
||
| **M4** | `v0.4.0` → `v1.0.0` | 登录（Argon2）+ 权限（admin/staff）+ 审计日志全面绑定 + 腾讯云 SMS 可取件通知（可关闭） |
|
||
|
||
## 8. 验收门禁（每期必过）
|
||
|
||
**质量：** TS strict 零错、ESLint/Prettier 零警、文件/函数/嵌套红线、无硬编码密钥、所有 IPC 过 Zod。
|
||
**测试：** Service 单测覆盖率 ≥ 70%、Playwright E2E 覆盖本期核心路径、备份可从 zip 还原到新安装。
|
||
**交付：** GH Actions `windows-latest` 构建绿灯；Windows 10/11 实机冒烟（manpengan）；`.exe` 大小记录基线；GitHub Release 附安装器 + SHA256。
|
||
**文档：** `README.md` 截图更新；`docs/CHANGELOG.md` 本期条目。
|
||
|
||
## 9. 分工
|
||
|
||
| 角色 | 职责 | 工具 |
|
||
| --------------------- | ------------------------------------------ | ----------- |
|
||
| **Claude (Opus 4.7)** | brainstorm / spec / 门禁验收 / code review | Claude Code |
|
||
| **Codex** | 关键节点二次审查（架构 / 安全 / 并发） | Codex CLI |
|
||
| **Gemini** | M1~M4 主力实现、测试编写、修 build | Gemini CLI |
|
||
| **manpengan** | 决策 / UI 走查 / 发版 | — |
|
||
|
||
**节奏：** 每期开始 Claude 在 milestone issue 补实施细节 → Gemini 提 PR → Claude 审 → Codex 关键点复审 → Claude 过门禁清单 → manpengan tag release。
|
||
|
||
## 10. 风险与缓解
|
||
|
||
| 风险 | 缓解 |
|
||
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
|
||
| Mac 交叉打 Windows exe，better-sqlite3 native 模块失败 | GH Actions `windows-latest` 为准；本地 `pnpm rebuild`；electron-builder `buildDependenciesFromSource: false` |
|
||
| 打印机型号差异 | M3 抽象 `PrinterDriver` 接口，先支持 58mm 通用 ESC/POS，型号配置化 |
|
||
| 腾讯云 SMS 模板审核周期 | Provider 可替换；模板 id 从 settings 读；无短信时仍可发版 |
|
||
| SQLite 单文件损坏 | WAL + 每日 zip + 备份校验任务 |
|
||
| Electron XSS → 任意代码 | contextIsolation + sandbox + CSP + 所有 IPC 过 Zod |
|
||
| 密钥泄漏（短信 SecretKey） | M4 用 OS keychain（`keytar`）加密存储，非明文入库 |
|
||
|
||
## 11. 假设
|
||
|
||
单店单机；日单量 ≤ 1000；员工 ≤ 10；打印机 58mm ESC/POS 兼容；柜台机器可联外网（为 SMS / 备份到外部 NAS 留空间，v1 不做）；GitHub 用户名 `manpengan`，仓库 **public**。
|
||
|
||
## 12. Open Questions
|
||
|
||
无。后续变更走 `docs/adr/YYYY-MM-DD-<topic>.md`。
|