邹方成
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): 添加称号效果参数验证测试
4.6 KiB
4.6 KiB
目标
- 为管理后台补齐“订单管理”全套能力：全局订单列表/详情、筛选与搜索、状态流转（取消/发货/签收/履约）、退款、导出与对账入口；与现有用户维度订单查询保持一致风格。
现状与缺口
- 已有：按用户查看订单、运营漏斗统计；无全局订单页与发货、退款、对账的管理操作。
- 模型完备：
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），增加关键操作的业务日志字段。
验收标准
- 管理端可全局查看与筛选订单，支持详情、取消、履约、发货、签收、异常标记；
- 退款创建与查询可用（占位版本），后续升级为真实退款；
- 导出按筛选条件生成数据；
- 运营漏斗与新页面数据口径一致；编译与基础联调通过。
实施步骤
- 后端：新增订单与发货相关接口与服务；将退款占位路由挂载；完善查询与分页；幂等与事务。
- 前端：新增API文件与页面组件（列表/详情/发货）；接入菜单与路由；UI按现有风格。
- 校验：编译与接口联调、权限校验、筛选与导出验证；漏斗口径确认。
- 留待增强：接入真实支付退款与对账流程；增加订单号唯一索引与支付幂等表。
风险与处理
- 真实退款未接入：先保留管理操作占位，避免资金走错；上线前需联通支付域。
- 并发与幂等：条件更新控制状态流；失败重试与告警结合现有日志。