74 lines
3.4 KiB
Markdown
74 lines
3.4 KiB
Markdown
# 订单模块接入与统计修复（2026-02-10）
|
||
|
||
## 摘要
|
||
本次对 Admin 订单模块进行了“从 Mock 到 RPC”的接入修复，补齐订单管理列表与订单统计页的后端 RPC，并在前端 `services/orderService.uts` 与页面侧完成对接。同时为核销记录 RPC 所依赖的 `ml_orders` 字段补齐 Schema 更新脚本。
|
||
|
||
## 动机
|
||
- `pages/mall/admin/order/list.uvue`（订单管理）与 `order-statistics/index.uvue`（订单统计）此前存在大量硬编码 Mock 数据，无法真实反映数据库状态。
|
||
- 按项目规范（`AGENT_PROJECT_SPEC.md`）：admin/analytics 全局数据访问必须通过 RPC，服务层为数据访问唯一入口。
|
||
|
||
## 影响范围
|
||
- **数据库 / RPC**：新增订单列表与统计类 RPC；补齐 `ml_orders` 必要字段（核销相关）。
|
||
- **服务层**：更新 `services/orderService.uts` 增加订单列表与统计类 fetch 方法。
|
||
- **页面**：
|
||
- `pages/mall/admin/order/list.uvue`：移除 mock，接入 `rpc_admin_order_list`。
|
||
- `pages/mall/admin/order/order-statistics/index.uvue`：移除硬编码图表数据，接入统计 RPC。
|
||
|
||
## 变更清单
|
||
|
||
### 新增 SQL
|
||
- `docs/sql/30_rpc/order/rpc_admin_order_list_v1.sql`
|
||
- `docs/sql/30_rpc/order/rpc_admin_order_stats_v1.sql`
|
||
- `docs/sql/30_rpc/order/rpc_admin_order_trend_v1.sql`
|
||
- `docs/sql/30_rpc/order/rpc_admin_order_source_stats_v1.sql`
|
||
- `docs/sql/10_schema/order/ml_orders_schema_update_v1.sql`
|
||
|
||
### 修改代码
|
||
- `services/orderService.uts`
|
||
- `pages/mall/admin/order/list.uvue`
|
||
- `pages/mall/admin/order/order-statistics/index.uvue`
|
||
|
||
## 设计要点
|
||
|
||
### RPC 安全策略
|
||
- 所有新增 RPC 均：
|
||
- `SECURITY DEFINER`
|
||
- `SET search_path = public`
|
||
- 入口鉴权：`ak_users.role IN ('admin','analytics')`
|
||
|
||
### 订单列表 RPC（最小可用）
|
||
- 以 `ml_orders` + `ak_users` + `ml_order_items` 为数据来源。
|
||
- 支持：分页、订单状态筛选、订单号/用户名/手机号搜索、时间范围筛选（基于 `created_at`）。
|
||
- 注意：支付方式与订单类型字段在权威 DDL 中未完整统一，本次按最小可用落地，后续可迭代扩展。
|
||
|
||
### 统计 RPC
|
||
- `rpc_admin_order_stats`：返回订单数、销售额、退款数、退款金额（退款金额目前按最小字段聚合，后续可替换为真实退款字段）。
|
||
- `rpc_admin_order_trend`：按天聚合趋势。
|
||
- `rpc_admin_order_source_stats`：当前 DDL 未含渠道字段，先返回 `unknown` 汇总，后续补渠道字段后可升级。
|
||
|
||
### Schema 补丁（核销字段）
|
||
`ml_orders_schema_update_v1.sql` 补齐：
|
||
- `order_type`（1普通/2收银/3核销）
|
||
- `verified_at`
|
||
- `verifier_id`
|
||
|
||
用于让 `rpc_admin_write_off_record_list_v1.sql` 的字段依赖具备落库条件。
|
||
|
||
## 验证方式
|
||
1. 在数据库控制台依次执行：
|
||
- `docs/sql/10_schema/order/ml_orders_schema_update_v1.sql`
|
||
- `docs/sql/30_rpc/order/*.sql`（新增的 4 个 RPC）
|
||
2. Admin 端页面验证：
|
||
- 订单管理：切换状态 Tabs、搜索、分页。
|
||
- 订单统计：打开页面检查 KPI 卡片与图表是否能加载并更新。
|
||
|
||
## 回滚方案
|
||
- 回滚 RPC：删除新增函数（需人工确认，不在脚本中提供）。
|
||
- 回滚字段：删除新增列（需人工确认，不在脚本中提供）。
|
||
|
||
## 关联文档
|
||
- `docs/project_spec/AGENT_PROJECT_SPEC.md`
|
||
- `pages/mall/admin/docs/sql/01_tables_catalog.md`
|
||
- `docs/sql/30_rpc/auth/get_current_user_role_v1.sql`
|
||
- `pages/mall/admin/docs/sql/11_roles_and_permissions_strategy.md`
|