feat(contract): 拆分 12301 合同方案 changelog 为 3 份独立文档(附件 Tab/导游 Tab/出行人字段) - 前端 mmg 重新阅读
这个提交包含在：
API Changelog Bot
父节点
1773e51a74
当前提交
f26e27da44
@ -1,233 +0,0 @@
|
|||||||
# 12301 合同 2026 spec 完整对齐: 新增附件管理 + 导游名单 + 出行人民族/同住分组录入
|
|
||||||
|
|
||||||
**类型**: 后端新接口 + 字段扩展
|
|
||||||
**关联**: 工单 #1590 / PR #1592
|
|
||||||
**日期**: 2026-05-01
|
|
||||||
**前端处理者**: mmg
|
|
||||||
**影响范围**: 管理后台「合同方案管理」+「订单出行人录入」+「合同生成」三块联动改造
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 背景
|
|
||||||
|
|
||||||
用户反馈 12301 国家旅游服务监管平台合同上报字段大量空白,本 PR 完整对齐 2026 spec:
|
|
||||||
|
|
||||||
- 12301 上报 21 个原本声明但未接通的 setter 全接通(投诉详细地址 / 合同份数 / 营业网点 / 付款明细 / 同住名单 / 导游列表 / race / nationality / 行程附件 / 自费购物 / 紧急联系人等)
|
|
||||||
- 新增 2 张子表 `contract_scheme_attachment` + `contract_tour_guide`(管理后台需要 UI 对应)
|
|
||||||
- `order_traveler` 加 `race`(民族) + `room_group_no`(同住分组号)
|
|
||||||
- 行程 PDF 自动生成上传 OSS 嵌入 12301 attachments[] 节点
|
|
||||||
|
|
||||||
业务规则锁定(用户明确):
|
|
||||||
- 所有产品**无购物**: shoppingArrangement = [] 永远
|
|
||||||
- 所有产品**无额外收费**: selfExpenseItems = [] 永远
|
|
||||||
- 付款方式**固定对公转账**: paymentMethod=2, payBankCard=15050161665209911111(从 nacos AgencyInfo.bankCard 注入)
|
|
||||||
- **导游有的产品没有**: tourGuides[] 允许空数组(无导游产品不强制录入)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 新增接口 1: 合同方案附件管理
|
|
||||||
|
|
||||||
### `GET /admin/contract/scheme/{schemeId}/attachments`
|
|
||||||
|
|
||||||
查询合同方案附件列表。
|
|
||||||
|
|
||||||
**Path 参数**:
|
|
||||||
- `schemeId` (Long, 必填) — 合同方案 ID
|
|
||||||
|
|
||||||
**返回示例**:
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"code": 200,
|
|
||||||
"message": "成功",
|
|
||||||
"data": [
|
|
||||||
{
|
|
||||||
"attachmentId": "2049914870366703618",
|
|
||||||
"schemeId": 3,
|
|
||||||
"fileName": "服务标准.pdf",
|
|
||||||
"ossUrl": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/contract/scheme-attachment/2026-05/3_xxxxx.pdf",
|
|
||||||
"ossKey": "contract/scheme-attachment/2026-05/3_xxxxx.pdf",
|
|
||||||
"fileSize": 102400,
|
|
||||||
"fileType": "PDF",
|
|
||||||
"sortOrder": 10,
|
|
||||||
"createTime": "2026-05-01 02:12:45"
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### `POST /admin/contract/scheme/{schemeId}/attachments`
|
|
||||||
|
|
||||||
上传新附件(multipart/form-data)。
|
|
||||||
|
|
||||||
**Path 参数**:
|
|
||||||
- `schemeId` (Long)
|
|
||||||
|
|
||||||
**form-data**:
|
|
||||||
- `file` (MultipartFile, 必填) — 附件文件,支持 PDF/JPG/PNG 等
|
|
||||||
- `fileType` (String, 必填) — 字典 `contract_attachment_type`: `PDF` / `IMAGE` / `OTHER`
|
|
||||||
- `sortOrder` (Integer, 选填,默认 0) — 排序号,越小越前
|
|
||||||
|
|
||||||
**返回**: 与 GET 列表的单项结构相同,含 `attachmentId` / `ossUrl`
|
|
||||||
|
|
||||||
### `PUT /admin/contract/scheme/{schemeId}/attachments/{attachmentId}/sort`
|
|
||||||
|
|
||||||
调整附件排序。
|
|
||||||
|
|
||||||
**Body**:
|
|
||||||
```json
|
|
||||||
{ "sortOrder": 20 }
|
|
||||||
```
|
|
||||||
|
|
||||||
### `DELETE /admin/contract/scheme/{schemeId}/attachments/{attachmentId}`
|
|
||||||
|
|
||||||
删除附件(软删除)。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 新增接口 2: 合同方案导游管理
|
|
||||||
|
|
||||||
### `GET /admin/contract/scheme/{schemeId}/tour-guides`
|
|
||||||
|
|
||||||
查询合同方案导游列表。
|
|
||||||
|
|
||||||
**返回示例**:
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"code": 200,
|
|
||||||
"message": "成功",
|
|
||||||
"data": [
|
|
||||||
{
|
|
||||||
"guideId": "2049915142757388290",
|
|
||||||
"schemeId": 3,
|
|
||||||
"name": "李导",
|
|
||||||
"phone": "13800138000",
|
|
||||||
"licenseNumber": "L-NMG-100953",
|
|
||||||
"sortOrder": 1,
|
|
||||||
"createTime": "2026-05-01 02:13:50"
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### `POST /admin/contract/scheme/{schemeId}/tour-guides`
|
|
||||||
|
|
||||||
新增导游(application/json)。
|
|
||||||
|
|
||||||
**Body**:
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"name": "李导",
|
|
||||||
"phone": "13800138000",
|
|
||||||
"licenseNumber": "L-NMG-100953",
|
|
||||||
"sortOrder": 1
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**字段说明**:
|
|
||||||
- `name` (String, 必填,≤50 字)
|
|
||||||
- `phone` (String, 选填,11 位手机号)
|
|
||||||
- `licenseNumber` (String, 选填,≤64 字,导游证号)
|
|
||||||
- `sortOrder` (Integer, 选填,默认 0)
|
|
||||||
|
|
||||||
### `PUT /admin/contract/scheme/{schemeId}/tour-guides/{guideId}`
|
|
||||||
|
|
||||||
修改导游(同 POST body)。
|
|
||||||
|
|
||||||
### `DELETE /admin/contract/scheme/{schemeId}/tour-guides/{guideId}`
|
|
||||||
|
|
||||||
删除导游(软删除)。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 出行人字段扩展
|
|
||||||
|
|
||||||
### 新增字段 (3 个 SaveReqVO + TravelerVO 都要加)
|
|
||||||
|
|
||||||
| 字段 | 类型 | 是否必填 | 说明 |
|
|
||||||
|------|------|---------|------|
|
|
||||||
| `race` | String | 选填 | 民族(默认\"汉族\"; 12301 race) |
|
|
||||||
| `nationality` | String | 选填 | 国籍(默认\"中国\"; 港澳台/外籍必填) |
|
|
||||||
| `roomGroupNo` | Integer | 选填 | 同住分组号(同号=同房; NULL 系统自动两两配对) |
|
|
||||||
|
|
||||||
### 影响接口
|
|
||||||
|
|
||||||
| 接口 | 变更 |
|
|
||||||
|------|------|
|
|
||||||
| `POST /admin/order/traveler` 创建出行人 | Body 新增 race/nationality/roomGroupNo |
|
|
||||||
| `PUT /admin/order/traveler/{id}` 修改出行人 | Body 新增 race/nationality/roomGroupNo |
|
|
||||||
| `POST /mp/order/traveler` 小程序新增出行人 | Body 新增 race/nationality/roomGroupNo |
|
|
||||||
| `GET /admin/order/traveler/{id}` 查出行人详情 | Resp 新增 race/nationality/roomGroupNo 三个字段 |
|
|
||||||
| `GET /admin/order/traveler/list` 列表 | 同上 |
|
|
||||||
|
|
||||||
### 兜底规则
|
|
||||||
|
|
||||||
- 后端:`race` null → 上报 12301 用 \"汉族\";`nationality` null → \"中国\"。前端可不强制要求,默认值由后端兜底
|
|
||||||
- `roomGroupNo` 为空时,后端按 traveler 列表顺序两两配对(0+1, 2+3, ...);奇数尾巴单人成对(自配自避免空)
|
|
||||||
- 港澳台/护照证件出行人**建议前端引导填写**(身份证可反推国籍/民族,护照不可)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 前端管理后台需要新增的 UI
|
|
||||||
|
|
||||||
### 1. 合同方案管理页 — 附件 Tab
|
|
||||||
|
|
||||||
在合同方案编辑页(`/admin/contract/scheme/edit/{id}`)加一个「附件管理」分块:
|
|
||||||
- 附件列表表格(file_name / file_type / file_size / sort_order / 操作)
|
|
||||||
- 上传按钮(MultipartFile,限 PDF/JPG/PNG,大小 ≤ 10MB)
|
|
||||||
- 排序拖动 / 删除按钮
|
|
||||||
|
|
||||||
附件用途:**长期复用模板**,如旅行社服务标准 PDF / 公司资质照片等。生成合同时自动嵌入 12301 attachments[] 节点。
|
|
||||||
|
|
||||||
### 2. 合同方案管理页 — 导游 Tab
|
|
||||||
|
|
||||||
同方案编辑页加「导游管理」分块:
|
|
||||||
- 导游列表表格(name / phone / license_number / sort_order / 操作)
|
|
||||||
- 新增按钮 → 弹窗表单(姓名 / 手机号 / 导游证号 / 排序)
|
|
||||||
- 修改 / 删除
|
|
||||||
|
|
||||||
业务规则: **没配导游就空,不强制录入**。有导游产品才需要在方案里配。
|
|
||||||
|
|
||||||
### 3. 订单出行人录入页
|
|
||||||
|
|
||||||
`/admin/order/{orderId}/traveler/edit` 表单加 3 个字段:
|
|
||||||
- 民族(下拉,使用字典 `nation` 或文本输入,默认\"汉族\")
|
|
||||||
- 国籍(下拉,默认\"中国\";使用字典 `nationality` 如有)
|
|
||||||
- 同住分组号(数字输入,提示\"同号=同房,空=系统自动两两配对\")
|
|
||||||
|
|
||||||
小程序录入页 `/mp/order/traveler/edit` 同步加。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 自动行程附件(无前端配合)
|
|
||||||
|
|
||||||
**后端自动生成**: 创建合同时,后端自动从订单产品快照渲染一份「行程单.pdf」(用 PDFBox 渲染,中文用 arphic uming TTC),上传 OSS,嵌入 12301 attachments[] 节点的第一项。前端**不需要做任何事**,这块用户看到的是 12301 平台合同 PDF 内已有完整的每日行程内容。
|
|
||||||
|
|
||||||
样本: 测试服 round-trip 生成的 12301 合同 ECDJ260501IYZJR9, 25 页 PDF(含行程单作为附件 1)。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 测试服验证
|
|
||||||
|
|
||||||
| 步骤 | 命令 | 结果 |
|
|
||||||
|------|------|------|
|
|
||||||
| 上传附件 | `POST /admin/contract/scheme/3/attachments` | 200 |
|
|
||||||
| 查附件 | `GET /admin/contract/scheme/3/attachments` | 返回 1 条 |
|
|
||||||
| 加导游 | `POST /admin/contract/scheme/3/tour-guides` | 200 |
|
|
||||||
| 查导游 | `GET /admin/contract/scheme/3/tour-guides` | 返回 1 条 |
|
|
||||||
| 创建合同 | `POST /admin/contract/create-by-scheme` body `{orderId,schemeId}` | 200, 合同号 ECDJ260501IYZJR9 |
|
|
||||||
| 12301 PDF | 25 页, 467 KB | 银行卡/投诉区号/附件1/海拉尔区营业部/汉族 全部呈现 |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 部署状态
|
|
||||||
|
|
||||||
- 测试服 SQL 已应用(2 张新表 + order_traveler 加 race/room_group_no)
|
|
||||||
- 测试服 nacos `hl-order-service-v2-test.yml` (namespace=test) 已推送 6 字段(3 agency × 6)
|
|
||||||
- 测试服 hl-order-service-v2 双实例已重启
|
|
||||||
- 正式环境 nacos 配置补字段 + 部署待运维管理员处理
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 服务重启提示
|
|
||||||
|
|
||||||
合并后只需重启 `hl-order-service-v2`(单服务)。其他服务无影响。
|
|
||||||
@ -0,0 +1,132 @@
|
|||||||
|
# 合同方案管理页 — 新增「附件管理」Tab
|
||||||
|
|
||||||
|
**类型**: 后端新接口
|
||||||
|
**前端处理者**: mmg
|
||||||
|
**日期**: 2026-05-01
|
||||||
|
**关联**: 工单 #1590 / PR #1592 #1594
|
||||||
|
**影响页面**: 管理后台「合同管理 → 合同方案 → 编辑方案」
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 这是什么
|
||||||
|
|
||||||
|
合同方案现在可以挂附件（PDF/图片）。生成 12301 合同时，方案附件会**自动作为合同附件嵌入**到 12301 平台合同 PDF 中。
|
||||||
|
|
||||||
|
**用途举例**：
|
||||||
|
- 旅行社服务标准 PDF
|
||||||
|
- 公司资质照片
|
||||||
|
- 安全告知补充说明
|
||||||
|
- 任何需要随合同长期出现的材料
|
||||||
|
|
||||||
|
**业务规则**：方案上传几个附件，生成合同时就嵌入几个，不需要每个订单单独传。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## UI 需求
|
||||||
|
|
||||||
|
在合同方案编辑页（路由类似 `/admin/contract/scheme/edit/:id`）加一个 **「附件管理」Tab**，里面：
|
||||||
|
|
||||||
|
1. **附件列表表格**：
|
||||||
|
- 列：文件名 / 类型 / 大小 / 排序号 / 创建时间 / 操作
|
||||||
|
- 操作：下载（`ossUrl`）/ 调整排序号 / 删除
|
||||||
|
|
||||||
|
2. **上传按钮**：
|
||||||
|
- 点击 → 弹窗
|
||||||
|
- 表单字段：
|
||||||
|
- 文件（必填，accept=`.pdf,.jpg,.jpeg,.png`，限 10MB）
|
||||||
|
- 文件类型（下拉：PDF / 图片 / 其他）
|
||||||
|
- 排序号（数字，默认 0，越小越前）
|
||||||
|
- 提交 → multipart 上传
|
||||||
|
|
||||||
|
3. **删除二次确认**：删后从列表移除
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 接口
|
||||||
|
|
||||||
|
**Base path**: `/admin/contract/scheme/{schemeId}/attachments`
|
||||||
|
|
||||||
|
### 1. 查询附件列表
|
||||||
|
|
||||||
|
```
|
||||||
|
GET /admin/contract/scheme/{schemeId}/attachments
|
||||||
|
Authorization: Bearer <admin_token>
|
||||||
|
|
||||||
|
→ 200
|
||||||
|
{
|
||||||
|
"code": 200,
|
||||||
|
"data": [
|
||||||
|
{
|
||||||
|
"attachmentId": "2049914870366703618", // String 雪花
|
||||||
|
"schemeId": 3,
|
||||||
|
"fileName": "服务标准.pdf",
|
||||||
|
"ossUrl": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/contract/scheme-attachment/2026-05/3_xxx.pdf",
|
||||||
|
"fileSize": 102400, // 字节数
|
||||||
|
"fileType": "PDF", // PDF / IMAGE / OTHER
|
||||||
|
"sortOrder": 10,
|
||||||
|
"createTime": "2026-05-01 10:12:45"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. 上传新附件（multipart/form-data）
|
||||||
|
|
||||||
|
```
|
||||||
|
POST /admin/contract/scheme/{schemeId}/attachments
|
||||||
|
Authorization: Bearer <admin_token>
|
||||||
|
Content-Type: multipart/form-data
|
||||||
|
|
||||||
|
form-data:
|
||||||
|
file: <File 二进制> (必填, ≤10MB)
|
||||||
|
fileType: "PDF" (必填, 字典 PDF / IMAGE / OTHER)
|
||||||
|
sortOrder: 10 (选填, 默认 0)
|
||||||
|
|
||||||
|
→ 200
|
||||||
|
{
|
||||||
|
"code": 200,
|
||||||
|
"data": { ...同上单条结构, 含新生成 attachmentId 和 ossUrl... }
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. 调整排序
|
||||||
|
|
||||||
|
```
|
||||||
|
PUT /admin/contract/scheme/{schemeId}/attachments/{attachmentId}/sort
|
||||||
|
Content-Type: application/json
|
||||||
|
{ "sortOrder": 20 }
|
||||||
|
|
||||||
|
→ 200 { "code": 200, "data": null }
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. 删除附件（软删除）
|
||||||
|
|
||||||
|
```
|
||||||
|
DELETE /admin/contract/scheme/{schemeId}/attachments/{attachmentId}
|
||||||
|
|
||||||
|
→ 200 { "code": 200, "data": null }
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 字段字典
|
||||||
|
|
||||||
|
`fileType` 字典 `contract_attachment_type`:
|
||||||
|
|
||||||
|
| 字典 value | 显示名 |
|
||||||
|
|-----------|------|
|
||||||
|
| PDF | PDF 文档 |
|
||||||
|
| IMAGE | 图片 |
|
||||||
|
| OTHER | 其他 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 测试服已就绪
|
||||||
|
|
||||||
|
可以现在直接调测试服 (`https://api.test.1814.love:9443`) 的 GET 端点验证（schemeId=3 是测试数据）。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 服务重启
|
||||||
|
|
||||||
|
后端 hl-order-service-v2 已上线，前端开发完直接对接即可。
|
||||||
@ -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 账号登录拿）。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 服务重启
|
||||||
|
|
||||||
|
后端已上线，前端开发完直接对接。
|
||||||
@ -0,0 +1,129 @@
|
|||||||
|
# 出行人录入 — 新增 民族 / 国籍 / 同住分组号 三个字段
|
||||||
|
|
||||||
|
**类型**: 后端字段扩展
|
||||||
|
**前端处理者**: mmg
|
||||||
|
**日期**: 2026-05-01
|
||||||
|
**关联**: 工单 #1590 / PR #1592
|
||||||
|
**影响页面**:
|
||||||
|
- 管理后台「订单详情 → 出行人 → 新增/编辑出行人」
|
||||||
|
- 小程序「订单 → 出行人」录入页
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 这是什么
|
||||||
|
|
||||||
|
出行人 entity 加了 3 个字段，用于 12301 合同上报：
|
||||||
|
|
||||||
|
| 字段 | 类型 | 说明 | 默认值兜底 |
|
||||||
|
|------|------|------|----------|
|
||||||
|
| `race` | String | 民族（中文，如 "汉族" "蒙古族" "回族"） | 后端兜底 "汉族" |
|
||||||
|
| `nationality` | String | 国籍（中文，如 "中国"） | 后端兜底 "中国" |
|
||||||
|
| `roomGroupNo` | Integer | 同住分组号（同号=同房，例如夫妻填同一数字 1，独立间填 NULL 或唯一数字） | 系统自动两两配对 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## UI 需求
|
||||||
|
|
||||||
|
### 出行人录入弹窗 / 表单
|
||||||
|
|
||||||
|
加三个字段（建议放在「证件号 / 手机号 / 紧急联系人」附近）：
|
||||||
|
|
||||||
|
1. **民族**（选填）
|
||||||
|
- 推荐用 **下拉框**，但项目暂没"民族"字典
|
||||||
|
- **简化方案**：用文本输入框 + placeholder "默认汉族, 港澳台/护照证件请填实际民族"
|
||||||
|
- 后端会用 EncryptTypeHandler 加密存储不？**不加密**(当前 entity 直接 String race)
|
||||||
|
- 长度限制 20 字符
|
||||||
|
|
||||||
|
2. **国籍**（选填）
|
||||||
|
- 文本输入 + placeholder "默认中国, 港澳台/护照证件必填"
|
||||||
|
- 长度限制 50 字符（实际更短）
|
||||||
|
|
||||||
|
3. **同住分组号**（选填）
|
||||||
|
- 数字输入 + placeholder "同号=同房, 留空系统自动两两配对"
|
||||||
|
- 提示文案：
|
||||||
|
> 例如夫妻同房：两人都填 1
|
||||||
|
> 朋友合住：两人都填 2
|
||||||
|
> 单人房：填唯一数字（如 99）
|
||||||
|
> 留空：系统按列表顺序自动两两配对（0+1, 2+3...）
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 接口（增量字段）
|
||||||
|
|
||||||
|
### 1. 管理端新增出行人
|
||||||
|
|
||||||
|
```
|
||||||
|
POST /admin/order/{orderId}/traveler
|
||||||
|
Content-Type: application/json
|
||||||
|
|
||||||
|
{
|
||||||
|
"name": "张三",
|
||||||
|
"idCardType": "ID_CARD",
|
||||||
|
"idCardNo": "152104199802205216",
|
||||||
|
"phone": "13800138000",
|
||||||
|
...
|
||||||
|
|
||||||
|
// 🆕 新增 3 字段(全部选填):
|
||||||
|
"race": "蒙古族",
|
||||||
|
"nationality": "中国",
|
||||||
|
"roomGroupNo": 1
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. 管理端修改出行人
|
||||||
|
|
||||||
|
```
|
||||||
|
PUT /admin/order/traveler/{travelerId}
|
||||||
|
Content-Type: application/json
|
||||||
|
|
||||||
|
{ ...含同样 3 字段 }
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. 小程序端
|
||||||
|
|
||||||
|
`POST /mp/order/traveler` body 里也加这 3 字段（逻辑一致）。
|
||||||
|
|
||||||
|
### 4. 查询出行人详情/列表
|
||||||
|
|
||||||
|
```
|
||||||
|
GET /admin/order/traveler/{travelerId}
|
||||||
|
GET /admin/order/{orderId}/travelers
|
||||||
|
|
||||||
|
→ 200
|
||||||
|
{
|
||||||
|
"code": 200,
|
||||||
|
"data": {
|
||||||
|
...原有字段...
|
||||||
|
"race": "汉族", // 🆕
|
||||||
|
"nationality": "中国", // 🆕
|
||||||
|
"roomGroupNo": 1 // 🆕 (Integer 或 null)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 哪种证件类型必填？
|
||||||
|
|
||||||
|
业务规则：
|
||||||
|
|
||||||
|
| 证件类型 | race / nationality 重要性 |
|
||||||
|
|---------|-------------------------|
|
||||||
|
| 身份证（ID_CARD） | 系统可由身份证号反推民族/国籍，**前端可不填**，后端兜底 |
|
||||||
|
| 港澳通行证 | **建议填**，身份证算法不适用 |
|
||||||
|
| 护照（PASSPORT） | **建议填**，外籍/海外华人必填正确国籍 |
|
||||||
|
| 台湾通行证 | 同港澳通行证 |
|
||||||
|
|
||||||
|
可在表单上加提示文案引导。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 测试服已就绪
|
||||||
|
|
||||||
|
后端字段已上线，前端调用接口加这 3 个字段即可。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 服务重启
|
||||||
|
|
||||||
|
后端 hl-order-service-v2 已上线。`order_traveler` 表已 ALTER 加 race + room_group_no 列（nationality 之前已有）。
|
||||||
正在加载...
x
在新工单中引用
屏蔽一个用户