实现房表生成第二种名单样式

docs/project/frontend-backend/frontend-to-backend-api-requests.md

@@ -17,7 +17,7 @@
 | P0 | 邮件会话详情接口 `GET /api/source-messages/{sourceMessageId}/conversation` | 邮件会话详情页 | 已完成第一版 |
 | 联调 | 演示数据 seed 接口 `POST /api/system/reservation/demo-data` | 本地 / test 前端页面看效果 | 已完成；仅 dev/test 受控使用 |
 | 联调 | Debug EML 上传接口 `POST /api/system/debug/eml-superagent-runs` | Debug 页面上传 `.eml` 看 SuperAgent 结果 | 已完成第一版；仅 dev/test 受控使用 |
-| Done | Rooming List Excel 生成接口 `POST /api/reservation/rooming-lists/generations` | 房表生成页面 | CP1 已完成；CP2 已实现旅游日期派生、Adults 自动计算和目标默认值字段收口 |
+| Done | Rooming List Excel 生成接口 `POST /api/reservation/rooming-lists/generations` | 房表生成页面 | CP1 已完成；CP2 已实现旅游日期派生、Adults 自动计算和目标默认值字段收口；CP3 已实现第二种 `英文姓` + `英文名` 名单样式和用户补 Arrival / Departure |
 | P1 | S10/S99 源邮件只读通知卡与旧 S000/S999 兼容 | 任务列表、任务详情来源邮件查看 | 已完成第一版：旧 S000/S999 兼容，新结构化 S10/S99 可入站并在任务列表 / 详情只读展示 |
 | P1 | type-known manual review 同卡复核解阻 | 任务详情复核 | 已完成第一版：原业务任务卡复核、字段修正、订单归属确认、READY 流转 |
 | P1 | 任务卡前端字段白名单元数据接口 | 字段白名单调试、版本对齐 | 未完成；若任务详情已透出完整元数据，可后置 |
@@ -1184,9 +1184,9 @@ POST /api/reservation/invoices/manual-generations
 - 第一版已写入 `workflow_reservation_invoice_generation` 生成记录和业务审计，但暂不提供前端查询历史列表 / 详情接口。
 - 错误响应中的 `error_code` 用于前端主错误文案映射；`message` / `details[]` 只作为折叠技术详情展示，不直接铺给普通用户。
 
-## 13. Rooming List Excel 生成接口 CP2 契约
+## 13. Rooming List Excel 生成接口 CP2 / CP3 契约
 
-M010 Rooming List Excel 生成接口 CP1 已实现，前端 V1 已接入 `/reservation/rooming-lists/new`。CP2 不新增路径，继续收口同一个正式业务接口。
+M010 Rooming List Excel 生成接口 CP1 已实现，前端 V1 已接入 `/reservation/rooming-lists/new`。CP2 不新增路径，继续收口同一个正式业务接口。CP3 已实现兼容第二种来源名单样式，仍复用本接口。
 
 路径：
 
@@ -1202,14 +1202,14 @@ CP2 前端提交字段：
 | `hotel_id` | 否 | 当前选择酒店；不传时由后端按登录用户酒店上下文解析。 |
 | `people_per_room` | 是 | 每间房人数，正整数。 |
 | `room_type` | 是 | 目标 Excel 的 Room Type。 |
+| `arrival` | 条件必填 | CP3 第二种来源名单样式必填，格式 `yyyy-MM-dd`；第一种 `旅游日期` 样式可不填。 |
+| `departure` | 条件必填 | CP3 第二种来源名单样式必填，格式 `yyyy-MM-dd`；必须晚于 `arrival`。 |
 | `payment_type` | 否 | 目标 Excel 的 Payment Type；默认 `BTQR`，当前允许 `BTQR`、`CA`。 |
 | `nationality` | 是 | 目标 Excel 的 Nationality；只允许 `KR`、`CHN`。 |
 
-CP2 前端不再提交：
+CP3 前端仍不提交：
 
 ```text
-arrival
-departure
 title
 rate_code
 adults
@@ -1222,19 +1222,25 @@ id_number
 
 后端派生规则：
 
-- 从来源 Excel `旅游日期` 列解析入住和离店日期；样例 `2026年5月9日－5月14日` 派生 `Arrival=2026/05/09`、`Departure=2026/05/14`。
+- 第一种来源样式：从来源 Excel `旅游日期` 列解析入住和离店日期；样例 `2026年5月9日－5月14日` 派生 `Arrival=2026/05/09`、`Departure=2026/05/14`。
+- 第二种来源样式：来源 Excel 表头包含 `英文姓`、`英文名`，没有可靠入住 / 离店日期；后端使用前端提交的 `arrival` / `departure` 写入目标 Excel。
+- 第二种来源样式姓名生成规则：`Name=英文姓`，`First Name=英文名`，不再拆分字符串。
+- 第二种来源样式中领队也进入房表；例如 `23+1` 表示 23 位客人 + 1 位领队全部参与分房，实际人数以后端读取到的有效名单行数为准。
 - `Adults` 按当前分房行实际人数计算；尾房人数不足时按实际人数写入。
 - `Children` 固定为 `0`。
 - `Title`、`Rate Code`、`VIP`、`Email`、`ID Type`、`ID Number` 第一版固定为空。
-- 如果来源 Excel 缺少 `旅游日期`、日期格式无法解析、结束日期不晚于起始日期，或同一文件出现多个不同旅游日期区间，后端返回受控错误，不生成 Excel。
+- 如果来源 Excel 既不能识别第一种 `护照全名` + `旅游日期`，也不能识别第二种 `英文姓` + `英文名`，后端返回受控错误，不生成 Excel。
+- 第一种来源样式缺少 `旅游日期`、日期格式无法解析、结束日期不晚于起始日期，或同一文件出现多个不同旅游日期区间，后端返回受控错误，不生成 Excel。
+- 第二种来源样式缺少 `arrival` / `departure`、日期格式无法解析，或 `departure` 不晚于 `arrival`，后端返回受控错误，不生成 Excel。
 
 前端诉求：
 
-- 页面第一部分保留上传来源 Excel、每房人数、Room Type。
+- 页面第一部分保留上传来源 Excel、每房人数、Room Type，并恢复 `Arrival` / `Departure` 日期输入。
+- `Arrival` / `Departure` 在第一种来源样式下可不填；当用户上传第二种没有 `旅游日期` 的名单时必须填写。页面文案建议说明“来源名单没有旅游日期时请填写入住 / 离店日期”。
 - 目标默认值区域只保留 Payment Type 和 Nationality 两个下拉。
 - Payment Type 默认选中 `BTQR`，当前提供 `BTQR`、`CA` 两个选项。
 - Nationality 只提供 `KR` 和 `CHN`。
-- 前端不读取完整 Excel 作为权威解析结果；旅游日期和成人数以后端生成结果为准。
+- 前端不读取完整 Excel 作为权威解析结果；来源样式识别、旅客名单和成人数以后端生成结果为准。
 - 页面不要把上传文件内容、客人名单、生成文件内容写入浏览器日志、埋点、错误上报、URL 或 localStorage。
 
 ## 14. 已确认后置接口