fix(agency): admin path 纠回设计冻结的 /admin/travel-agency — 全量推送 mmg

独立 hotfix changelog 强提示前端必改请求 path:
- admin 端 /admin/agency/* 全部改回 /admin/travel-agency/*
- mp 端 /mp/agency/* 不变
- 完整 path 对照表 (主体 CRUD + 资质 + 支付)
- 测试服 round-trip 验证 (新 path 200, 旧 path 404)
- 前端最小改动建议 (字符串替换)

关联 PR: wx/HL #1715 (已 merge dev + 测试服部署完成)
关联文档: 06_feat_agency_management_module.md (已同步 patch)

cc @mmg

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

changelogs/2026-05/06_fix_agency_admin_path_correction.md

@@ -0,0 +1,130 @@
+# fix(agency): admin 接口 path 从 /admin/agency 纠回设计冻结的 /admin/travel-agency
+
+**日期**: 2026-05-06 15:39
+**通知对象**: @mmg (前端) — **必须改前端 baseURL/请求 path**
+**关联 PR**: wx/HL #1715 (已 merge dev + 测试服部署完成 + round-trip 验证通过)
+**关联文档**: `06_feat_agency_management_module.md` (定稿已同步 patch)
+
+---
+
+## ⚠️ 一句话摘要
+
+**所有 admin 端旅行社公司接口的 path 已经从 `/admin/agency/*` 改回设计文档冻结的 `/admin/travel-agency/*`。前端必须改请求 path,旧 path 测试服已 HTTP 404。**
+
+---
+
+## 一、为什么要改
+
+| 阶段 | path | 状态 |
+|------|------|------|
+| 设计文档 (PRD 冻结) | `/admin/travel-agency/*` | ✅ 真相源 |
+| 代码副本 A 实施 (PR #1710) | `/admin/agency/*` | ❌ 擅自缩短,与设计漂移 |
+| changelog 第一版 (2026-05-06 15:13) | `/admin/agency/*` | ❌ 跟着实施漂 |
+| 前端实际调用 | `/admin/travel-agency/*` | ✅ 按设计文档调用 |
+| 测试服 gateway 路由 | `/admin/agency/**` | ❌ 前端 404 |
+| **本次纠回 (PR #1715, 2026-05-06 15:39)** | `/admin/travel-agency/*` | ✅ **代码 + gateway + changelog 三处全部对齐设计** |
+
+**纠回原则**: 代码必须和告知前端的契约一致,设计文档是唯一真相源。
+
+---
+
+## 二、path 全量对照表 (前端必改)
+
+### 1. 主体 CRUD (admin)
+
+| Method | 旧 path (HTTP 404) | 新 path (前端必改) |
+|--------|------------|------------|
+| GET | ~~`/admin/agency/page`~~ | `/admin/travel-agency/page` |
+| GET | ~~`/admin/agency/{id}`~~ | `/admin/travel-agency/{id}` |
+| GET | ~~`/admin/agency/enabled`~~ | `/admin/travel-agency/enabled` |
+| POST | ~~`/admin/agency`~~ | `/admin/travel-agency` |
+| PUT | ~~`/admin/agency/{id}`~~ | `/admin/travel-agency/{id}` |
+| POST | ~~`/admin/agency/{id}/disable`~~ | `/admin/travel-agency/{id}/disable` |
+| POST | ~~`/admin/agency/{id}/set-primary`~~ | `/admin/travel-agency/{id}/set-primary` |
+| DELETE | ~~`/admin/agency/{id}`~~ | `/admin/travel-agency/{id}` |
+
+### 2. 资质子表
+
+| Method | 旧 path | 新 path |
+|--------|------------|------------|
+| GET | ~~`/admin/agency/{agencyId}/qualification`~~ | `/admin/travel-agency/{agencyId}/qualification` |
+| POST | ~~`/admin/agency/{agencyId}/qualification`~~ | `/admin/travel-agency/{agencyId}/qualification` |
+| PUT | ~~`/admin/agency/{agencyId}/qualification/{id}`~~ | `/admin/travel-agency/{agencyId}/qualification/{id}` |
+| DELETE | ~~`/admin/agency/{agencyId}/qualification/{id}`~~ | `/admin/travel-agency/{agencyId}/qualification/{id}` |
+
+### 3. 支付子表
+
+| Method | 旧 path | 新 path |
+|--------|------------|------------|
+| GET | ~~`/admin/agency/{agencyId}/payment`~~ | `/admin/travel-agency/{agencyId}/payment` |
+| POST | ~~`/admin/agency/{agencyId}/payment`~~ | `/admin/travel-agency/{agencyId}/payment` |
+| PUT | ~~`/admin/agency/{agencyId}/payment/{paymentId}`~~ | `/admin/travel-agency/{agencyId}/payment/{paymentId}` |
+| DELETE | ~~`/admin/agency/{agencyId}/payment/{paymentId}`~~ | `/admin/travel-agency/{agencyId}/payment/{paymentId}` |
+| POST | ~~`/admin/agency/{agencyId}/payment/{paymentId}/set-default`~~ | `/admin/travel-agency/{agencyId}/payment/{paymentId}/set-default` |
+
+### 4. mp 端 (无变化)
+
+`/mp/agency/primary` **不变** (本次仅纠 admin path,mp 端 path 与设计一致,不动)。
+
+---
+
+## 三、前端最小改动建议
+
+如果前端封装了 axios 公司模块的 baseURL/path,只需把字符串 `admin/agency` → `admin/travel-agency` 全文替换即可:
+
+```bash
+# hl-ui 前端项目根:
+# Linux/Mac
+grep -rn "admin/agency" src/ --include="*.js" --include="*.vue" --include="*.ts"
+# Windows PowerShell
+Select-String -Path src/**/*.{js,vue,ts} -Pattern "admin/agency"
+# 然后批量替换 admin/agency → admin/travel-agency
+```
+
+---
+
+## 四、测试服 round-trip 验证 (2026-05-06 15:39)
+
+```bash
+# 拿 admin token
+TOK=$(curl -sk -X POST "https://api.test.1814.love:9443/admin/auth/login" \
+  -H "Content-Type: application/json" \
+  -d '{"username":"admin","password":"Admin@123456"}' \
+  | python -c "import json,sys; print(json.load(sys.stdin)['data']['token'])")
+
+# ✅ 新 path 返 200 + 3 家公司明文
+curl -sk "https://api.test.1814.love:9443/admin/travel-agency/enabled" \
+  -H "Authorization: Bearer $TOK"
+# {"code":200,"message":"成功","data":[
+#   {"agencyId":"...","code":"hulai","agencyName":"内蒙古呼籁...","isPrimary":1},
+#   {"agencyId":"...","code":"qianshou","agencyName":"内蒙古呼籁牵手..."},
+#   {"agencyId":"...","code":"hulai-wenlu","agencyName":"内蒙古呼籁文旅..."}
+# ]}
+
+# ❌ 旧 path 测试服已 HTTP 404
+curl -sk -w "\nHTTP %{http_code}\n" "https://api.test.1814.love:9443/admin/agency/enabled"
+# {"timestamp":"...","path":"/admin/agency/enabled","status":404,"error":"Not Found"}
+# HTTP 404
+```
+
+---
+
+## 五、影响面
+
+- **admin 后台 (前端必改)**: 旅行社公司管理模块所有 admin 接口 path
+- **mp 端**: ⛔ 无影响 (mp 端 path 没变)
+- **后端代码**: ✅ controller @RequestMapping + gateway routes 已对齐, internal Feign + 单测无影响
+- **数据**: ✅ 无 schema/数据变化, 仅 path 字符串改名
+
+---
+
+## 六、相关 commit
+
+- wx/HL PR #1710 (定稿主 PR, 含偏离的 path)
+- wx/HL PR #1711 (runtime hotfix)
+- wx/HL PR #1712 (gateway 白名单 hotfix)
+- **wx/HL PR #1715 (本次 path 纠回, dev 已合 + 测试服已部署 + round-trip 通过)**
+
+---
+
+cc @mmg