feat(agency): 旅行社公司管理模块 admin/mp 接口上线 (wx/HL #1710)

changelogs/2026-05/06_feat_agency_management_module.md

@@ -0,0 +1,93 @@
+# 旅行社公司管理模块上线
+
+- 日期: 2026-05-06
+- 通知对象: @mmg
+- 后端 PR: wx/HL #1710 (Closes #1707)
+- squash commit: 3ce00b61
+- 网关地址: https://api.test.1814.love:9443
+
+---
+
+## 一、admin 端新增接口
+
+### 1. 旅行社主体 CRUD (`/admin/travel-agency/**`)
+
+| Method | Path | 说明 |
+|--------|------|------|
+| POST | `/admin/travel-agency` | 新建公司（SUPER_ADMIN） |
+| PUT | `/admin/travel-agency/{id}` | 编辑 |
+| POST | `/admin/travel-agency/{id}/disable` | 停用（status=DISABLED，主体不可停） |
+| DELETE | `/admin/travel-agency/{id}` | 软删（SUPER_ADMIN，主体/有引用不可删） |
+| POST | `/admin/travel-agency/{id}/set-primary` | 设为主体（全局唯一） |
+| GET | `/admin/travel-agency/page?pageNum=1&pageSize=10&...` | 分页 |
+| GET | `/admin/travel-agency/{id}` | 详情 |
+| GET | `/admin/travel-agency/enabled` | 下拉选项（产品编辑页用） |
+
+### 2. 资质附件 (`/admin/travel-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 / 许可证号 / 电话 / 地址 等） |
+
+---
+
+## 三、产品端字段变更
+
+- `product` 表新增 `agencyId Long` 字段
+  - V20260506_001：`NULL`（数据回填阶段）
+  - V20260507_001：`NOT NULL`（强制阶段）
+- `ProductSaveReqVO` 必填 `agencyId`
+- 历史产品已迁移到 `hulai`（主体公司）
+
+---
+
+## 四、用户业务规则提醒
+
+- "产品绑定公司 = 绑定商户号"，下单 mchId 永远走 `agency.default.payment.mchId`
+- `product.mchId` 字段保留为只读历史回填字段，新订单创建路径不再读取
+
+---
+
+## 五、UI 建议（前端自由发挥）
+
+**admin 后台**：顶级菜单 "系统管理 > 旅行社公司管理"
+- 左侧公司列表 + 右侧编辑面板
+- Tab 分三段：基础信息 / 资质附件 / 支付配置
+
+**产品创建页**：新增 "所属公司" 下拉，调 `/admin/travel-agency/enabled` 接口。
+
+---
+
+## 六、curl 验证示例
+
+```bash
+TOK="<admin token>"
+curl -sk "https://api.test.1814.love:9443/admin/travel-agency/page?pageNum=1&pageSize=10" \
+  -H "Authorization: Bearer $TOK"
+# 期望 records 含 hulai / qianshou / hulai-wenlu 三家
+```
+
+---
+
+## 七、关联 Issue 与部署
+
+- 后端 PR: wx/HL #1710（squash 3ce00b61）
+- 关闭工单: wx/HL #1707
+- 部署后 nacos 需补 `agency.payment.aes-key`（本期 fallback `encryption.aes-key`）
+
+---
+
+cc @mmg