feat(contract): 拆分 12301 合同方案 changelog 为 3 份独立文档(附件 Tab/导游 Tab/出行人字段) - 前端 mmg 重新阅读

2026-05-01 15:51:00 +08:00
@@ -0,0 +1,120 @@
+# 合同方案管理页 — 新增「导游管理」Tab
+
+**类型**: 后端新接口
+**前端处理者**: mmg
+**日期**: 2026-05-01
+**关联**: 工单 #1590 / PR #1592
+**影响页面**: 管理后台「合同管理 → 合同方案 → 编辑方案」
+
+---
+
+## 这是什么
+
+合同方案现在可以配导游名单。生成 12301 合同时，方案下配的导游会**作为合同条款的一部分上报到 12301 平台**（合同正文显示导游姓名/电话/导游证号）。
+
+**业务规则**：
+- **不强制**：自驾产品 / 不带团产品**没导游就不配，留空数组即可**（用户原话："导游有的产品没有"）
+- **方案级配置**：一个方案对应一组默认导游（同一线路通常配同一批导游）
+- 后端**永远不会兜底**到经办人，没配就 12301 上报空导游列表
+
+---
+
+## UI 需求
+
+在合同方案编辑页加一个 **「导游管理」Tab**，里面：
+
+1. **导游列表表格**：
+   - 列：姓名 / 手机号 / 导游证号 / 排序号 / 创建时间 / 操作
+   - 操作：编辑 / 删除
+
+2. **新增按钮**：
+   - 点击 → 弹窗表单
+   - 字段（详见下方接口）
+   - 提交 → POST 接口
+
+3. **编辑**：
+   - 复用同一弹窗，PUT 接口
+
+4. **删除二次确认**
+
+---
+
+## 接口
+
+**Base path**: `/admin/contract/scheme/{schemeId}/tour-guides`
+
+### 1. 查询导游列表
+
+```
+GET /admin/contract/scheme/{schemeId}/tour-guides
+
+→ 200
+{
+  "code": 200,
+  "data": [
+    {
+      "guideId": "2049915142757388290",   // String 雪花
+      "schemeId": 3,
+      "name": "李导",
+      "phone": "13800138000",              // 后端已用 EncryptTypeHandler 自动加解密
+      "licenseNumber": "L-NMG-100953",
+      "sortOrder": 1,
+      "createTime": "2026-05-01 10:13:50"
+    }
+  ]
+}
+```
+
+**返回空列表**（`data: []`）很正常 — 该方案没配导游。
+
+### 2. 新增导游
+
+```
+POST /admin/contract/scheme/{schemeId}/tour-guides
+Content-Type: application/json
+
+{
+  "name": "李导",                  // 必填, ≤50 字
+  "phone": "13800138000",          // 选填, 11 位手机号(13/14/15/16/17/18/19 开头)
+  "licenseNumber": "L-NMG-100953", // 选填, ≤64 字
+  "sortOrder": 1                   // 选填, 默认 0, 越小越前
+}
+
+→ 200 { "code": 200, "data": { ... 含新 guideId } }
+```
+
+**校验**：
+- name 不能空
+- phone 格式 `^$|^1[3-9]\d{9}$`（允许空 OR 11 位手机号）
+- 长度限制后端已校验，前端可加客户端校验提升体验
+
+### 3. 修改导游
+
+```
+PUT /admin/contract/scheme/{schemeId}/tour-guides/{guideId}
+Content-Type: application/json
+
+{ ...同 POST body... }
+
+→ 200 { "code": 200, "data": { ... 同 GET 单条结构 } }
+```
+
+### 4. 删除导游（软删除）
+
+```
+DELETE /admin/contract/scheme/{schemeId}/tour-guides/{guideId}
+
+→ 200 { "code": 200, "data": null }
+```
+
+---
+
+## 测试服已就绪
+
+`https://api.test.1814.love:9443/admin/contract/scheme/3/tour-guides` GET 立即可调（admin token 可用 wx 账号登录拿）。
+
+---
+
+## 服务重启
+
+后端已上线，前端开发完直接对接。