# 合同方案管理页 — 新增「导游管理」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 账号登录拿）。

---

## 服务重启

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