390 lines
16 KiB
Markdown
390 lines
16 KiB
Markdown
# 2026-02-05 / mall：配送-商家-消费者 数据流统一分析（SQL + 项目规范口径）
|
||
|
||
## 摘要
|
||
|
||
本文基于本仓库 **权威 SQL 目录** `docs/sql/`（并参考 `mall_sql/` 中的 `complete_mall_database.sql` 实现细节），结合项目工程与安全规范 `docs/project_spec/AGENT_PROJECT_SPEC.md`、`docs/sql/11_roles_and_permissions_strategy.md`，对 **消费者 / 商家 / 配送员** 三方在电商场景中的数据流运转进行统一分析。
|
||
|
||
输出内容包括：
|
||
|
||
- 三方域模型与关键表关系（文字版 ER）
|
||
- 端到端事件链路：下单、支付、履约配送、完成、评价
|
||
- 订单与配送状态机（字段口径与关键歧义点）
|
||
- 读模型（各端典型查询视角）
|
||
- 权限边界（RLS / RPC / 前端守卫）在本项目中的统一口径
|
||
|
||
> 本文为分析文档，不包含代码/SQL 变更。
|
||
|
||
---
|
||
|
||
## 动机
|
||
|
||
- 统一“谁能看/改什么数据”的口径：角色权威字段、RLS 与 RPC 的安全闭环要求必须一致。
|
||
- 统一“数据如何落表与流转”的口径：避免前后端/不同模块对订单、配送、商家模型理解不一致。
|
||
- 为后续落地（配置页、配送履约闭环、统计看板等）提供可审计的基础说明。
|
||
|
||
---
|
||
|
||
## 影响范围
|
||
|
||
- **数据库层**：`docs/sql/` 中的表结构、触发器、RLS、RPC 策略口径（本文不修改）。
|
||
- **前端工程层**：页面必须通过 `services/` 访问数据；admin/analytics 需通过 RPC 获取全局数据（本文不修改）。
|
||
- **业务模块**：
|
||
- 消费者端（consumer）订单链路
|
||
- 商家端（merchant）商品与订单履约
|
||
- 配送端（delivery）接单/取货/送达
|
||
- 管理端（admin）配置与全局视角
|
||
|
||
---
|
||
|
||
## 变更清单
|
||
|
||
- **新增文件**：
|
||
- `docs/ops/2026-02-05__mall__delivery-merchant-customer-dataflow-analysis.md`
|
||
- **修改文件**：无
|
||
- **删除文件**：无
|
||
|
||
---
|
||
|
||
## 权威输入（引用口径）
|
||
|
||
- 数据库与流程说明：
|
||
- `docs/sql/02_relationships_er.md`
|
||
- `docs/sql/03_enums_status_dict.md`
|
||
- `docs/sql/07_business_workflows.md`
|
||
- `docs/sql/11_roles_and_permissions_strategy.md`
|
||
- 工程与安全规范：
|
||
- `docs/project_spec/AGENT_PROJECT_SPEC.md`
|
||
- 参考实现（非权威口径，但含完整 DDL/触发器/RLS 示例）：
|
||
- `mall_sql/schemas/complete_mall_database.sql`
|
||
- 管理端设置页现状（占位）：
|
||
- `pages/mall/admin/system-settings.uvue`
|
||
|
||
---
|
||
|
||
## 1. 统一域模型：三方是谁（同一身份体系下的三类角色）
|
||
|
||
- **统一用户主表**：`public.ak_users`
|
||
- **角色唯一权威字段**：`ak_users.role`
|
||
- **商城用户扩展档案**：`public.ml_user_profiles`
|
||
- 关系：`ak_users` 1:1 `ml_user_profiles`（`ml_user_profiles.user_id UNIQUE`）
|
||
|
||
三方角色定义（业务口径）：
|
||
|
||
- 消费者：`ak_users.role = 'customer'`
|
||
- 商家：`ak_users.role = 'merchant'`
|
||
- 配送员：`ak_users.role = 'delivery'`
|
||
|
||
结论：三方并非三套用户体系，而是“同一 `ak_users` + 不同域表扩展”。
|
||
|
||
---
|
||
|
||
## 2. 核心表关系（文字版 ER）
|
||
|
||
### 2.1 消费者（Customer）
|
||
|
||
- `ak_users (customer)` 1:N `ml_user_addresses`
|
||
- `ak_users (customer)` 1:N `ml_shopping_cart`
|
||
- `ak_users (customer)` 1:N `ml_orders`（`ml_orders.user_id`）
|
||
|
||
### 2.2 商家（Merchant）
|
||
|
||
- `ak_users (merchant)` 1:1 `ml_shops`（`ml_shops.merchant_id UNIQUE`）
|
||
- 当前模型含义：一商家一店铺
|
||
- `ak_users (merchant)` 1:N `ml_products`（`ml_products.merchant_id`）
|
||
- `ak_users (merchant)` 1:N `ml_orders`（`ml_orders.merchant_id`）
|
||
|
||
### 2.3 商品（Product）
|
||
|
||
- `ml_products` 1:N `ml_product_skus`
|
||
- `ml_products` 1:N `ml_product_specs`
|
||
- SKU 变更触发汇总：`ml_product_skus` 变更 -> 触发器刷新 `ml_products.total_stock/available_stock`
|
||
|
||
### 2.4 订单（Order）
|
||
|
||
- `ml_orders` 1:N `ml_order_items`
|
||
- `ml_orders` 1:1 `ml_delivery_tasks`（`ml_delivery_tasks.order_id UNIQUE`）
|
||
- 当前模型含义：一订单最多一个配送任务
|
||
|
||
### 2.5 配送（Delivery）
|
||
|
||
- `ak_users (delivery)` 1:1 `ml_delivery_drivers`（`ml_delivery_drivers.user_id UNIQUE`）
|
||
- `ml_delivery_drivers` 1:N `ml_delivery_tasks`（通过 `ml_delivery_tasks.driver_id` 关联）
|
||
|
||
---
|
||
|
||
## 3. 三方端到端数据流（事件 → 落表 → 状态变化）
|
||
|
||
### 3.1 消费者链路（浏览→加购→下单→支付→收货→评价）
|
||
|
||
#### 事件 A：维护地址
|
||
|
||
- 写表：`ml_user_addresses`
|
||
- 约束：同一用户最多一个默认地址
|
||
- 由触发器 `ensure_single_default_address()` 保证
|
||
|
||
#### 事件 B：加购/改购
|
||
|
||
- 写表：`ml_shopping_cart`
|
||
- 约束：`UNIQUE(user_id, product_id, sku_id)`（便于 upsert 累加）
|
||
|
||
#### 事件 C：下单（创建订单 + 明细快照）
|
||
|
||
- 写表：
|
||
- `ml_orders`（订单主表）
|
||
- `ml_order_items`（订单明细快照）
|
||
- 关键设计点：
|
||
- `ml_orders.shipping_address` 为 JSONB 地址快照，避免订单与地址簿耦合
|
||
- `ml_order_items` 快照化写入商品名/规格/图/价格，避免商品变更影响历史
|
||
|
||
> 一致性提示（现状）：当前权威文档指出未体现“扣库存/冻结库存”落地，库存一致性需由应用层事务或后续 DB/RPC 补齐。
|
||
|
||
#### 事件 D：支付成功
|
||
|
||
- 更新：`ml_orders`
|
||
- `order_status: 1 -> 2`
|
||
- `payment_status: 1 -> 2`
|
||
- `paid_amount = total_amount`
|
||
- 触发器副作用：`handle_order_status_change()` 在 `1->2` 写 `paid_at`
|
||
|
||
#### 事件 E：收货完成/订单完成
|
||
|
||
- 更新：`ml_orders`
|
||
- `order_status: 3 -> 4`
|
||
- `shipping_status -> 4`
|
||
- 触发器副作用：写 `delivered_at/completed_at`，并累计更新 `ml_products.sale_count`
|
||
|
||
#### 事件 F：评价
|
||
|
||
- 写表：`ml_product_reviews`
|
||
- 强绑定来源：`order_id + order_item_id`
|
||
|
||
---
|
||
|
||
### 3.1.1 退款/取消在当前模型中的最小表达（现状与缺口）
|
||
|
||
当前数据库没有独立的退款申请表或售后流程表，只能通过 `ml_orders` 的状态组合表达：
|
||
|
||
- **退款分支**：
|
||
- `payment_status: 3（部分退款）` / `4（全额退款）`
|
||
- `order_status` 通常进入 `6（退款中）` -> `7（已退款）`
|
||
- **取消分支**：
|
||
- `order_status: 5`（歧义点，见第 4.2 节）
|
||
- `cancel_reason`（文本字段）可用于记录取消原因
|
||
|
||
> **缺口提示**：
|
||
> - 缺少退款申请流水、审批流、支付对账表，复杂售后需后续扩表或接支付系统。
|
||
> - 缺少 `cancelled_at`、`refunded_at` 等审计时间字段。
|
||
> - 配送已取货/在途/已送达时的退款/取消口径未在当前模型体现（需业务层定义）。
|
||
|
||
---
|
||
|
||
### 3.2 商家链路（供给→接单→履约）
|
||
|
||
#### 事件 A：创建/编辑商品
|
||
|
||
- 写表：`ml_products`、`ml_product_skus`、`ml_product_specs`
|
||
- 库存汇总：SKU 触发器刷新 SPU 汇总库存字段
|
||
|
||
#### 事件 B：发货/履约推进
|
||
|
||
- 更新：`ml_orders`
|
||
- `order_status: 2 -> 3`
|
||
- `shipping_status: 1 -> 2`
|
||
- 触发器副作用：`2->3` 时写 `shipped_at`
|
||
|
||
---
|
||
|
||
### 3.2.1 单商家订单模型的限制（需求提醒）
|
||
|
||
当前订单主表 `ml_orders` 直接持有 `merchant_id`，且未见“主单/子单”结构，因此该模型天然对应：
|
||
|
||
- **一笔订单仅归属一个商家/店铺**（单商家订单）
|
||
|
||
> 若产品需求为“一单多商家（多店铺）”，通常需要：
|
||
> - 引入主/子订单拆分（例如主订单聚合支付与收货信息，子订单按商家拆分履约与结算），或
|
||
> - 在下单阶段强制拆单（多个 `ml_orders`）并建立父子关联字段。
|
||
|
||
---
|
||
|
||
### 3.3 配送链路（派单/接单→取货→配送→送达）
|
||
|
||
#### 事件 A：创建配送任务
|
||
|
||
- 写表：`ml_delivery_tasks`
|
||
- 关键字段：
|
||
- `order_id UNIQUE`
|
||
- `driver_id` 可空（先生成后指派）
|
||
- `pickup_address`（取货点）
|
||
- `delivery_address`（配送点，建议源自订单地址快照）
|
||
|
||
#### 事件 B：接单/指派
|
||
|
||
- 更新：`ml_delivery_tasks`
|
||
- `status: 1 -> 2`
|
||
- `assigned_at` 写入
|
||
- 绑定 `driver_id`
|
||
|
||
#### 事件 C：取货→配送→送达（或失败）
|
||
|
||
- 更新：`ml_delivery_tasks`
|
||
- `2 -> 3`（写 `picked_at`）
|
||
- `3 -> 4`
|
||
- `4 -> 5`（写 `delivered_at`）
|
||
- 失败：`status = 6` + `failure_reason`
|
||
|
||
> 一致性提示（现状）：未看到 DB 侧“配送送达 → 自动联动订单状态”的权威触发器/RPC 设计，需在 service/RPC 层承担联动更新职责。
|
||
|
||
---
|
||
|
||
### 3.3.1 配送状态 → 订单状态的建议映射（统一口径）
|
||
|
||
为避免三方对“配送进展如何反映到订单状态”理解不一致，建议采用以下最小映射（可在 service/RPC 事务中实现）：
|
||
|
||
| 配送任务 `status` | 建议同步的 `ml_orders.shipping_status` | 建议同步的 `ml_orders.order_status` | 说明 |
|
||
| ----------------- | -------------------------------------- | ----------------------------------------------------- | ------------------------- |
|
||
| 1 待接单 | 1 未发货 | 2 待发货（已支付） | 任务生成但未接单 |
|
||
| 2 已接单 | 2 已发货 | 2 待发货 | 商家/平台已指派，但未取货 |
|
||
| 3 取货中 | 3 运输中 | 3 待收货 | 骑手已取货，在途 |
|
||
| 4 配送中 | 3 运输中 | 3 待收货 | 仍在途 |
|
||
| 5 已送达 | 4 已送达 | 3 待收货（或直接 4 已完成，取决于产品是否需用户确认） | 骑手确认送达 |
|
||
| 6 配送失败 | 1 未发货（或自定义状态） | 2 待发货（或进入异常分支） | 需人工介入 |
|
||
|
||
> **关键决策点**：`status=5` 时，`order_status` 是“待收货”还是直接“已完成”，取决于产品是否需要用户“确认收货”这一步。若不需要，可直接 `4`。
|
||
|
||
---
|
||
|
||
### 3.3.2 派单依据（任务池可见性）的字段来源
|
||
|
||
`ml_delivery_drivers` 与 `ml_delivery_tasks` 中的以下字段是“任务池筛选/派单算法”的数据基础：
|
||
|
||
- **服务区域**：`ml_delivery_drivers.service_areas`（JSONB），用于按区域过滤可接单骑手
|
||
- **实时位置**：`current_lat/current_lng`，用于距离排序/就近派单
|
||
- **工作状态**：`work_status`（在线/忙碌/离线），用于过滤可用骑手
|
||
- **任务状态**：`ml_delivery_tasks.status=1`，用于构建“待接单任务池”
|
||
|
||
> 权限提示：若任务池需对骑手可见，需配合 RLS 或 RPC 实现“仅可看同区域且状态=1 的任务”。
|
||
|
||
---
|
||
|
||
## 4. 状态机统一口径（必须统一的单一真相）
|
||
|
||
### 4.1 订单并行状态字段
|
||
|
||
`ml_orders` 存在三条并行状态线：
|
||
|
||
- `order_status`：订单流程
|
||
- `payment_status`：支付/退款
|
||
- `shipping_status`：发货/物流
|
||
|
||
推荐统一驱动关系：
|
||
|
||
- 支付成功驱动 `order_status` 进入“待发货”阶段
|
||
- 发货/配送接管驱动 `order_status` 进入“待收货”阶段
|
||
- 签收/确认收货驱动 `order_status` 完成
|
||
- 退款以 `payment_status` 为主线，同时影响 `order_status` 分支
|
||
|
||
### 4.2 `order_status = 5` 的歧义
|
||
|
||
文档指出 `5` 在不同脚本存在“已取消/已取货”表述差异。
|
||
|
||
- 无自提流程：建议统一为“已取消”
|
||
- 有自提流程：建议拆出独立状态值（避免取消与自提完成混用）
|
||
|
||
---
|
||
|
||
## 5. 读模型（各端典型查询视角）
|
||
|
||
> 本节描述“应该怎么查”，不涉及具体实现。
|
||
|
||
### 5.1 消费者端
|
||
|
||
- 商品列表/详情：优先基于商品详情视图（若存在）或 `ml_products`（上架商品）
|
||
- 我的订单列表：`ml_orders.user_id = 当前用户` + 时间倒序
|
||
- 订单详情：`ml_orders` + `ml_order_items`
|
||
- 配送进度：若需展示，则读取 `ml_delivery_tasks`（需权限策略或 RPC 支持）
|
||
|
||
### 5.2 商家端
|
||
|
||
- 我的商品：`ml_products.merchant_id = 当前商家`
|
||
- 注意：若 `ml_products` 的 RLS select 仅允许 `status=1`，商家后台查看草稿/下架需额外策略或 RPC
|
||
- 店铺订单：`ml_orders.merchant_id = 当前商家` + `ml_order_items`
|
||
- 配送任务看板：按订单关联 `ml_delivery_tasks`
|
||
|
||
> **现状风险（RLS）**：`ml_products_select_policy` 仅允许 `status=1`，会导致商家后台直查表时看不到自己的草稿/下架商品。建议扩展 RLS 或为商家后台提供专用 RPC。
|
||
|
||
### 5.3 配送端
|
||
|
||
- 待接单任务池：`ml_delivery_tasks.status = 1`（通常需按服务区域过滤）
|
||
- 我的任务：`ml_delivery_tasks.driver_id = 当前配送员`
|
||
- 任务详情：最小化暴露订单/个人敏感信息（原则层面）
|
||
|
||
---
|
||
|
||
## 6. 权限边界（RLS / RPC / 前端守卫的闭环）
|
||
|
||
### 6.1 前端工程约束
|
||
|
||
- 数据访问唯一入口：必须通过 `services/`
|
||
- 客户端路由守卫用于快速失败，但最终权限以数据库为准
|
||
|
||
### 6.2 admin / analytics 的全局数据访问
|
||
|
||
按项目规范与策略文档：
|
||
|
||
- 不建议对 admin/analytics 直接开放业务表全局 `SELECT`
|
||
- 应通过 RPC（`SECURITY DEFINER` + 固定 `search_path` + 入口 `get_current_user_role()` 鉴权）返回最小必要字段/聚合数据
|
||
|
||
---
|
||
|
||
## 7. 金额字段的归因与缺口（运费/优惠/抽佣）
|
||
|
||
| 金额字段 | 数据来源 | 归因说明 | 现状缺口 |
|
||
| --------------------------- | ----------------------------------------------------- | ------------------------------------------------- | --------------------------------------- |
|
||
| `ml_orders.shipping_fee` | `ml_system_configs.shipping_fee`（或按距离/重量计算） | 配送费，可配置默认值或按规则计算 | 缺少运费规则表（如按区域/重量/距离） |
|
||
| `ml_orders.discount_amount` | 优惠券/活动/满减 | 优惠金额，使用券时关联 `ml_user_coupons.order_id` | 缺少活动/满减规则表，复杂优惠需扩表 |
|
||
| `ml_orders.total_amount` | 商品金额 + 运费 - 优惠 | 订单最终应付 | — |
|
||
| `platform_commission` | `ml_system_configs.platform_commission`（比例） | 平台抽佣，通常在结算时计算 | 缺少结算单/分账流水表，抽佣未落结算流水 |
|
||
|
||
> **结论**：金额归因在“配置 → 落表”层面基本可表达，但缺少结算/对账/复杂优惠的支撑表。
|
||
|
||
---
|
||
|
||
## 8. 系统配置（system-settings）与“配置驱动流程”的现状说明
|
||
|
||
- DB 已存在：`ml_system_configs`，并在参考脚本中初始化了配置项（如 `shipping_fee`、`platform_commission`、`order_auto_confirm_days`）。
|
||
- 管理端页面现状：`pages/mall/admin/system-settings.uvue` 目前为占位页，仅展示 query 参数，未接入配置读写。
|
||
|
||
结论：配置承载表存在，但尚未形成“配置 → 业务流程”的实际驱动闭环。
|
||
|
||
---
|
||
|
||
## 兼容性与风险
|
||
|
||
- **状态机风险**：三条并行状态字段若缺少统一约束，易出现互相矛盾的状态组合。
|
||
- **一致性风险**：库存扣减/冻结、配送送达与订单联动等关键一致性未在当前权威 SQL 中体现，需在应用层或后续 RPC/触发器补齐。
|
||
- **权限风险**：配送域 RLS/RPC 若未补齐，会导致配送端无法形成可运转的“接单→更新状态”闭环。
|
||
|
||
---
|
||
|
||
## 回滚方案
|
||
|
||
本文仅新增文档，无业务变更；删除该 markdown 文件即可回滚。
|
||
|
||
---
|
||
|
||
## 验证方式
|
||
|
||
- 打开本文档，核对引用路径均存在：
|
||
- `docs/sql/*`、`docs/project_spec/*`
|
||
- 与现有页面目录结构、角色字段口径（`ak_users.role`）一致。
|
||
|
||
---
|
||
|
||
## 关联文档
|
||
|
||
- `docs/project_spec/AGENT_PROJECT_SPEC.md`
|
||
- `docs/sql/02_relationships_er.md`
|
||
- `docs/sql/03_enums_status_dict.md`
|
||
- `docs/sql/07_business_workflows.md`
|
||
- `docs/sql/11_roles_and_permissions_strategy.md`
|