226 行
8.9 KiB
Markdown
226 行
8.9 KiB
Markdown
---
|
||
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
|
||
- **当前状态**: 后端已就绪，前端待切换路径。
|