# 旅行社公司管理模块上线

- 日期: 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