更新第四种复杂的rooming list

2026-08-20 11:39:20 +08:00
1 parent e23131f4d0
commit 3bce336b6c
@@ -2,9 +2,9 @@

 | 项目 | 内容 |
 | --- | --- |
-| 文档状态 | 后端 CP1 已实现；CP2 已实现旅游日期派生、Adults 系统计算和目标默认值字段收口；CP3 第二种来源名单样式已实现；CP4 第三种单列 `英文名` 来源名单样式已实现 |
+| 文档状态 | 后端 CP1 已实现；CP2 已实现旅游日期派生、Adults 系统计算和目标默认值字段收口；CP3 第二种来源名单样式已实现；CP4 第三种单列 `英文名` 来源名单样式已实现；CP5 第四种 `拼音` + `分房` 原表分房样式已实现 |
 | 适用范围 | 从旅行团名单 Excel 解析护照姓名，并生成酒店 / PMS 可导入的 Rooming List Excel |
-| 当前目标 | CP1 已支持前端上传来源 Excel、填写分房和目标列默认值，后端同步生成目标格式 `.xlsx`；CP2 收口为后端从来源 `旅游日期` 派生入住 / 离店日期，成人数由系统按分房结果计算，目标默认值区域只保留付款方式和国籍；CP3 兼容 `英文姓` + `英文名` 第二种名单样式；CP4 兼容单列 `英文名` 第三种名单样式；无旅游日期来源样式均由用户补充入住 / 离店日期 |
+| 当前目标 | CP1 已支持前端上传来源 Excel、填写分房和目标列默认值，后端同步生成目标格式 `.xlsx`；CP2 收口为后端从来源 `旅游日期` 派生入住 / 离店日期，成人数由系统按分房结果计算，目标默认值区域只保留付款方式和国籍；CP3 兼容 `英文姓` + `英文名` 第二种名单样式；CP4 兼容单列 `英文名` 第三种名单样式；CP5 兼容 `拼音` + `分房` 第四种名单样式并尊重原表分房；无旅游日期来源样式均由用户补充入住 / 离店日期 |
 | 依赖能力 | 登录权限、酒店上下文、Apache POI 或等价 Excel 读写能力 |

 ## 1. 背景
@@ -53,6 +53,17 @@ CP4 目标调整：
 - 第三种样式中的 `领队` 行也进入房表。例如 `19+1` 应理解为 19 位客人 + 1 位领队，合计 20 位入住人全部参与分房。
 - 来源表中的中文名、性别、证件号、生日、出生地、签发地、联系方式、小费、住宿说明等字段第一版仍不写入目标 Excel，也不在错误响应或日志中回显。

+CP5 目标调整：
+
+- 兼容第四种来源名单样式：表头包含 `拼音`、`分房`，可选包含 `儿童情况`。
+- 第四种样式的 `拼音` 单元格值形如 `ZHANG JIANWEI`，后端复用空格拆分规则，第一段写入目标 `Name`，剩余部分写入目标 `First Name`。
+- 第四种样式必须尊重来源表已经标注的分房结果：`用房1间` 表示开始一间新房，后续 `分房` 为空的名单行归入当前房间，直到下一次 `用房1间` 或 `外住`。
+- `分房=外住` 的行不进入目标 Rooming List；如果当前房间已开始，遇到 `外住` 前会先结束当前房间。
+- `儿童情况=不占床` 的旅客仍进入当前房间的 `Accompanying Guests`，但不计入目标 `Adults`；`儿童情况=占床` 或空白按占床人员计入 `Adults`。
+- 第四种样式没有可靠入住 / 离店日期来源，后端不得从标题、团号或航班日期猜测酒店入住 / 离店日期；必须使用前端提交的 `arrival` / `departure`。
+- 第四种样式下 `people_per_room` 仍因当前接口兼容保持必填，但实际生成时忽略该字段，目标房间行完全以后端读取到的来源原表分房为准。
+- 来源表中的中文名、性别、出生日期、出生地、护照、签发地、签发日期、有效期、联系方式、备注等字段第一版仍不写入目标 Excel，也不在错误响应或日志中回显。
+
 第一阶段不做：

 - 不落业务订单。
@@ -78,7 +89,7 @@ CP4 目标调整：

 ## 4. 来源 Excel 解析规则

-基于当前样例来源文件，当前支持三类来源名单格式。后端应先在来源 Excel 中识别表头组合，再选择对应解析器。
+基于当前样例来源文件，当前支持四类来源名单格式。后端应先在来源 Excel 中识别表头组合，再选择对应解析器。

 ### 4.1 第一种来源样式：护照全名 + 旅游日期

@@ -199,6 +210,36 @@ Sheet1 第 4 行起：名单数据
 - 不读取也不返回中文名、性别、证件号、生日、出生地、签发地、联系方式、小费、住宿说明。
 - 第三种样式没有 `旅游日期`，后端不得从航班行猜测入住 / 离店日期；必须使用前端提交的 `arrival` / `departure`。

+### 4.4 第四种来源样式：拼音 + 分房
+
+第四种样式识别以下表头：
+
+| 来源字段 | 中文说明 | 第一版用途 |
+| --- | --- | --- |
+| `拼音` | 护照英文姓名，通常为空格分隔 | 拆分后写入目标 Excel 的 `Name` 和 `First Name` |
+| `分房` | 来源表人工分房标记，例如 `用房1间`、`外住` | 用于生成目标 Excel 的房间行，不再按 `people_per_room` 自动切房 |
+| `儿童情况` | 儿童占床说明，例如 `不占床` | `不占床` 不计入 `Adults`，但仍进入 `Accompanying Guests` |
+
+已确认样例：
+
+```text
+Sheet1：团队名单表
+表头：序号 / 姓名 / 拼音 / 性别 / 出生日期 / 出生地 / 护照 / 签发地 / 签发日期 / 有效期 / 联系方式 / 儿童情况 / 分房 / 备注
+名单行：1L 领队可标记 `外住`；客人行通过 `用房1间` 和空白 `分房` 表示同房关系。
+```
+
+解析规则：
+
+- 在前若干行内查找同一行同时包含 `拼音` 和 `分房` 的表头；`儿童情况` 可选。
+- 从表头下一行开始读取名单行。
+- `拼音` 为空的行跳过。
+- `分房` 包含 `外住` 的行不进入目标 Rooming List。
+- `分房` 包含 `用房` 的行开始一间新房；后续 `分房` 为空的有效姓名行归入当前房间。
+- 如果在第一个 `用房` 标记前出现普通名单行，第一版跳过，避免把未分房人员误归入目标房间。
+- 每间房第一位旅客写入目标 `Name` / `First Name`；同房其他旅客写入 `Accompanying Guests`。
+- `儿童情况=不占床` 的旅客仍保留在 `Accompanying Guests`，但不计入 `Adults`；`Children` 第一版仍固定为 `0`。
+- 第四种样式没有 `旅游日期`，后端不得从标题、团号或航班行猜测入住 / 离店日期；必须使用前端提交的 `arrival` / `departure`。
+
 ## 5. 分房生成规则

 前端需要传入 `people_per_room`，表示每间房人数。
@@ -206,6 +247,7 @@ Sheet1 第 4 行起：名单数据
 规则：

 - 按来源 Excel 中旅客出现顺序分组。
+- 第四种 `拼音` + `分房` 来源样式例外：后端尊重来源表原始分房，忽略 `people_per_room` 的分组作用。
 - `room_count = ceil(total_people / people_per_room)`。
 - 每组第一位旅客写入目标 Excel 的 `Name` 和 `First Name`。
 - 同组剩余旅客写入目标 Excel 的 `Accompanying Guests`。
@@ -325,7 +367,7 @@ Content-Disposition: attachment; filename="rooming-list-<timestamp>.xlsx"
 - `payment_type` 非 `BTQR` / `CA`，返回 `ROOMING_LIST_VALIDATION_FAILED`。
 - `nationality` 非 `KR` / `CN` / `TH` / `MM` / `RS` / `TW`，返回 `ROOMING_LIST_VALIDATION_FAILED`。
 - 无旅游日期来源样式缺少 `arrival` / `departure`、日期格式错误或 `departure` 不晚于 `arrival`，返回 `ROOMING_LIST_VALIDATION_FAILED`。
- 来源文件缺失、非 `.xls` / `.xlsx`、无法读取、既不能识别第一种 `护照全名` + `旅游日期`，也不能识别第二种 `英文姓` + `英文名` 或第三种单列 `英文名`，返回 `ROOMING_LIST_SOURCE_FILE_INVALID`。
+- 来源文件缺失、非 `.xls` / `.xlsx`、无法读取、既不能识别第一种 `护照全名` + `旅游日期`，也不能识别第二种 `英文姓` + `英文名`、第三种单列 `英文名` 或第四种 `拼音` + `分房`，返回 `ROOMING_LIST_SOURCE_FILE_INVALID`。
 - 第一种来源样式缺少 / 无法解析 `旅游日期` 表头，返回 `ROOMING_LIST_SOURCE_FILE_INVALID`。
 - 同一来源文件出现多个不同旅游日期区间，CP2 返回受控错误，不生成 Excel。
 - 错误详情只返回字段名或行号，不回显完整名单、证件号或源文件内容。
@@ -359,7 +401,7 @@ RESERVATION_ROOMING_LIST_GENERATE
 | `ReservationRoomingListGenerationController` | 接收前端上传请求，做登录、权限和酒店上下文校验 |
 | `ReservationRoomingListGenerationService` | 编排来源解析、分房、目标 Excel 渲染和文件响应 |
 | `ReservationRoomingListGenerationServiceImpl` | 具体业务实现 |
-| `RoomingListSourceExcelParser` | CP1 解析来源 Excel，提取护照姓名；CP2 已扩展为同时提取并校验统一旅游日期区间；CP3 已扩展第二种 `英文姓` + `英文名` 样式；CP4 已扩展第三种单列 `英文名` 样式；无旅游日期来源样式要求用户补日期 |
+| `RoomingListSourceExcelParser` | CP1 解析来源 Excel，提取护照姓名；CP2 已扩展为同时提取并校验统一旅游日期区间；CP3 已扩展第二种 `英文姓` + `英文名` 样式；CP4 已扩展第三种单列 `英文名` 样式；CP5 已扩展第四种 `拼音` + `分房` 原表分房样式；无旅游日期来源样式要求用户补日期 |
 | `RoomingListNameParser` | 拆分 `/` 或空格格式的护照姓名 |
 | `RoomingListGroupingService` | 按每房人数分组并生成目标行模型 |
 | `RoomingListExcelRenderer` | 生成目标格式 `.xlsx` |
@@ -419,6 +461,11 @@ RESERVATION_ROOMING_LIST_GENERATE
 - 能识别第三种来源样式单列 `英文名` 表头。
 - 第三种来源样式下 `英文名=CAI/HAIYUN` 能生成 `Name=CAI`、`First Name=HAIYUN`。
 - 第三种来源样式下领队也进入房表，实际人数以后端读取到的有效名单行数为准。
+- 能识别第四种来源样式 `拼音` / `分房` 表头。
+- 第四种来源样式下 `拼音=ZHANG JIANWEI` 能生成 `Name=ZHANG`、`First Name=JIANWEI`。
+- 第四种来源样式尊重原表 `用房1间` 分房，不按 `people_per_room` 重新切房。
+- 第四种来源样式下 `分房=外住` 行不进入目标 Rooming List。
+- 第四种来源样式下 `儿童情况=不占床` 的旅客进入 `Accompanying Guests`，但不计入 `Adults`。
 - 无旅游日期来源样式使用前端提交的 `arrival` / `departure` 写入目标 Excel。
 - 无旅游日期来源样式缺少 `arrival` / `departure` 返回受控错误。
 - `LI/CHUNHONG` 能拆成 `Name=LI`、`First Name=CHUNHONG`。