# 目标
- 为管理后台补齐“订单管理”全套能力：全局订单列表/详情、筛选与搜索、状态流转（取消/发货/签收/履约）、退款、导出与对账入口；与现有用户维度订单查询保持一致风格。

# 现状与缺口
- 已有：按用户查看订单、运营漏斗统计；无全局订单页与发货、退款、对账的管理操作。
- 模型完备：`orders/order_items/shipping_records/user_points_ledger`，但缺少支付域表与真实退款流程；`CreateRefund`占位未挂路由。

# 后端接口设计
- 订单列表（全局）：`GET /api/admin/pay/orders`
  - 筛选：`status(1/2/3/4)`、`source_type(1/2/3)`、`pay_time_range`、`created_range`、`user_id/order_no`、`is_consumed`
  - 排序：`created_at/paid_at` 倒序
  - 返回：分页、订单聚合（含金额、状态、支付时间、用户信息摘要）
- 订单详情：`GET /api/admin/pay/orders/:order_no`
  - 返回：订单主信息 + `order_items` + `shipping_records` + 记账流水摘要
- 订单备注更新：`PUT /api/admin/pay/orders/:order_no/remark`
- 订单取消：`POST /api/admin/pay/orders/:order_no/cancel`
  - 行为：若`status=1待支付`→置`status=3已取消`/写`cancelled_at`，幂等
- 发货单列表：`GET /api/admin/pay/shipments`
  - 筛选：`status(1待发/2已发/3已签收/4异常)`、`order_no/product_id/express_no`、时间范围
- 创建发货：`POST /api/admin/pay/shipments`
  - 入参：`order_no/order_item_id/address_id/quantity/express_code(optional)`；行为：生成`shipping_records`，将`status=1待发`
- 标记已发货：`PUT /api/admin/pay/shipments/:id/ship`
  - 入参：`express_code/express_no`；行为：置`status=2已发/shipped_at`
- 标记已签收：`PUT /api/admin/pay/shipments/:id/receive`
  - 行为：置`status=3已签收/received_at`
- 标记异常：`PUT /api/admin/pay/shipments/:id/abnormal`
- 履约完成（虚拟）：`PUT /api/admin/pay/orders/:order_no/consume`
  - 行为：`is_consumed=1`，用于虚拟资产核销；幂等
- 退款（对接支付域）：
  - 创建退款：`POST /api/admin/pay/refunds`（保留当前占位实现，后续替换为真实支付退款API）
  - 查询退款：`GET /api/admin/pay/refunds`、`GET /api/admin/pay/refunds/:refund_no`
- 导出：`GET /api/admin/pay/orders/export`（按筛选条件导出CSV/XLSX）
- 对账入口：`POST /api/admin/pay/bills/import`（后续结合支付域实现）

# 服务层与数据层
- 新增 `admin` 服务模块：封装订单聚合查询、详情组装、状态流转与发货操作；使用 Gorm 事务与条件更新保证幂等。
- DAO 复用：`orders/order_items/shipping_records/user_points_ledger`；索引建议：`orders.order_no`唯一、`shipping_records.express_no`索引。

# 前端管理页
- 新增“订单管理”菜单及页面：
  - 订单列表页：筛选（状态、来源、时间、用户、订单号、履约）、表格列（订单号、用户、金额、状态、支付时间、来源、履约、备注）、操作（查看、取消、退款、履约、导出）
  - 订单详情页：订单主信息、订单项、发货记录（创建/发货/签收/异常）、记账流水与日志
  - 发货管理页：发货单列表，支持搜索与状态更新
- API 封装：在 `web/admin/src/api/` 新增 `pay-orders.ts` 与 `shipments.ts`，匹配后端接口

# 业务与校验
- 金额与状态校验：取消仅允许`status=1`；履约仅允许`status=2`；发货需校验行项目数量与地址。
- 幂等：状态流转采用条件更新；重复请求直接返回当前状态。
- 审计：请求日志已入库（`dblogger`），增加关键操作的业务日志字段。

# 验收标准
- 管理端可全局查看与筛选订单，支持详情、取消、履约、发货、签收、异常标记；
- 退款创建与查询可用（占位版本），后续升级为真实退款；
- 导出按筛选条件生成数据；
- 运营漏斗与新页面数据口径一致；编译与基础联调通过。

# 实施步骤
1. 后端：新增订单与发货相关接口与服务；将退款占位路由挂载；完善查询与分页；幂等与事务。
2. 前端：新增API文件与页面组件（列表/详情/发货）；接入菜单与路由；UI按现有风格。
3. 校验：编译与接口联调、权限校验、筛选与导出验证；漏斗口径确认。
4. 留待增强：接入真实支付退款与对账流程；增加订单号唯一索引与支付幂等表。

# 风险与处理
- 真实退款未接入：先保留管理操作占位，避免资金走错；上线前需联通支付域。
- 并发与幂等：条件更新控制状态流；失败重试与告警结合现有日志。