合同方案管理页 — 新增「导游管理」Tab

类型: 后端新接口 前端处理者: mmg 日期: 2026-05-01 关联: 工单 #1590 / PR #1592 影响页面: 管理后台「合同管理 → 合同方案 → 编辑方案」

这是什么

合同方案现在可以配导游名单。生成 12301 合同时，方案下配的导游会作为合同条款的一部分上报到 12301 平台（合同正文显示导游姓名/电话/导游证号）。

业务规则：

不强制：自驾产品 / 不带团产品没导游就不配，留空数组即可（用户原话："导游有的产品没有"）
方案级配置：一个方案对应一组默认导游（同一线路通常配同一批导游）
后端永远不会兜底到经办人，没配就 12301 上报空导游列表

UI 需求

在合同方案编辑页加一个 「导游管理」Tab，里面：

导游列表表格：
- 列：姓名 / 手机号 / 导游证号 / 排序号 / 创建时间 / 操作
- 操作：编辑 / 删除
新增按钮：
- 点击 → 弹窗表单
- 字段（详见下方接口）
- 提交 → POST 接口
编辑：
- 复用同一弹窗，PUT 接口
删除二次确认

接口

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 账号登录拿）。

服务重启

后端已上线，前端开发完直接对接。

3.0 KiB 原始文件 Blame 文件历史 Unescape Escape