# 【修改接口·两端】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 评论
