diff --git a/changelogs/2026-05/06_fix_agency_admin_path_correction.md b/changelogs/2026-05/06_fix_agency_admin_path_correction.md new file mode 100644 index 0000000..c78acd6 --- /dev/null +++ b/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