medical-mall/docs/ops/2026-02-10__admin__order-module-integration.md

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