---
url: /docs/api-docs/v1/admin/orders.md
---
# 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 总览](/api-docs/v1/admin/)。