fix: 完善旅行社公司模块 changelog (PR #1710+#1711+#1712 全合并 + 测试服 round-trip 已验)

changelogs/2026-05/06_feat_agency_management_module.md

@@ -1,92 +1,129 @@
-# 旅行社公司管理模块上线
+# feat(agency): 旅行社公司管理新模块 + 产品绑定公司 (定稿)
 
-- 日期: 2026-05-06
+**日期**: 2026-05-06
-- 通知对象: @mmg
+**通知对象**: @mmg (前端)
-- 后端 PR: wx/HL #1710 (Closes #1707)
+**关联 PR**: wx/HL #1710 (主) + #1711 (runtime hotfix) + #1712 (gateway 白名单 hotfix)
-- squash commit: 3ce00b61
+**关联工单**: wx/HL #1707 closed
-- 网关地址: https://api.test.1814.love:9443
+**测试服已部署 + round-trip 验证通过**: 2026-05-06 15:13
 
 ---
 
-## 一、admin 端新增接口
+## 一、部署状态 (测试服 https://api.test.1814.love:9443)
 
-### 1. 旅行社主体 CRUD (`/admin/travel-agency/**`)
+| 接口 | round-trip 验证 |
+|---|---|
+| GET /admin/agency/page | ✅ 200 / 3 家明文 |
+| GET /admin/agency/{id} | ✅ 200 / 完整公司信息 |
+| GET /admin/agency/enabled | ✅ 200 / 下拉选项 |
+| GET /admin/agency/{id}/qualification | ✅ 200 / 资质列表 |
+| GET /admin/agency/{id}/payment | ✅ 200 / 支付配置列表 |
+| GET /mp/agency/primary | ✅ 200 / 主体公司公开信息(无需登录) |
+
+---
+
+## 二、后端接口 (网关 admin/agency)
+
+> 实际 controller `@RequestMapping` 路径是 `/admin/agency` (不是 /admin/travel-agency)。前端联调请用此路径。
+
+### 1. 主体 CRUD (admin)
 
 | Method | Path | 说明 |
 |--------|------|------|
-| POST | `/admin/travel-agency` | 新建公司（SUPER_ADMIN） |
+| GET | `/admin/agency/page?pageNum=&pageSize=&code=&agencyName=&status=` | 公司列表(分页) |
-| PUT | `/admin/travel-agency/{id}` | 编辑 |
+| GET | `/admin/agency/{id}` | 详情 |
-| POST | `/admin/travel-agency/{id}/disable` | 停用（status=DISABLED，主体不可停） |
+| GET | `/admin/agency/enabled` | 启用列表(下拉用, `List<{id,code,agencyName}>`) |
-| DELETE | `/admin/travel-agency/{id}` | 软删（SUPER_ADMIN，主体/有引用不可删） |
+| POST | `/admin/agency` | 新建 (SUPER_ADMIN) |
-| POST | `/admin/travel-agency/{id}/set-primary` | 设为主体（全局唯一） |
+| PUT | `/admin/agency/{id}` | 编辑 |
-| GET | `/admin/travel-agency/page?pageNum=1&pageSize=10&...` | 分页 |
+| POST | `/admin/agency/{id}/disable` | 停用 (主体不可停, 引用产品也不可) |
-| GET | `/admin/travel-agency/{id}` | 详情 |
+| POST | `/admin/agency/{id}/set-primary` | 设为主体 (全局唯一 STORED 生成列+UNIQUE 兜底) |
-| GET | `/admin/travel-agency/enabled` | 下拉选项（产品编辑页用） |
+| DELETE | `/admin/agency/{id}` | 软删 (SUPER_ADMIN, 主体/有引用拒绝) |
 
-### 2. 资质附件 (`/admin/travel-agency/{agencyId}/qualification/**`)
+### 2. 资质子表 (admin/agency/{agencyId}/qualification)
-
-- POST / GET / PUT / DELETE 标准 CRUD
-- 支持开放式名称 + 文件类型白名单（PDF / JPG / PNG / JPEG）
-
-### 3. 商户支付配置 (`/admin/travel-agency/{agencyId}/payment/**`)
-
-- POST / GET / PUT / DELETE CRUD
-- POST `/admin/travel-agency/{agencyId}/payment/{paymentId}/set-default` 设为默认 mchId
-- 加密字段 `apiV3Key` / `mchSerialNo`：前端不返明文，编辑时使用占位密码框
-
----
-
-## 二、mp 端 (`/mp/agency`)
 
 | Method | Path | 说明 |
 |--------|------|------|
-| GET | `/mp/agency/primary` | 主体公司公开信息（name / 许可证号 / 电话 / 地址 等） |
+| GET | `/admin/agency/{agencyId}/qualification` | 列表 |
+| POST | `/admin/agency/{agencyId}/qualification` (multipart) | 上传 (name + file + sortOrder + remark + 可选 issueDate/expireDate) |
+| PUT | `/admin/agency/{agencyId}/qualification/{id}` | 编辑 |
+| DELETE | `/admin/agency/{agencyId}/qualification/{id}` | 删除 |
+
+- 文件类型白名单: PDF / JPG / PNG / JPEG (后续可加字典 `qualification_file_type`)
+
+### 3. 支付子表 (admin/agency/{agencyId}/payment)
+
+| Method | Path | 说明 |
+|--------|------|------|
+| GET | `/admin/agency/{agencyId}/payment` | 列表 |
+| POST | `/admin/agency/{agencyId}/payment` | 新增 (mchId + apiV3Key + mchSerialNo + publicKeyId + isDefault) |
+| PUT | `/admin/agency/{agencyId}/payment/{paymentId}` | 编辑 (加密字段密文返回, 编辑用 placeholder) |
+| DELETE | `/admin/agency/{agencyId}/payment/{paymentId}` | 删除 |
+| POST | `/admin/agency/{agencyId}/payment/{paymentId}/set-default` | 设为默认 mchId |
+
+### 4. mp 端 (无需登录)
+
+| Method | Path | 说明 |
+|--------|------|------|
+| GET | `/mp/agency/primary` | 主体公司公开信息 (name + 许可证 + 客服电话 + 地址) |
 
 ---
 
-## 三、产品端字段变更
+## 三、关键业务规则
 
-- `product` 表新增 `agencyId Long` 字段
+1. **产品绑定公司 = 绑定商户号** — 用户原话 (2026-05-06): "下单只能是这个商户号了"。创建产品必填 `agencyId`, 下单 `mchId` 永远走 `agency.default.payment.mchId`, `productMchId` 不再被读取。
-  - V20260506_001：`NULL`（数据回填阶段）
+2. **历史产品默认填主体公司 hulai** — V20260506_001 + V20260506_006 全行回填 (含软删 12371 条)。
-  - V20260507_001：`NOT NULL`（强制阶段）
+3. **主体公司全局唯一** — STORED 生成列 `primary_lock` + UNIQUE 兜底。
-- `ProductSaveReqVO` 必填 `agencyId`
+4. **加密字段 (apiV3Key/mchSerialNo)** — admin 后台需手动补录, `AgencyDataInitializer` 启动只 UPSERT 主表 + 默认 mchId/cert 路径。
-- 历史产品已迁移到 `hulai`（主体公司）
 
 ---
 
-## 四、用户业务规则提醒
+## 四、产品端字段 (前端必改)
 
-- "产品绑定公司 = 绑定商户号"，下单 mchId 永远走 `agency.default.payment.mchId`
+- `ProductSaveReqVO` 必须传 `agencyId: Long`
-- `product.mchId` 字段保留为只读历史回填字段，新订单创建路径不再读取
+- `ProductDetailVO` / Resp 增加 `agencyId / mchId` 字段
+- 产品编辑页"所属公司"下拉调 `/admin/agency/enabled`
+- V20260507_001 部署后 `product.agency_id NOT NULL`, 漏传校验失败
 
 ---
 
-## 五、UI 建议（前端自由发挥）
+## 五、订单端字段
 
-**admin 后台**：顶级菜单 "系统管理 > 旅行社公司管理"
+- `OrderInfo` 加 `agencyId Long` (V20260506_006 ALTER)
-- 左侧公司列表 + 右侧编辑面板
+- 订单列表/详情 `mchName` 拼接走 `TravelAgencyService.getById`, 不再读 `OrderHelperService.MCH_NAMES` 静态映射
-- Tab 分三段：基础信息 / 资质附件 / 支付配置
-
-**产品创建页**：新增 "所属公司" 下拉，调 `/admin/travel-agency/enabled` 接口。
 
 ---
 
-## 六、curl 验证示例
+## 六、UI 建议 (前端自由发挥)
+
+**admin 后台**: 顶级菜单 "系统管理 > 旅行社公司管理"
+- 左列表 + 右编辑面板, Tab 分 基础信息 / 资质附件 / 支付配置 三段
+- 主体公司用徽章高亮 (返字段 `isPrimary=1`)
+- `status=DISABLED` 全局灰显
+
+---
+
+## 七、curl 验证示例
 
 ```bash
-TOK="<admin token>"
+# admin 拿 token
-curl -sk "https://api.test.1814.love:9443/admin/travel-agency/page?pageNum=1&pageSize=10" \
+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/agency/page?pageNum=1&pageSize=10" \
   -H "Authorization: Bearer $TOK"
-# 期望 records 含 hulai / qianshou / hulai-wenlu 三家
+
+# 主体公司公开信息 (mp 端用, 不需 token)
+curl -sk "https://api.test.1814.love:9443/mp/agency/primary"
 ```
 
 ---
 
-## 七、关联 Issue 与部署
+## 八、关联文档
 
-- 后端 PR: wx/HL #1710（squash 3ce00b61）
+- PR #1710 / #1711 / #1712 全 merge dev
-- 关闭工单: wx/HL #1707
+- 工单 wx/HL #1707 closed (有 closing comment + status/已完成 label)
-- 部署后 nacos 需补 `agency.payment.aes-key`（本期 fallback `encryption.aes-key`）
 
 ---