---
schema: "hl-changelog/v2"
ticket: "7174"
title: "定制需求管理后台接口迁移 v3 路径"
consumer: "admin"
author: "yst"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "verified"
frontend_owner: "mmg"
frontend_ref: "8c5574c4"
target_release: "v2.1"
verified_at: "2026-09-08"
status_note: "前端已交付并验证(commit 8c5574c4):api/order.js 五端点 /order/customize→/v3/admin/order/customize(per-request baseURL 空串覆盖防拼 /admin/v3/,沿用 REFUND_V3 先例),accept/reply/complete 由 PUT 改 POST;ReplyModal payload reply→replyContent、productId 显式 String() 防雪花数值化;新建 orderCustomizeV3.spec 5 例锁路径/POST/第三参 baseURL/雪花字符串透传;旧 v2 路径 customize 域零残留(残留 /order/customizer* 系定制师分配端点非本域);checkpoint 全绿(Vitest 全量+生产构建)。"
updated_at: "2026-09-08"
base: "dev-v3"
---

# 定制需求管理后台接口迁移 v3 路径

管理后台「定制需求」（私人定制需求单）相关接口整体由 order-v2 迁往 order-v3，**仅路径前缀变化**，请求方法、出入参字段、业务语义与 v2 **完全一致**，前端只需替换 base 路径。

- 旧路径前缀（已下线）：`/admin/order/customize`
- 新路径前缀（order-v3）：`/v3/admin/order/customize`

## 二、变更接口清单

| # | 接口 | 方法 | 旧路径（已 404） | 新路径（v3） | 变更类型 |
|---:|---|---|---|---|---|
| 1 | 定制需求分页 | GET | `/admin/order/customize/page` | `/v3/admin/order/customize/page` | 路径前缀 |
| 2 | 定制需求详情 | GET | `/admin/order/customize/{requestId}` | `/v3/admin/order/customize/{requestId}` | 路径前缀 |
| 3 | 接受定制需求 | POST | `/admin/order/customize/{requestId}/accept` | `/v3/admin/order/customize/{requestId}/accept` | 路径前缀 |
| 4 | 回复定制需求 | POST | `/admin/order/customize/{requestId}/reply` | `/v3/admin/order/customize/{requestId}/reply` | 路径前缀 |
| 5 | 标记完成 | POST | `/admin/order/customize/{requestId}/complete` | `/v3/admin/order/customize/{requestId}/complete` | 路径前缀 |

## 三、接口详情

> 5 个接口入参/出参字段与 v2 完全一致，仅 base 路径由 `/admin/order/customize` 改为 `/v3/admin/order/customize`。以下以分页与回复两个典型接口为例，其余接口契约不变。

### 1. 定制需求分页 `GET /v3/admin/order/customize/page`

**VO**: `CustomizeRequestPageReqVO / PageResult<CustomizeRequestRespVO>`

#### 使用场景

管理后台定制需求列表页，按状态筛选分页查询。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---:|---|---|
| `page` | Query | Number | 是 | ≥1 | 页码 |
| `pageSize` | Query | Number | 是 | 1-100 | 每页条数 |
| `status` | Query | String | 否 | 见状态枚举 | 按状态筛选，省略查全部 |

#### 出参

| 字段 | 类型 | 说明 |
|---|---|---|
| `data.records[].id` | String | 定制需求 ID（requestId，Long 转字符串防精度丢失） |
| `data.records[].destination` | String | 目的地 |
| `data.records[].travelCount` | String | 出行人数描述（v2 契约字段名，保持） |
| `data.records[].budgetRange` | String | 预算区间（v2 契约字段名，保持） |
| `data.records[].status` | String | 状态码，见状态枚举 |
| `data.records[].statusLabel` | String | 状态中文名 |
| `data.records[].contactName` | String | 联系人 |
| `data.records[].contactPhone` | String | 联系电话（脱敏返回） |
| `data.records[].createTime` | String | 创建时间 |
| `data.total` / `page` / `pageSize` | Number | 分页元信息 |

#### 请求示例

```http
GET /v3/admin/order/customize/page?page=1&pageSize=20&status=PENDING
Authorization: Bearer <admin-token>
```

#### 响应示例

```json
{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": {
    "records": [
      {
        "id": "2094278854020399106",
        "destination": "呼伦贝尔",
        "travelCount": "2 大 1 小",
        "budgetRange": "5000-10000",
        "status": "PENDING",
        "statusLabel": "待处理",
        "contactName": "张三",
        "contactPhone": "138****1111",
        "createTime": "2026-09-06 10:00:00"
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 20
  }
}
```

#### 空数据 / 降级响应

无匹配时 `records=[]`、`total=0`，HTTP 200，前端正常渲染空列表。

#### 错误响应

未登录 / 登录过期：

```json
{"code":401,"message":"未登录或登录已过期","success":false,"data":null}
```

### 2. 回复定制需求 `POST /v3/admin/order/customize/{requestId}/reply`

**VO**: `CustomizeReplyReqVO / CustomizeRequestRespVO`

#### 使用场景

定制师回复客户需求，可关联已搭建的产品。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---:|---|---|
| `requestId` | Path | String | 是 | 正整数 ID 字符串 | 目标定制需求 |
| `replyContent` | Body | String | 是 | 非空 | 回复内容 |
| `productId` | Body | String | 否 | 正整数 ID 字符串 | 关联产品 ID（可空） |

#### 出参

| 字段 | 类型 | 说明 |
|---|---|---|
| `data.id` | String | 定制需求 ID |
| `data.status` | String | 回复后为 `REPLIED` |
| `data.replyContent` | String | 回复内容 |

#### 请求示例

```json
{
  "replyContent": "已为您定制呼伦贝尔 5 日亲子行程，详见关联产品。",
  "productId": "2094279000000000001"
}
```

#### 错误响应

当前状态不允许回复 / 需求不存在：

```json
{"code":588102,"message":"当前状态不允许接受: {0}","success":false,"data":null}
```

```json
{"code":588101,"message":"定制需求不存在","success":false,"data":null}
```

#### 业务边界

- 状态机：PENDING（待处理）→ PROCESSING（处理中，accept）→ REPLIED（已回复，reply）→ CONVERTED（已转化，complete）/ CANCELLED（已取消）。
- 越权操作 / 非法状态转换返回 588 段错误码（见下）。

## 六.5、枚举 / 数据字典

### `status`（定制需求状态，代码枚举）

**所属字段**: `CustomizeRequestPageReqVO.status / CustomizeRequestRespVO.status` | **类型**: `String`

| 值 | 中文 | 说明 |
|---|---|---|
| `PENDING` | 待处理 | 用户提交后初始态 |
| `PROCESSING` | 处理中 | 定制师已接受 |
| `REPLIED` | 已回复 | 定制师已回复方案 |
| `CONVERTED` | 已转化 | 已关联产品/成单 |
| `CANCELLED` | 已取消 | 用户取消 |

## 六.6、修改前后对比

| 项目 | 修改前（order-v2） | 修改后（order-v3） |
|---|---|---|
| base 路径 | `/admin/order/customize` | `/v3/admin/order/customize` |
| 请求方法 | GET/POST | 不变 |
| 出入参字段 | travelCount/budgetRange/remark/replyContent 等 | **完全一致**（字段名保留 v2 契约） |
| 错误码段 | 582001-582005（v2） | 588101-588106（v3 新段） |
| 旧路径状态 | 可用 | **已下线，调用返回 404 接口不存在** |

## 六.7、影响评估

- **是否破坏向后兼容**：是（路径变化），前端必须把 base 路径由 `/admin/order/customize` 替换为 `/v3/admin/order/customize`；**字段零改动**，替换路径即可。
- **前端是否必须同步上线**：是。旧 v2 路径已下线，不切将 404。
- **前端 workaround 清理点**：删除对旧 `/admin/order/customize/**` 的调用，统一指向 `/v3/admin/order/customize/**`。
- **错误码注意**：v3 用新错误码段 588101-588106（v2 的 58200x 已废弃），若前端有按错误码做提示映射需同步更新。

## 七、不影响范围

- 小程序端（C 端）定制需求提交/查询链路：走 product-v2 聚合层，已在 PR #7198 完成内部 Feign 切流，对外 `/mp/custom/**` 路径不变，**小程序前端零改动**。
- 不修改权限、字典、网关路由以外行为；旧路径下线无数据迁移副作用（存量数据走独立迁移脚本，测试环境无数据）。

## 八、测试环境已验证

- TEST 网关：`/v3/admin/order/customize/page` 无 admin 头返 401、带 admin 头返 200 分页结构（`records/total/page/pageSize`）。
- 反向探活：旧 v2 路径 `/admin/order/customize/page`、`/internal/mp/customize/list` 均返回 `404 接口不存在`，确认旧实现已下线。

## 当前状态

- 后端：已部署并已验证。
- 前端：待处理（需切换 base 路径）。

## 十、相关文档

- Issue：[#7174](https://git.1814.love:8443/wx/HL/issues/7174)（Epic [#7171](https://git.1814.love:8443/wx/HL/issues/7171)）
- 后端 PR：[#7183](https://git.1814.love:8443/wx/HL/pulls/7183)（v3 建域）/ [#7198](https://git.1814.love:8443/wx/HL/pulls/7198)（切流）/ [#7214](https://git.1814.love:8443/wx/HL/pulls/7214)（v2 下线）

## 关联 / 联系人

- **Epic**: [#7171](https://git.1814.love:8443/wx/HL/issues/7171)
- **Issue**: [#7174](https://git.1814.love:8443/wx/HL/issues/7174)
- **后端负责人**: @yst
- **当前状态**: 后端已就绪，前端待切换路径。