diff --git a/changelogs-v2/2026-09/07_7174_定制需求管理后台接口迁移v3路径-修改接口-管理后台.md b/changelogs-v2/2026-09/07_7174_定制需求管理后台接口迁移v3路径-修改接口-管理后台.md new file mode 100644 index 00000000..f717f1bb --- /dev/null +++ b/changelogs-v2/2026-09/07_7174_定制需求管理后台接口迁移v3路径-修改接口-管理后台.md @@ -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` + +#### 使用场景 + +管理后台定制需求列表页,按状态筛选分页查询。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|---|---|---|---:|---|---| +| `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 +``` + +#### 响应示例 + +```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 +- **当前状态**: 后端已就绪,前端待切换路径。