142 lines
7.6 KiB
Markdown
142 lines
7.6 KiB
Markdown
|
## 第一阶段：规格说明（Specification）
|
|||
|
|
|
|||
|
|
### 目标范围
|
|||
|
|
- 会员模块：会员档案、等级与折扣、积分累计与调整、优惠券、会员消费统计、收银台选会员
|
|||
|
|
- 库存管理：供应商管理、商品批次与保质期、库存预警（min_stock）、入出库记录与盘点、报表
|
|||
|
|
- 交班：交班记录、现金实点与系统金额核对、交班摘要打印/导出、交班数据留痕
|
|||
|
|
- 日结：每日营业汇总、支付方式统计、退款与挂单影响、库存快照、日报表打印/导出
|
|||
|
|
|
|||
|
|
### 用户故事与验收标准
|
|||
|
|
- 会员
|
|||
|
|
- 作为收银员，我可以通过手机号/姓名搜索并选择会员，订单将关联会员信息；验收：收银台勾选成功，订单详情显示会员信息，会员统计更新
|
|||
|
|
- 作为店长，我可以调整会员积分并查看积分历史；验收：积分变动入库，历史可分页查询，边界：负值调整、过期处理
|
|||
|
|
- 作为运营，我可以配置会员等级的折扣率；验收：订单最终金额按等级折扣计算，折扣记录可溯源
|
|||
|
|
- 库存
|
|||
|
|
- 作为仓管，我可录入供应商与商品批次，设置生产/过期日期；验收：批次入库同时更新商品库存，库存历史含批次、供应商与价格
|
|||
|
|
- 作为店长，我能看到30天内即将过期的批次；验收：列表按过期日期升序、数量>0、状态为active
|
|||
|
|
- 作为仓管，我能看到库存预警商品并生成补货建议；验收：按min_stock阈值计算，支持刷新
|
|||
|
|
- 交班
|
|||
|
|
- 作为收银员，我在结束班次时提交交班，系统对比现金实点与系统记录；验收：差异提示、交班记录持久化、打印小票/导出PDF
|
|||
|
|
- 日结
|
|||
|
|
- 作为店长，我每日进行日结，生成营业汇总与支付方式统计；验收：包含订单数、销售额、折扣额、退款额、各支付占比，支持打印/导出
|
|||
|
|
|
|||
|
|
### 非功能需求
|
|||
|
|
- 性能：订单创建接口P95 < 150ms；库存列表P95 < 200ms；渲染主界面首屏 < 2s
|
|||
|
|
- 安全：JWT密钥来源于环境变量（不硬编码）；前后端避免日志泄露敏感信息
|
|||
|
|
- 可维护性：拆分过大的路由文件（orders.js）为分域模块；统一Ant Design风格与交互
|
|||
|
|
- 测试：单元与集成测试覆盖率≥80%，路由与服务关键路径均有测试
|
|||
|
|
|
|||
|
|
### 数据模型与规则（概要）
|
|||
|
|
- Member：member_no, name, phone, level, points, total_consumption, total_orders, discount_rate, status
|
|||
|
|
- MemberPointsHistory：member_id, points_change, before/after, type, source_type, operator_id, expire_date
|
|||
|
|
- MemberCoupon：member_id, coupon_code, type, discount_value, status, used_order_id
|
|||
|
|
- Supplier：name, contact_person, phone, status, payment_method, bank信息
|
|||
|
|
- ProductBatch：product_id, supplier_id, batch_no, production_date, expiry_date, quantity, cost/selling_price, status
|
|||
|
|
- InventoryHistory：product_id, operation_type(in/out), quantity, stock_before/after, reason, supplier_id, batch_id
|
|||
|
|
- Order增加member_id，交班/日结新增域模型
|
|||
|
|
|
|||
|
|
### 风险与缓解
|
|||
|
|
- 数据一致性风险：入库/出库并发更新 → 事务与行级锁
|
|||
|
|
- 大文件维护难：orders.js过大 → 领域拆分与服务化
|
|||
|
|
- 硬件依赖不稳定：打印/串口 → 失败重试与降级提示
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 第二阶段：设计（Design）
|
|||
|
|
|
|||
|
|
### 架构图与分层
|
|||
|
|
- Electron主进程：窗口、串口、进程间通信
|
|||
|
|
- 渲染进程（React）：路由、页面（Cashier/Members/Inventory/Reports/Settings）、服务层axios
|
|||
|
|
- 后端（Express + Sequelize + SQLite）：routes（members/suppliers/batches/orders/shifts/closing），models，services（printer）
|
|||
|
|
- 状态：以局部state为主，服务拉取；后续评估引入轻量store（如Zustand）
|
|||
|
|
|
|||
|
|
### API规范（示例）
|
|||
|
|
- 会员
|
|||
|
|
- GET /api/members?page=&limit=&search=&level=&status=
|
|||
|
|
- POST /api/members；PUT /api/members/:id
|
|||
|
|
- POST /api/members/:id/points/adjust
|
|||
|
|
- GET /api/members/:id/points/history
|
|||
|
|
- GET /api/members/:id/stats
|
|||
|
|
- 库存
|
|||
|
|
- GET /api/suppliers；POST/PUT/DELETE /api/suppliers/:id
|
|||
|
|
- GET /api/batches?product_id=&supplier_id=&status=
|
|||
|
|
- POST/PUT/DELETE /api/batches/:id
|
|||
|
|
- GET /api/batches/expiring-soon?days=30
|
|||
|
|
- GET /api/products/low-stock
|
|||
|
|
- 交班/日结（新）
|
|||
|
|
- POST /api/shifts/start；POST /api/shifts/end
|
|||
|
|
- GET /api/shifts?date=&cashier_id=
|
|||
|
|
- POST /api/daily-closing/run?date=YYYY-MM-DD
|
|||
|
|
- GET /api/daily-closing/:date/report
|
|||
|
|
|
|||
|
|
### 安全与配置
|
|||
|
|
- JWT_SECRET、DB路径、打印机配置从环境注入（.env或配置文件），移除硬编码
|
|||
|
|
- axios拦截器仅在开发环境输出详细日志；生产降级
|
|||
|
|
|
|||
|
|
### 性能策略
|
|||
|
|
- 首屏路由懒加载（Members/Inventory/Reports）
|
|||
|
|
- 去除生产环境冗余console
|
|||
|
|
- 批量接口分页与筛选
|
|||
|
|
|
|||
|
|
### 错误与日志
|
|||
|
|
- 统一错误中间件返回结构：{error, code}
|
|||
|
|
- 后端logger统一等级与文件输出；避免请求体敏感字段写入
|
|||
|
|
|
|||
|
|
### 部署与运维
|
|||
|
|
- 打包：Webpack主/渲染配置复用；构建脚本区分dev/prod
|
|||
|
|
- 监控：运行日志与错误统计（文件落盘）
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 第三阶段：任务列表（Task List）
|
|||
|
|
|
|||
|
|
### 会员模块
|
|||
|
|
- 后端：Member/PointsHistory/Coupon模型与关联；members路由（列表/详情/创建/更新/积分调整/统计）
|
|||
|
|
- 前端：memberService；Members页面（列表、详情抽屉、积分调整）；Cashier会员搜索与选择、订单携带member_id
|
|||
|
|
- 测试：members路由supertest；积分调整边界测试
|
|||
|
|
|
|||
|
|
### 库存模块
|
|||
|
|
- 后端：Supplier/ProductBatch/InventoryHistory扩展模型与关联；suppliers、batches路由；products低库存与批次过期接口
|
|||
|
|
- 前端：supplierService、batchService；EnhancedInventory页面（历史/批次/供应商/过期预警）；StockWarning组件
|
|||
|
|
- 测试：库存历史入出库事务测试；过期批次筛选逻辑测试
|
|||
|
|
|
|||
|
|
### 交班模块
|
|||
|
|
- 模型：Shift（cashier_id, start_time, end_time, cash_counted, cash_system, diff, notes）
|
|||
|
|
- 接口：开始/结束交班、查询交班记录、打印交班小票
|
|||
|
|
- 前端：Cashier页交班入口与弹窗；Reports页交班查询
|
|||
|
|
- 测试：金额核对与差异计算、打印调用
|
|||
|
|
|
|||
|
|
### 日结模块
|
|||
|
|
- 模型：DailyClosing（date, totals: sales/discount/refund/pending, payments breakdown, inventory snapshot）
|
|||
|
|
- 接口：运行日结、查询日报表、打印/导出
|
|||
|
|
- 前端：Reports页新增日结Tab与报表展示
|
|||
|
|
- 测试：数据聚合正确性、挂单与退款影响核算
|
|||
|
|
|
|||
|
|
### 跨域任务
|
|||
|
|
- 重构：拆分orders.js为orders-basic、orders-stats、orders-print、orders-pending等
|
|||
|
|
- 安全：JWT密钥与配置管理；移除敏感日志
|
|||
|
|
- UI统一：导航新增Members/Inventory；遵循Ant Design规范与一致的卡片/表格/抽屉交互
|
|||
|
|
- 测试与CI：引入Jest/Vitest + supertest；GitHub Actions构建与测试；覆盖率≥80%
|
|||
|
|
|
|||
|
|
### 时间与优先级
|
|||
|
|
- Phase 1（1.5–2周）：会员 + 库存（供应商/批次/预警）
|
|||
|
|
- Phase 2（1周）：交班
|
|||
|
|
- Phase 3（1周）：日结
|
|||
|
|
- 持续：重构与安全、测试与CI、性能优化
|
|||
|
|
|
|||
|
|
### 完成标准
|
|||
|
|
- 所有API具备文档与错误处理；前后端功能稳定可用
|
|||
|
|
- 覆盖率≥80%，P95延迟满足目标；UI风格统一
|
|||
|
|
- 交付：规格说明与设计文档、任务列表、架构与流程图（Mermaid/PlantUML），可量化指标达标
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 可视化与指标
|
|||
|
|
- 架构图：Electron↔Express↔SQLite、渲染进程模块与路由
|
|||
|
|
- 流程图：会员积分调整流程、入库流水与库存更新、交班核对与打印、日结聚合
|
|||
|
|
- 指标：
|
|||
|
|
- 性能：P95接口与首屏、构建包大小<2MB渲染bundle（后续按需分割）
|
|||
|
|
- 质量：测试覆盖率≥80%、关键路由100%用例
|
|||
|
|
- 安全：零硬编码密钥、敏感日志为0
|
|||
|
|
|
|||
|
|
请确认以上三阶段规划；确认后我将严格按照该规划开始实施。
|