wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 工作流 软件包 项目 发布 百科 活动
文件
10b46812d23a51304c00ee1537254b4a07c7265c
hl-api-changelog/changelogs-v2/2026-09/07_7174_定制需求管理后台接口迁移v3路径-修改接口-管理后台.md
T
Mimingguang 6d966716fb
changelog-filename-gate / validate (push) Failing after 2s
详情
chore(changelog): 回写 #7174 前端交付验证(verified, ref 8c5574c4)
2026-09-08 10:33:14 +08:00

8.9 KiB
原始文件 Blame 文件历史

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base
schema ticket title consumer author change_type backend_status gateway_status frontend_status frontend_owner frontend_ref target_release verified_at status_note updated_at base
hl-changelog/v2 7174 定制需求管理后台接口迁移 v3 路径 admin yst 修改接口 deployed verified verified mmg 8c5574c4 v2.1 2026-09-08 前端已交付并验证(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 全量+生产构建)。 2026-09-08 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 分页元信息

请求示例

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

响应示例

{
  "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，前端正常渲染空列表。

错误响应

未登录 / 登录过期：

{"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 回复内容

请求示例

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

错误响应

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

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

{"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 路径）。

十、相关文档

关联 / 联系人

  • Epic: #7171
  • Issue: #7174
  • 后端负责人: @yst
  • 当前状态: 后端已就绪，前端待切换路径。
在新工单中引用 查看 Git Blame 复制永久链接