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

feat(agency): 旅行社公司管理新模块 + 产品绑定公司 (定稿)

日期: 2026-05-06 通知对象: @mmg (前端) 关联 PR: wx/HL #1710 (主) + #1711 (runtime hotfix) + #1712 (gateway 白名单 hotfix) 关联工单: wx/HL #1707 closed 测试服已部署 + round-trip 验证通过: 2026-05-06 15:13

---

一、部署状态 (测试服 https://api.test.1814.love:9443)

接口	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	说明
GET	/admin/agency/page?pageNum=&pageSize=&code=&agencyName=&status=	公司列表(分页)
GET	/admin/agency/{id}	详情
GET	/admin/agency/enabled	启用列表(下拉用, List<{id,code,agencyName}>)
POST	/admin/agency	新建 (SUPER_ADMIN)
PUT	/admin/agency/{id}	编辑
POST	/admin/agency/{id}/disable	停用 (主体不可停, 引用产品也不可)
POST	/admin/agency/{id}/set-primary	设为主体 (全局唯一 STORED 生成列+UNIQUE 兜底)
DELETE	/admin/agency/{id}	软删 (SUPER_ADMIN, 主体/有引用拒绝)

2. 资质子表 (admin/agency/{agencyId}/qualification)

Method	Path	说明
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 + 许可证 + 客服电话 + 地址)

---

三、关键业务规则

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/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 验证示例

# 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/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