项目流程图
本文从业务视角梳理 kxmall 生鲜前置仓商城的整体架构与核心流程，便于向客户或新同学讲解「系统怎么跑起来」。
一句话概括：
用户按定位匹配最近前置仓下单并支付 → 仓库配货出库 → 自提 / 自营骑手 / 达达或顺丰送达 → 确认收货、评价、积分与分销 → 需要时可售后或开票。
# 系统总体架构
三端共用一套后端，按仓库（前置仓）就近履约。
flowchart TB
subgraph 客户端
A1[用户端 uni-app<br/>小程序 / H5 / App]
A2[骑手端 uni-app<br/>小程序 / H5 / App]
A3[管理后台 Vue + Element UI]
end
subgraph 后端服务 Spring Boot
B1[kxmall-app-api<br/>用户接口]
B2[kxmall-rider-api<br/>骑手接口]
B3[kxmall-admin-api<br/>管理接口]
B4[kxmall-system / framework / common<br/>订单、仓储、支付、通知]
end
subgraph 基础设施
C1[(MySQL)]
C2[(Redis)]
C3[Nginx]
C4[对象存储 OSS]
end
subgraph 外部能力
D1[微信支付 / 支付宝]
D2[达达配送]
D3[顺丰同城]
D4[短信 / 云打印]
end
A1 --> B1
A2 --> B2
A3 --> B3
B1 --> B4
B2 --> B4
B3 --> B4
B4 --> C1
B4 --> C2
B4 --> C4
B4 --> D1
B4 --> D2
B4 --> D3
B4 --> D4
# 业务全景
flowchart LR
subgraph 前台运营
U[用户下单]
M[营销活动<br/>秒杀 / 团购 / 优惠券]
K[在线客服]
F[发票申请]
end
subgraph 履约中心
W[前置仓配货]
S[仓储库存 / 货架 / 批次]
D[配送出库]
end
subgraph 末端配送
R1[自营骑手]
R2[达达 / 顺丰同城]
R3[门店自提]
end
U --> W
M --> U
W --> S
W --> D
D --> R1
D --> R2
D --> R3
U --> K
U --> F
# 用户购物主流程
核心逻辑：先按定位匹配配送范围内的仓库，再看该仓库库存下单。
flowchart TD
A[打开小程序 / H5 / App] --> B[获取定位]
B --> C{是否在某仓库配送范围内?}
C -->|是| D[匹配最近前置仓]
C -->|否| E[提示超范围 / 换地址]
D --> F[浏览首页 / 分类 / 搜索]
F --> G[商品详情]
G --> H{立即购买 or 加购?}
H -->|加购| I[购物车]
I --> J[结算页]
H -->|立即购买| J
J --> K{配送 or 自提?}
K -->|配送 shippingType=1| L[选择收货地址 + 预计送达时间]
K -->|自提 shippingType=2| M[选择提货仓]
L --> N[选优惠券 / 积分]
M --> N
N --> O[提交订单]
O --> P{支付方式}
P -->|微信 / 支付宝| Q[拉起支付]
P -->|余额 / 积分| R[下单时直接扣款]
Q --> S[支付回调成功]
R --> T[进入待配货]
S --> T
支付渠道：微信、支付宝、余额、积分。
支付场景：小程序、公众号 H5、App。
# 订单全生命周期
订单状态见 OrderStatusType：
| 状态码 | 含义 |
|---|---|
| 10 | 未付款 |
| 12 | 等待团购结束 |
| 14 | 等待配货 |
| 16 | 配货中 |
| 20 | 待出库 |
| 30 | 待收货 |
| 32 | 配送异常 |
| 34 | 配送超时 |
| 40 | 待评价 |
| 50 | 已完成 |
| 60 | 退款中 |
| 70 | 已退款 |
| 80 | 已取消 |
| 90 | 系统取消 |
flowchart TD
A[用户提交订单] --> B{支付?}
B -->|未付| C[未付款 10]
C -->|超时未付<br/>定时任务| Z1[系统取消 90<br/>回滚库存]
C -->|用户取消| Z2[已取消 80]
B -->|团购未结束| D[等待团购结束 12]
D -->|成团| E[等待配货 14]
D -->|失败| Z3[自动退款]
B -->|支付成功| E
E --> F[仓库开始配货 16]
F --> G[完成配货 / 待出库 20]
G --> H{履约方式}
H -->|门店自提| I[用户到店核销]
I --> J[待评价 40]
H -->|商家配送| K[分配骑手 / 商家自配]
K --> L[待收货 30]
H -->|第三方配送<br/>达达 / 顺丰| M[创建三方运单]
M --> L
L -->|骑手完成 / 用户确认<br/>或超时自动确认| J
L -->|异常| N[配送异常 32]
L -->|超时| O[配送超时 34]
J -->|用户评价| P[已完成 50]
P --> Q[发放积分 / 分销佣金]
P --> R[可申请发票]
E -.->|配货前可退| S[退款中 60]
F -.->|配货中可退| S
G -.->|待出库可退| S
S --> T[已退款 70]
仓库后台对应操作：
- 开始配货：14 → 16
- 完成配货：16 → 20
- 出库后走自提 / 商家配送 / 第三方配送
- 称重退差价：生鲜按实际重量退差价
# 配送流程
履约方式有三种：门店自提、商家配送（含自营骑手）、第三方配送（达达 / 顺丰同城）。
flowchart TD
A[订单待出库 20] --> B{shippingType}
B -->|2 门店自提| C[生成提货码]
C --> D[用户到店]
D --> E[仓库核销提货]
E --> F[待评价]
B -->|1 配送| G{配送渠道}
G -->|商家自配| H[商家配送]
H --> I{是否派给自营骑手?}
I -->|是| J[分配骑手]
I -->|否| K[商家自行送达]
J --> L[骑手待取货]
L --> M[开始配送]
M --> N[送达完成]
K --> N
N --> F
G -->|第三方| O[取默认配送配置]
O --> P{达达 or 顺丰同城}
P --> Q[策略模式创建运单]
Q --> R[待收货 30]
R --> S[三方回调更新轨迹]
S --> N
自营骑手状态：待取货 → 配送中 → 已完成；另有超时、异常、被改派。
# 仓储与库存
按「仓库覆盖范围」卖货，库存是仓维度，不是全站一份库存。
flowchart TD
A[后台维护仓库] --> B[绘制配送电子围栏]
B --> C[设置营业状态 / 营业时间]
C --> D[货架货位管理]
E[采购入库单] --> F[待入库]
F --> G[确认入库]
G --> H[更新仓库库存]
H --> I[绑定货架 / 批次]
I --> J[库存预警]
K[用户下单锁库存] --> L[配货按货架拣货]
L --> M[出库扣减]
M --> N[配送 / 自提]
O[退款 / 取消] --> P[回滚库存]
相关能力：仓库、库存、入库、出库、货架、批次、库存预警。
# 售后流程
flowchart TD
A[用户申请售后] --> B[已提交，待平台审核]
B -->|用户撤销| Z[关闭]
B --> C{后台审核}
C -->|拒绝| D[结束]
C -->|通过| E[平台已审核]
E --> F{仅退款 or 退货退款}
F -->|仅退款| G[原路退款]
F -->|退货| H[用户发货]
H --> I[仓库收货确认]
I --> G
G --> J[已完成]
订单侧：配货前～待出库可退；完成后走售后单。
# 发票流程
flowchart TD
A[用户选已完成订单] --> B[填写抬头<br/>公司 / 个人]
B --> C[提交申请 待审核]
C --> D{财务审核}
D -->|拒绝| E[用户可修改后重提]
E --> C
D -->|通过| F[开具发票]
F --> G[邮件送达 / 用户查看]
# 骑手作业
flowchart TD
A[骑手登录] --> B[开工 / 休息]
B -->|开工| C[接收仓库派单]
C --> D[待取货]
D --> E[到仓取货，开始配送]
E --> F{能否送达?}
F -->|能| G[到达签收]
G --> H[订单待评价]
G --> I[骑手钱包入账]
I --> J[提现申请]
J --> K[后台审核打款]
F -->|不能| L[上报异常]
L --> M[后台改派或其他处理]