hl-api-changelog/changelogs/2026-05/06_feat_agency_management_module.md

旅行社公司管理模块上线

• 日期: 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 验证示例

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