# 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
