docs(changelog): 定制需求管理后台接口迁移 v3 路径（Epic #7171）

customize 定制需求域由 order-v2 迁往 order-v3，管理后台 5 个接口 base 路径 /admin/order/customize → /v3/admin/order/customize，仅路径前缀变化，字段/方法/出入参契约零变更。旧 v2 路径已下线 404。 Refs #7174
2026-09-07 00:49:24 +08:00
@@ -0,0 +1,225 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7174"
+title: "定制需求管理后台接口迁移 v3 路径"
+consumer: "admin"
+author: "yst"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: "hl-admin"
+frontend_ref: ""
+target_release: "v2.1"
+verified_at: "2026-09-07"
+status_note: "Epic #7171：customize 定制需求域由 order-v2 迁往 order-v3。PR #7183（v3 建域）+ #7198（product-v2 Feign 切流）+ #7214（v2 旧域下线）均已合并 dev-v3 并部署 TEST。v3 端点已在 TEST 实证：admin page 无 X-Admin-Id 返 401、带 admin 头返 200 分页结构。仅路径前缀变化，字段/方法/出入参契约与 v2 完全一致。旧 v2 路径已下线，调旧路径返回 404 接口不存在。当前状态：后端已就绪，前端待切换路径。"
+updated_at: "2026-09-07"
+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
+- **当前状态**: 后端已就绪，前端待切换路径。