order — 订单管理（10 action）

前缀：/api/v1/admin/order/ 权限：ORDER_READ（list/detail/close-reasons）· ORDER_WRITE（close/update-logistics/return-goods/update-address/update-recipient）· ORDER_REFUND（refund/adjust-price — 高敏感）— 仅 super + operator，it 一律 403 代码：src/app/admin/interface/api/order_mgmt.py + application/usecase/order_mgmt.py

3.5.1 list —— 订单列表

GET /api/v1/admin/order/list · 权限 ORDER_READ

Query 参数：

字段	类型	必填	默认	说明
page	int	⬜	1	≥1
page_size	int	⬜	20	1~100
status	string	⬜	—	订单状态过滤
user_id	string	⬜	—	按用户过滤
date_from / date_to	string	⬜	—	ISO 日期区间

响应 data：{ total, page, page_size, items: [OrderSummary] }

OrderSummary 字段：

字段	类型	说明
id / user_id	string	订单 / 用户
amount / paid_amount / refund_amount	float	金额三件套
status	string	pending | paid | refunded | closed
payment_channel	string	支付渠道
created_at / updated_at	string	ISO

错误码：40201001 page/page_size < 1。

3.5.2 detail —— 订单详情

GET /api/v1/admin/order/detail/{order_id} · 权限 ORDER_READ

响应 data：

字段	类型	说明
order	object	全字段（含 recipient_name 等）
items	array	商品明细
payment	object	{channel, paid_amount, refund_amount, refund_status}
refund_history	array	退款流水
logistics	object	{company, tracking_no}

错误码：40201301（404）订单不存在。

3.5.3 refund —— 退款（⚠️ 高敏感）

POST /api/v1/admin/order/refund · 权限 ORDER_REFUND · confirm_text = "REFUND"

请求 body：

字段	类型	必填	说明
order_id	string	✅	目标订单
amount	float	✅	退款金额
reason	string	✅	退款原因
note	string | null	⬜	备注（audit）
confirm_text	string	✅	必须逐字为 "REFUND"，否则 40201001（400）

响应 data：

字段	类型	说明
refund_id	string	退款单号
status	string	退款后状态
refunded_at	string	ISO
withdrawal_id	string | null	关联提现单（如走提现通道）

错误码（§7.4 财务链路全分支）：

code	场景
40201301	订单不存在（404）
40201302	订单状态不允许退款（ORDER_STATUS_NOT_ALLOWED）
40201303	已有退款冲突（关单/退款时）
40201304	退款金额超过可退余量
40201305	渠道余额不足
40201307	部分退款不支持该支付方式
40201308	订单金额与支付金额不一致
40201309	超过维权期
40201001	confirm_text 不匹配 / 参数非法

3.5.4 close —— 关闭订单

POST /api/v1/admin/order/close · 权限 ORDER_WRITE

请求 body：{ order_id✅, reason✅, note? }

响应 data：{ "success": true }

错误码：40201301（404）· 40201302 状态不允许 · 40201303 已有退款冲突 · 40201001 参数非法。

3.5.5 close-reasons —— 关单原因字典

GET /api/v1/admin/order/close-reasons · 权限 ORDER_READ

响应 data：{ "reasons": [ {code, label, …} ] }（供前端关单弹窗下拉）

3.5.6 update-logistics —— 更新物流

POST /api/v1/admin/order/update-logistics · 权限 ORDER_WRITE

请求 body：{ order_id✅, logistics_company✅, tracking_no✅ }

响应 data：{ "success": true }

错误码：40201301（404）· 40201302 状态不允许 · 40201001 参数非法。

3.5.7 return-goods —— 退货登记

POST /api/v1/admin/order/return-goods · 权限 ORDER_WRITE

请求 body：

字段	类型	必填	说明
order_id	string	✅	目标订单
items	array	✅	退货明细（对象数组）
note	string | null	⬜	备注

响应 data：{ "return_id": "<id>", "status": "<status>" }

错误码：40201301（404）· 40201302 状态不允许 · 40201001 items 非法。

3.5.8 adjust-price —— 调价（⚠️ 高敏感）

POST /api/v1/admin/order/adjust-price · 权限 ORDER_REFUND · confirm_text = "ADJUST"

请求 body：

字段	类型	必填	说明
order_id	string	✅	目标订单
new_amount	float	✅	新金额
reason	string	✅	调价原因
confirm_text	string	✅	必须逐字为 "ADJUST"，否则 40201001（400）

响应 data：{ "success": true, "old_amount": <float>, "new_amount": <float> }

错误码：40201301（404）· 40201302 状态不允许 · 40201310 调账金额非法（负数/零/超上限）· 40201001 confirm_text 不匹配。

3.5.9 update-address —— 修改收货地址

POST /api/v1/admin/order/update-address · 权限 ORDER_WRITE

请求 body：{ order_id✅, address✅（对象） }

响应 data：{ "success": true }

错误码：40201301（404）· 40201302 状态不允许 · 40201306 已发货无法改地址 · 40201001 address 非法。

3.5.10 update-recipient —— 修改收件人

POST /api/v1/admin/order/update-recipient · 权限 ORDER_WRITE

请求 body：{ order_id✅, name✅, phone✅, note? }

响应 data：{ "success": true }

错误码：40201301（404）· 40201302 状态不允许 · 40201001 参数非法。

---

本域错误码汇总：40201301-40201310（§6.5）。财务链路验收（§7.4/§7.5）：refund → 渠道余额扣减 → audit → notification。通用失败见 admin 总览。