23c32d42ff
PR #1710 定稿 changelog 误标 path 为 /admin/agency (副本 A 实施漂移), 现已纠回设计冻结的 /admin/travel-agency。 代码 + 网关路由 + 本文档全部对齐: - AdminTravelAgencyController + Qualification + Payment 三个 controller - hl-gateway/application.yml order-service 路由 - 旧 path /admin/agency 已关闭 (HTTP 404) 测试服 round-trip (2026-05-06 15:39): - GET /admin/travel-agency/enabled → code:200, 3 家公司列表 - GET /admin/travel-agency/page → code:200, 完整分页数据 - GET /admin/agency/* → HTTP 404 (旧 path 已下线) cc @mmg (前端联调请改 baseURL/请求 path) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
131 行
5.5 KiB
Markdown
131 行
5.5 KiB
Markdown
# feat(agency): 旅行社公司管理新模块 + 产品绑定公司 (定稿)
|
|
|
|
**日期**: 2026-05-06
|
|
**通知对象**: @mmg (前端)
|
|
**关联 PR**: wx/HL #1710 (主) + #1711 (runtime hotfix) + #1712 (gateway 白名单 hotfix) + #1715 (admin path 纠回设计冻结的 travel-agency)
|
|
**关联工单**: wx/HL #1707 closed
|
|
**测试服已部署 + round-trip 验证通过**: 2026-05-06 15:13 (旧 path /admin/agency)、2026-05-06 15:39 (新 path /admin/travel-agency, PR #1715 部署完成)
|
|
|
|
---
|
|
|
|
## 一、部署状态 (测试服 https://api.test.1814.love:9443)
|
|
|
|
| 接口 | round-trip 验证 |
|
|
|---|---|
|
|
| GET /admin/travel-agency/page | ✅ 200 / 3 家明文 |
|
|
| GET /admin/travel-agency/{id} | ✅ 200 / 完整公司信息 |
|
|
| GET /admin/travel-agency/enabled | ✅ 200 / 下拉选项 |
|
|
| GET /admin/travel-agency/{id}/qualification | ✅ 200 / 资质列表 |
|
|
| GET /admin/travel-agency/{id}/payment | ✅ 200 / 支付配置列表 |
|
|
| GET /mp/agency/primary | ✅ 200 / 主体公司公开信息(无需登录) |
|
|
|
|
---
|
|
|
|
## 二、后端接口 (网关 admin/travel-agency)
|
|
|
|
> ⚠️ **2026-05-06 15:35 更正 (PR #1715)**: 前一版本 changelog 误将 path 标为 `/admin/agency` (副本 A 实施漂移设计文档)。现已纠回设计冻结的 `/admin/travel-agency`,代码 + 网关路由 + 本文档全部对齐。**前端请用 `/admin/travel-agency` 调用**。
|
|
|
|
### 1. 主体 CRUD (admin)
|
|
|
|
| Method | Path | 说明 |
|
|
|--------|------|------|
|
|
| GET | `/admin/travel-agency/page?pageNum=&pageSize=&code=&agencyName=&status=` | 公司列表(分页) |
|
|
| GET | `/admin/travel-agency/{id}` | 详情 |
|
|
| GET | `/admin/travel-agency/enabled` | 启用列表(下拉用, `List<{id,code,agencyName}>`) |
|
|
| POST | `/admin/travel-agency` | 新建 (SUPER_ADMIN) |
|
|
| PUT | `/admin/travel-agency/{id}` | 编辑 |
|
|
| POST | `/admin/travel-agency/{id}/disable` | 停用 (主体不可停, 引用产品也不可) |
|
|
| POST | `/admin/travel-agency/{id}/set-primary` | 设为主体 (全局唯一 STORED 生成列+UNIQUE 兜底) |
|
|
| DELETE | `/admin/travel-agency/{id}` | 软删 (SUPER_ADMIN, 主体/有引用拒绝) |
|
|
|
|
### 2. 资质子表 (admin/agency/{agencyId}/qualification)
|
|
|
|
| Method | Path | 说明 |
|
|
|--------|------|------|
|
|
| GET | `/admin/travel-agency/{agencyId}/qualification` | 列表 |
|
|
| POST | `/admin/travel-agency/{agencyId}/qualification` (multipart) | 上传 (name + file + sortOrder + remark + 可选 issueDate/expireDate) |
|
|
| PUT | `/admin/travel-agency/{agencyId}/qualification/{id}` | 编辑 |
|
|
| DELETE | `/admin/travel-agency/{agencyId}/qualification/{id}` | 删除 |
|
|
|
|
- 文件类型白名单: PDF / JPG / PNG / JPEG (后续可加字典 `qualification_file_type`)
|
|
|
|
### 3. 支付子表 (admin/agency/{agencyId}/payment)
|
|
|
|
| Method | Path | 说明 |
|
|
|--------|------|------|
|
|
| GET | `/admin/travel-agency/{agencyId}/payment` | 列表 |
|
|
| POST | `/admin/travel-agency/{agencyId}/payment` | 新增 (mchId + apiV3Key + mchSerialNo + publicKeyId + isDefault) |
|
|
| PUT | `/admin/travel-agency/{agencyId}/payment/{paymentId}` | 编辑 (加密字段密文返回, 编辑用 placeholder) |
|
|
| DELETE | `/admin/travel-agency/{agencyId}/payment/{paymentId}` | 删除 |
|
|
| POST | `/admin/travel-agency/{agencyId}/payment/{paymentId}/set-default` | 设为默认 mchId |
|
|
|
|
### 4. mp 端 (无需登录)
|
|
|
|
| Method | Path | 说明 |
|
|
|--------|------|------|
|
|
| GET | `/mp/agency/primary` | 主体公司公开信息 (name + 许可证 + 客服电话 + 地址) |
|
|
|
|
---
|
|
|
|
## 三、关键业务规则
|
|
|
|
1. **产品绑定公司 = 绑定商户号** — 用户原话 (2026-05-06): "下单只能是这个商户号了"。创建产品必填 `agencyId`, 下单 `mchId` 永远走 `agency.default.payment.mchId`, `productMchId` 不再被读取。
|
|
2. **历史产品默认填主体公司 hulai** — V20260506_001 + V20260506_006 全行回填 (含软删 12371 条)。
|
|
3. **主体公司全局唯一** — STORED 生成列 `primary_lock` + UNIQUE 兜底。
|
|
4. **加密字段 (apiV3Key/mchSerialNo)** — admin 后台需手动补录, `AgencyDataInitializer` 启动只 UPSERT 主表 + 默认 mchId/cert 路径。
|
|
|
|
---
|
|
|
|
## 四、产品端字段 (前端必改)
|
|
|
|
- `ProductSaveReqVO` 必须传 `agencyId: Long`
|
|
- `ProductDetailVO` / Resp 增加 `agencyId / mchId` 字段
|
|
- 产品编辑页"所属公司"下拉调 `/admin/travel-agency/enabled`
|
|
- V20260507_001 部署后 `product.agency_id NOT NULL`, 漏传校验失败
|
|
|
|
---
|
|
|
|
## 五、订单端字段
|
|
|
|
- `OrderInfo` 加 `agencyId Long` (V20260506_006 ALTER)
|
|
- 订单列表/详情 `mchName` 拼接走 `TravelAgencyService.getById`, 不再读 `OrderHelperService.MCH_NAMES` 静态映射
|
|
|
|
---
|
|
|
|
## 六、UI 建议 (前端自由发挥)
|
|
|
|
**admin 后台**: 顶级菜单 "系统管理 > 旅行社公司管理"
|
|
- 左列表 + 右编辑面板, Tab 分 基础信息 / 资质附件 / 支付配置 三段
|
|
- 主体公司用徽章高亮 (返字段 `isPrimary=1`)
|
|
- `status=DISABLED` 全局灰显
|
|
|
|
---
|
|
|
|
## 七、curl 验证示例
|
|
|
|
```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'])")
|
|
|
|
# 公司列表
|
|
curl -sk "https://api.test.1814.love:9443/admin/travel-agency/page?pageNum=1&pageSize=10" \
|
|
-H "Authorization: Bearer $TOK"
|
|
|
|
# 主体公司公开信息 (mp 端用, 不需 token)
|
|
curl -sk "https://api.test.1814.love:9443/mp/agency/primary"
|
|
```
|
|
|
|
---
|
|
|
|
## 八、关联文档
|
|
|
|
- PR #1710 / #1711 / #1712 全 merge dev
|
|
- 工单 wx/HL #1707 closed (有 closing comment + status/已完成 label)
|
|
|
|
---
|
|
|
|
cc @mmg
|