fulin/minishouyin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
master
minishouyin/.trae/documents/项目功能分析与改进实施计划.md
LIUFL a094f55890 docs: 整理文档并删除测试脚本 
将文档统一整理到doc目录下，删除不再需要的测试脚本和临时文件
2025-11-12 16:12:40 +08:00

7.6 KiB
Raw Permalink Blame History

第一阶段：规格说明（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

请确认以上三阶段规划；确认后我将严格按照该规划开始实施。