配送补给
云桥门店 · 杭州
早上好，林经理
库存预计可用 12 天
2 类耗材接近安全库存，请及时补货
库存提醒
抽纸 · 预计 3 天见底当前 24 箱，建议补货 20 箱
洗手液 · 预计 12 天当前 50 桶，消耗趋势稳定
进行中的配送
配送中#PS20260921008司机已出发 · 预计 18:30 前送达
Product & Technical Design · v1.0
面向个人与企业客户的货物配送小程序
一个小程序承载客户下单、库存消耗预测、商家经营管理和配送履约；配套 React PC 管理后台，后端采用 Spring Boot + MyBatis + Redis + MySQL。
一、方案结论
首期目标不是做一个复杂平台，而是把“客户持续消耗 → 预测见底 → 商家接单 → 商家配送 → 结算与统计”跑通。配送员是可选角色，没有配送员时由商家直接完成履约。
小程序Vue 3 + uni-app
一套代码覆盖微信小程序，并保留 H5 扩展能力。
商家后台React + Vite
桌面端适合订单表格、报表导出和权限配置。
服务端Spring Boot
模块化单体起步，后续可拆分，不提前引入微服务复杂度。
数据层MySQL + Redis
MySQL 做事实数据，Redis 做缓存、幂等、提醒任务和限流。
关键决策：首期不强制创建配送员账号。订单的履约人可以是商家本人、商家员工或配送员，字段允许为空；这样不会因为人员配置不足阻塞业务。
二、系统总体架构
建议采用“模块化单体 + 清晰领域边界”。早期部署和排错简单，业务量上升后可以按模块拆分服务。
微信小程序 · uni-app客户、商家、可选配送员；角色权限控制页面和操作
React PC 管理后台商品、客户、订单、配送、结算、统计、系统设置
通知通道小程序订阅消息、短信/企业微信可选
Spring Boot API
认证与权限 · 客户与商家 · 商品库存 · 订单支付 · 配送履约 · 消耗预测 · 统计报表
REST + SSE 可选MySQL用户、组织、商品、订单、支付、配送、消耗、统计事实
Redis登录会话、验证码、库存缓存、幂等键、提醒队列、限流
第三方服务微信登录/支付、地图导航、对象存储、消息服务
推荐目录边界
// 后端
src/main/java/com/example/delivery/
common/ # 统一响应、异常、分页、审计
auth/ # 微信登录、JWT、RBAC
tenant/ # 商家/组织/门店
customer/ # 客户档案、地址、消耗填报
product/ # 品类、商品、价格、库存
order/ # 订单、订单明细、状态流转
payment/ # 线上支付、授信、月结、退款
delivery/ # 履约人、配送任务、签收、异常
forecast/ # 日消耗、可用天数、安全库存
report/ # 日/月/季/年聚合与排行
notification/ # 低库存、订单、支付、异常通知
scheduler/ # 定时聚合与提醒任务
三、角色与小程序 UI
微信原生风格的可交互原型。选择角色后，可通过左侧页面目录或手机底部 TabBar 浏览完整工作区。
角色之间导航不同，但同一角色的 TabBar、状态颜色和操作层级保持一致。配送员仍为可选角色，商家可以直接完成配送。
09:41
09:41
09:41
角色策略：配送员工作区是可选能力。没有配送员账号时，商家在“履约”页面直接点击“我来配送”；有员工后再启用任务分配，不阻塞首期上线。
四、核心业务流程
每条流程都必须有可追踪状态、操作人和审计记录，避免只改一个“已完成”字段导致无法对账。
4.1 客户下单到完成配送
1. 创建订单选择商品、地址、支付方式；校验价格和库存快照。
2. 支付/授信个人线上支付；企业检查授信额度，允许月结或货到付款。
3. 商家接单确认订单，生成备货任务；拒单需记录原因。
4. 分配履约人商家点击“我来配送”，或分配给员工/配送员。
5. 配送签收导航、联系客户、拍照/签名、异常上报。
6. 完成结算线上支付自动完成；月结订单进入账期和对账单。
4.2 消耗预测与补货提醒
聚合历史消耗
按客户 + 商品统计近 7/30/90 天有效消耗量，剔除取消订单和异常填报。
按客户 + 商品统计近 7/30/90 天有效消耗量，剔除取消订单和异常填报。
更新当日消耗
客户可填写“今日消耗数量”和“当前盘点库存”；保留修改记录。
客户可填写“今日消耗数量”和“当前盘点库存”；保留修改记录。
计算预计可用天数
预计可用天数 = 当前可用库存 ÷ 平滑日均消耗；消耗不足时使用品类默认值。
预计可用天数 = 当前可用库存 ÷ 平滑日均消耗；消耗不足时使用品类默认值。
低库存通知
当预计可用天数 ≤ 安全天数，通知客户和商家；同一商品同一客户在 24 小时内去重。
当预计可用天数 ≤ 安全天数，通知客户和商家；同一商品同一客户在 24 小时内去重。
首期预测边界：这是可解释的规则预测，不宣称 AI 精准预测。先让客户能修正数据，再积累足够样本；未来可以替换为季节性模型，但不改变前端接口。
五、核心数据模型
所有业务表建议带 `tenant_id`，即使首期只有一个商家，也为后续多商家隔离预留。金额使用分为单位，数量使用高精度 decimal。
| 表 | 关键字段 | 用途 | 重要约束 |
|---|---|---|---|
| tenant | id, name, status, settlement_config | 商家/组织租户 | 所有商家数据按 tenant_id 隔离 |
| user / user_role | id, openid, mobile, role, tenant_id | 微信用户与 RBAC | customer 可跨组织；merchant_staff 绑定租户 |
| customer_profile | id, user_id, customer_type, credit_limit, settlement_type | 个人/企业客户档案 | customer_type: PERSONAL / BUSINESS |
| product_category / product | category_id, sku, name, unit, price, safety_days | 品类、商品、价格、安全线 | 订单保存商品和价格快照 |
| customer_inventory | customer_id, product_id, quantity, counted_at | 客户当前库存盘点 | 唯一键 customer_id + product_id |
| consumption_record | customer_id, product_id, quantity, source, recorded_at | 手动/订单/导入消耗 | source 区分 MANUAL、DELIVERY、IMPORT |
| sales_order / sales_order_item | order_no, customer_id, status, payment_status, total_amount | 订单主表和明细 | 状态只允许状态机迁移；金额不可直接覆盖 |
| payment / settlement_bill | payment_no, method, amount, paid_at, due_at | 线上支付、货到付款、月结 | 支付回调幂等；月结必须生成账单 |
| delivery_task | order_id, assignee_id, assignee_type, status, signed_at | 配送任务与签收 | assignee_id 可为空；商家自配送使用 tenant_user |
| inventory_alert | customer_id, product_id, level, predicted_days, notified_at | 低库存提醒去重 | 同一客户商品 24 小时内不重复推送 |
| daily_stat | tenant_id, stat_date, orders, quantity, amount | 日汇总事实 | 月/季/年由日事实聚合，避免重复口径 |
订单状态机
CREATED → PENDING_PAYMENT → PAID → ACCEPTED → PREPARING → READY_FOR_DELIVERY → DELIVERING → DELIVERED → COMPLETED
↘ CANCELLED
↘ EXCEPTION → RESOLVED
// 月结订单：PAID 不代表收款完成，payment_status = CREDIT_PENDING，签收后进入 settlement_bill。
六、接口与后端实现
接口按业务域分组，统一返回 request_id，错误码可被小程序和 React 后台分别翻译。前端只依赖接口契约，不直接依赖数据库字段。
| 接口 | 用途 | 权限 | 关键行为 |
|---|---|---|---|
| POST /api/v1/auth/wechat-login | 微信登录换取 token | 公开 | 服务端校验 code，签发 access_token + refresh_token |
| GET /api/v1/me/workspace | 返回当前角色工作区 | 登录用户 | 根据 role 返回客户/商家/配送员导航和待办数量 |
| POST /api/v1/orders | 创建订单 | 客户 | 重新计算价格、库存、可用支付方式，写订单快照 |
| POST /api/v1/orders/{id}/accept | 商家接单 | 商家 | 乐观锁防重复接单，生成备货任务 |
| POST /api/v1/orders/{id}/delivery/claim | 我来配送 | 商家/员工 | delivery_task.assignee_type = TENANT_USER |
| POST /api/v1/orders/{id}/delivery/assign | 分配履约人 | 商家 | 可分配员工或配送员；校验租户关系 |
| POST /api/v1/orders/{id}/sign | 签收并上传凭证 | 履约人 | 签收图片先入对象存储，成功后更新订单状态 |
| POST /api/v1/consumption-records | 提交手动消耗 | 客户 | 校验商品归属，记录来源和操作者 |
| GET /api/v1/inventory/forecast | 库存可用天数 | 客户/商家 | 缓存 5 分钟；返回预测值、依据和更新时间 |
| GET /api/v1/reports/overview | 经营统计 | 商家 | 按 range=daily|monthly|quarterly|yearly 聚合 |
| POST /api/v1/payments/wechat/notify | 微信支付回调 | 微信服务 | 验签、幂等、更新支付状态、投递订单事件 |
统一响应与异常
{ "code": "OK", "message": "success", "data": {}, "request_id": "req_20260921_xxx" }
# 典型错误：AUTH_EXPIRED、FORBIDDEN_ROLE、ORDER_STATE_CONFLICT、PAYMENT_REQUIRED、CREDIT_LIMIT_EXCEEDED、IDEMPOTENCY_REPLAY
七、支付与结算方案
支付不强行统一。客户类型、商家授信和订单金额共同决定可用结算方式。
个人客户
默认微信支付，下单后支付。支持支付超时取消、退款和支付凭证。
推荐默认
企业/门店客户
商家审核后授信，可选择货到付款或月结。每月生成对账单，支持部分核销。
授信可用
异常与风控
授信余额不足不可提交月结订单；退款、取消、异常签收都需要操作记录。
必须审计
支付配置关系
| 客户类型 | 默认方式 | 可选方式 | 完成条件 |
|---|---|---|---|
| 个人 | 线上支付 | 商家配置的货到付款 | 线上支付回调成功，或商家确认现金收款 |
| 企业/门店 | 月结/货到付款 | 线上支付 | 授信订单签收后入账；账单核销后已结算 |
不要把“订单已完成”和“款项已结清”混为一个状态。订单状态描述履约，payment_status 描述收款，settlement_status 描述企业对账。三者分开才能支持月结、部分退款和欠款提醒。
八、商家统计口径
所有统计默认按商家租户隔离，时间以商家配置时区为准。金额按订单明细实际成交金额，不用商品当前价格回算历史。
时间维度
日自然日 00:00–23:59
月自然月累计
季自然季度累计
年自然年累计
核心指标
累计商品配送SUM(delivered_quantity)
品类消耗情况按 category_id 聚合
总消耗金额SUM(actual_amount)
配送完成率completed / accepted
排行指标
消耗最多用户
按客户累计消耗数量或金额排序，可切换个人/企业。
消耗金额最高商品
订单明细金额按 SKU 聚合，商品改名不影响历史快照。
消耗最多金额用户
按实付金额 + 已确认月结金额统计，未确认账单单独标识。
实现建议：订单完成时写入 daily_stat 明细，夜间任务补偿重算；报表先查日汇总，明细下钻再查订单。这样手机端响应稳定，PC 导出不会压垮交易表。
九、权限、通知与部署
RBAC 权限
customer：自己的订单、库存、消耗、地址；
merchant_owner：全部经营数据、支付配置；
merchant_staff：被授权订单、履约和客户；
delivery_staff：分配给自己的任务；
admin：租户和系统级配置。
通知规则
低库存：客户 + 商家；订单状态：客户 + 当前履约人；支付回调：客户；月结到期：客户 + 商家财务；异常签收：商家 + 客户。通知失败写入重试队列。
安全与审计
JWT 短 token + refresh token；接口按租户隔离；支付回调验签；所有状态迁移写 order_event；敏感字段脱敏日志，签收图片走私有对象存储。
本地开发建议
# 1. 先启动依赖
docker compose up -d mysql redis
# 2. 启动 Spring Boot（开发环境）
./mvnw spring-boot:run -Dspring-boot.run.profiles=dev
# 3. 启动小程序端 / React 后台
cd apps/miniapp && pnpm install && pnpm dev:mp-weixin
cd apps/admin && pnpm install && pnpm dev
# 4. 验证
curl http://localhost:8080/actuator/health
curl http://localhost:8080/api/v1/products
分阶段实施
Phase 1 · 业务闭环 微信登录、客户下单、商品、订单、商家接单、商家自配送、线上支付/货到付款、基础统计。
Phase 2 · 消耗预测 客户库存、手动消耗填报、可用天数、安全库存、低库存通知、月结账单。
Phase 3 · 管理增强 React PC 报表、批量导入、员工权限、配送任务分配、签收图片、异常售后。
Phase 4 · 扩展能力 配送员独立角色、第三方同城配送、设备/扫码采集、多商家入驻和更复杂预测模型。
十、首期验收标准
客户可验收
能登录、维护地址、浏览商品、选择个人线上支付或企业授信方式、查看订单状态、填写日消耗、看到预计可用天数并收到低库存提醒。
商家可验收
能维护商品和客户、接单、点击“我来配送”、分配员工、完成签收、处理异常、查看日/月/季/年统计和客户/商品排行。
一致性验收
支付回调重复不会重复记账；订单状态不能跳跃；取消订单不会计入配送统计；月结订单与已收款订单分开统计。
上线前验收
完成微信支付沙箱/正式配置、隐私和订阅消息审核、备份恢复演练、接口限流、日志审计、移动端和 PC 端权限测试。