From 0db446c40904334a8e6f0cba51b5067633b60cb8 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Wed, 6 May 2026 15:16:33 +0800 Subject: [PATCH] =?UTF-8?q?fix:=20=E5=AE=8C=E5=96=84=E6=97=85=E8=A1=8C?= =?UTF-8?q?=E7=A4=BE=E5=85=AC=E5=8F=B8=E6=A8=A1=E5=9D=97=20changelog=20(PR?= =?UTF-8?q?=20#1710+#1711+#1712=20=E5=85=A8=E5=90=88=E5=B9=B6=20+=20?= =?UTF-8?q?=E6=B5=8B=E8=AF=95=E6=9C=8D=20round-trip=20=E5=B7=B2=E9=AA=8C)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../06_feat_agency_management_module.md | 145 +++++++++++------- 1 file changed, 91 insertions(+), 54 deletions(-) diff --git a/changelogs/2026-05/06_feat_agency_management_module.md b/changelogs/2026-05/06_feat_agency_management_module.md index 5a7102c..4151447 100644 --- a/changelogs/2026-05/06_feat_agency_management_module.md +++ b/changelogs/2026-05/06_feat_agency_management_module.md @@ -1,92 +1,129 @@ -# 旅行社公司管理模块上线 +# feat(agency): 旅行社公司管理新模块 + 产品绑定公司 (定稿) -- 日期: 2026-05-06 -- 通知对象: @mmg -- 后端 PR: wx/HL #1710 (Closes #1707) -- squash commit: 3ce00b61 -- 网关地址: https://api.test.1814.love:9443 +**日期**: 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 --- -## 一、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） | -| 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` | 下拉选项（产品编辑页用） | +| 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/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`) +### 2. 资质子表 (admin/agency/{agencyId}/qualification) | 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` 字段 - - V20260506_001：`NULL`（数据回填阶段） - - V20260507_001：`NOT NULL`（强制阶段） -- `ProductSaveReqVO` 必填 `agencyId` -- 历史产品已迁移到 `hulai`（主体公司） +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 路径。 --- -## 四、用户业务规则提醒 +## 四、产品端字段 (前端必改) -- "产品绑定公司 = 绑定商户号"，下单 mchId 永远走 `agency.default.payment.mchId` -- `product.mchId` 字段保留为只读历史回填字段，新订单创建路径不再读取 +- `ProductSaveReqVO` 必须传 `agencyId: Long` +- `ProductDetailVO` / Resp 增加 `agencyId / mchId` 字段 +- 产品编辑页"所属公司"下拉调 `/admin/agency/enabled` +- V20260507_001 部署后 `product.agency_id NOT NULL`, 漏传校验失败 --- -## 五、UI 建议（前端自由发挥） +## 五、订单端字段 -**admin 后台**：顶级菜单 "系统管理 > 旅行社公司管理" -- 左侧公司列表 + 右侧编辑面板 -- Tab 分三段：基础信息 / 资质附件 / 支付配置 - -**产品创建页**：新增 "所属公司" 下拉，调 `/admin/travel-agency/enabled` 接口。 +- `OrderInfo` 加 `agencyId Long` (V20260506_006 ALTER) +- 订单列表/详情 `mchName` 拼接走 `TravelAgencyService.getById`, 不再读 `OrderHelperService.MCH_NAMES` 静态映射 --- -## 六、curl 验证示例 +## 六、UI 建议 (前端自由发挥) + +**admin 后台**: 顶级菜单 "系统管理 > 旅行社公司管理" +- 左列表 + 右编辑面板, Tab 分 基础信息 / 资质附件 / 支付配置 三段 +- 主体公司用徽章高亮 (返字段 `isPrimary=1`) +- `status=DISABLED` 全局灰显 + +--- + +## 七、curl 验证示例 ```bash -TOK="" -curl -sk "https://api.test.1814.love:9443/admin/travel-agency/page?pageNum=1&pageSize=10" \ +# 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" -# 期望 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） -- 关闭工单: wx/HL #1707 -- 部署后 nacos 需补 `agency.payment.aes-key`（本期 fallback `encryption.aes-key`） +- PR #1710 / #1711 / #1712 全 merge dev +- 工单 wx/HL #1707 closed (有 closing comment + status/已完成 label) ---