From 69115eeaddbcb88deffbf5643439e383392f55e2 Mon Sep 17 00:00:00 2001
From: yst <yst@1814.love>
Date: Mon, 18 May 2026 22:10:48 +0800
Subject: [PATCH] =?UTF-8?q?feat(agency):=20Agency=20=E5=9F=9F=E6=8E=A5?=
 =?UTF-8?q?=E5=8F=A3=E8=B7=AF=E5=BE=84=E5=88=87=20v3=EF=BC=88admin=20+=20m?=
 =?UTF-8?q?p=20=E4=B8=A4=E7=AB=AF=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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
---
 ...9_2561_agency模块路径切v3-修改接口-两端.md | 137 ++++++++++++++++++
 1 file changed, 137 insertions(+)
 create mode 100644 changelogs-v2/2026-05/19_2561_agency模块路径切v3-修改接口-两端.md

diff --git a/changelogs-v2/2026-05/19_2561_agency模块路径切v3-修改接口-两端.md b/changelogs-v2/2026-05/19_2561_agency模块路径切v3-修改接口-两端.md
new file mode 100644
index 0000000..d251f51
--- /dev/null
+++ b/changelogs-v2/2026-05/19_2561_agency模块路径切v3-修改接口-两端.md
@@ -0,0 +1,137 @@
+# 【修改接口·两端】Agency 模块路径切 v3
+
+> **更新时间**: 2026-05-19
+> **端类型**: 管理后台 + 小程序
+> **关联**: HL Issue [#2561](https://git.1814.love:8443/wx/HL/issues/2561) / PR [#2562](https://git.1814.love:8443/wx/HL/pulls/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. 修改前后对比（关键示例）
+
+### 旧调用
+
+```http
+GET /admin/travel-agency/page?pageNum=1&pageSize=10
+Authorization: Bearer {admin_jwt}
+```
+
+### 新调用
+
+```http
+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. 注意事项
+
+1. **必须改的请求方**：admin 管理后台 + 小程序 mp/agency 调用方
+2. **不需要改**：内部 Feign 调用方（mp-service 已通过 PR-2 内部切换，前端无感）
+3. **切换时机**：建议本周内完成，避免错过新功能升级窗口
+4. **测试方式**：本地 / 测试服并存期间，新旧 path 可同时调，对比响应一致
+5. **gateway 重启**：后端已 merge，gateway 重启后新路由生效（运维通知）
+
+---
+
+## 9. 关联 / 联系人
+
+- Issue: https://git.1814.love:8443/wx/HL/issues/2561
+- PR: https://git.1814.love:8443/wx/HL/pulls/2562
+- 前序 PRs: #2556（PR-1 骨架）/ #2558（PR-2 内部切换）
+- 方案文档: `.claude/PRPs/2026-05-18-v2-to-v3-agency-migration-plan.md`
+- 后端负责人: yst
+- 切换问题反馈: 在 PR #2562 评论