邹方成
6ee627139c
Some checks failed
Build docker and publish / linux (1.24.5) (push) Failing after 40s
feat(pay): 添加支付API基础结构 feat(miniapp): 创建支付测试小程序页面与配置 feat(wechatpay): 配置微信支付参数与证书 fix(guild): 修复成员列表查询条件 docs: 更新代码规范文档与需求文档 style: 统一前后端枚举显示与注释格式 refactor(admin): 重构用户奖励发放接口参数处理 test(title): 添加称号效果参数验证测试
65 lines
4.6 KiB
Markdown
65 lines
4.6 KiB
Markdown
# 目标
|
||
- 为管理后台补齐“订单管理”全套能力：全局订单列表/详情、筛选与搜索、状态流转（取消/发货/签收/履约）、退款、导出与对账入口；与现有用户维度订单查询保持一致风格。
|
||
|
||
# 现状与缺口
|
||
- 已有：按用户查看订单、运营漏斗统计；无全局订单页与发货、退款、对账的管理操作。
|
||
- 模型完备：`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. 留待增强：接入真实支付退款与对账流程；增加订单号唯一索引与支付幂等表。
|
||
|
||
# 风险与处理
|
||
- 真实退款未接入：先保留管理操作占位，避免资金走错；上线前需联通支付域。
|
||
- 并发与幂等：条件更新控制状态流；失败重试与告警结合现有日志。 |