# 订单模块接入与统计修复（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`