yst 69115eeadd feat(agency): Agency 域接口路径切 v3（admin + mp 两端）

PR #2562 把 4 个 controller path 加 /v3 前缀:
- /admin/travel-agency/** → /v3/admin/travel-agency/**
- /mp/agency/** → /v3/mp/agency/**

仅路径变更, 参数/响应/错误码/业务逻辑 100% 不变。
旧 path 雪藏期内仍可用, 但前端必须切到新 path 才能享受后续维护。

关联: HL Issue #2561 / PR #2562 / PR-1 #2556 / PR-2 #2558

2026-05-18 22:10:48 +08:00

4.4 KiB

原始文件 Blame 文件历史

【修改接口·两端】Agency 模块路径切 v3

更新时间: 2026-05-19 端类型: 管理后台 + 小程序关联: HL Issue #2561 / PR #2562 背景: Agency 域已迁移至 hl-order-service-v3，旧 v2 路径仍可用（雪藏期），但前端必须切到新 /v3 路径以确保后续维护。

0. 模块全貌

子模块	接口数	端
§A admin 旅行社 CRUD	~10	管理后台
§B admin 支付配置	~5	管理后台
§C admin 资质附件	~5	管理后台
§D mp 公开视图	~3	小程序

1. 接口背景

Agency（旅行社）域承载主体公司 + 支付商户号 + 资质附件信息。之前由 v2 老订单服务（hl-order-service）承载，PR #2556/#2558/#2562 完整迁到 v3（hl-order-service-v3）。

迁移采用 Option A 雪藏方案：v2 代码 / 表 / 旧路径 全部保留，但前端必须切到 v3 新路径，新功能 / 维护只在 v3 进行。

2. 变更清单（仅路径变更，参数 / 响应 / 错误码 / 业务逻辑 100% 不变）

§A admin 旅行社 CRUD

旧 path	新 path	方法
`/admin/travel-agency/page`	`/v3/admin/travel-agency/page`	GET
`/admin/travel-agency/{id}`	`/v3/admin/travel-agency/{id}`	GET / PUT / DELETE
`/admin/travel-agency`	`/v3/admin/travel-agency`	POST
`/admin/travel-agency/simple-list`	`/v3/admin/travel-agency/simple-list`	GET
`/admin/travel-agency/{id}/toggle-status`	`/v3/admin/travel-agency/{id}/toggle-status`	PUT
`/admin/travel-agency/{id}/visible`	`/v3/admin/travel-agency/{id}/visible`	PUT
……（其他 admin 接口同规则，统一前缀替换）	……同规则	……

§B admin 支付配置

旧 path	新 path
`/admin/travel-agency/{agencyId}/payment/**`	`/v3/admin/travel-agency/{agencyId}/payment/**`

§C admin 资质附件

旧 path	新 path
`/admin/travel-agency/{agencyId}/qualification/**`	`/v3/admin/travel-agency/{agencyId}/qualification/**`

§D mp 公开视图（小程序）

旧 path	新 path
`/mp/agency/primary`	`/v3/mp/agency/primary`
`/mp/agency/**`	`/v3/mp/agency/**`

3. 切换规则

统一替换：

admin: /admin/travel-agency/ 前缀 → /v3/admin/travel-agency/
mp: /mp/agency/ 前缀 → /v3/mp/agency/

其他完全不变：参数、响应字段、错误码、JWT 鉴权、业务逻辑、性能特征。

4. 入参 / 出参

无变化。所有接口的请求体 / 查询参数 / 响应 Result 包装 / 字段名 / 类型 / 可空性 / 枚举值 完全保持原样。详见 Knife4j（重启后 v3 接口在 http://<v3-host>:8086/doc.html）。

5. 错误码

无变化。仍是 582xxx 段位（Agency 错误码段），含义不变。

6. 修改前后对比（关键示例）

旧调用

GET /admin/travel-agency/page?pageNum=1&pageSize=10
Authorization: Bearer {admin_jwt}

新调用

GET /v3/admin/travel-agency/page?pageNum=1&pageSize=10
Authorization: Bearer {admin_jwt}

响应完全一样。

7. 影响评估 / 回滚

影响

前端必须把所有 Agency 域接口 base URL 加 /v3 前缀
短期内（雪藏期）旧 path 仍可用，但不接受新写入（数据在 v2 库冻结）
新功能（如新增 admin 字段）只在 v3 推

回滚

旧 v2 path 未删，前端可临时改回。Gateway 旧规则保留。但建议尽快切完，否则数据漂移风险。

8. 注意事项

必须改的请求方：admin 管理后台 + 小程序 mp/agency 调用方
不需要改：内部 Feign 调用方（mp-service 已通过 PR-2 内部切换，前端无感）
切换时机：建议本周内完成，避免错过新功能升级窗口
测试方式：本地 / 测试服并存期间，新旧 path 可同时调，对比响应一致
gateway 重启：后端已 merge，gateway 重启后新路由生效（运维通知）

9. 关联 / 联系人

Issue: wx/HL#2561
PR: wx/HL#2562
前序 PRs: #2556（PR-1 骨架）/ #2558（PR-2 内部切换）
方案文档: .claude/PRPs/2026-05-18-v2-to-v3-agency-migration-plan.md
后端负责人: yst
切换问题反馈: 在 PR #2562 评论

4.4 KiB 原始文件 Blame 文件历史 Unescape Escape