实现Rooming List Excel生成接口

2026-07-18 11:36:16 +07:00
parent 75d860129c
commit d3a52e7605
25 changed files with 1709 additions and 3 deletions
--- a/docs/project/README.md
+++ b/docs/project/README.md
@@ -56,6 +56,7 @@
 | `requirements/M007-agentbus-superagent-auto-dispatch-v1.md` | 当前有效 | M007 AgentBus 新邮件入库后异步分发 SuperAgent 的后端 V1 方案，当前默认关闭，等待测试机联调。 |
 | `requirements/M008-excel-to-pdf-conversion-v1.md` | 当前有效 | M008 Excel 转 PDF 文件转换能力方案，记录 LibreOffice headless、手动上传转换、邮件附件自动派生 PDF 和部署要求；CP2 已实现手动上传后端接口。 |
 | `requirements/M009-manual-invoice-generation-v1.md` | 当前有效 | M009 Manual Invoice 手工开票生成方案；后端 CP2 已支持无订单 / 无任务手工填写、填充 Excel 模板、转 PDF、OSS 输出和生成记录。 |
+| `requirements/M010-rooming-list-excel-generation-v1.md` | 当前有效 | M010 Rooming List Excel 生成方案；后端 CP1 已支持前端上传来源名单和手工字段，同步生成 `.xlsx` 直接下载，不落库、不上传 OSS。 |

 ## 集成契约

--- a/docs/project/frontend-backend/README.md
+++ b/docs/project/frontend-backend/README.md
@@ -46,6 +46,7 @@
 | 订单任务主流程 V3 | `docs/project/requirements/M002-order-task-workflow-v3.md` | 当前开发基线，基于 0711 P0 冻结基线和 0712 P0.1 Parent Group 修订，覆盖 S10/S99、40 路由、方案 C、type-known manual review 同卡解阻和 fail-closed。 |
 | 任务卡字段控件契约 V1 | `docs/project/requirements/M002-task-field-control-contract-v1.md` | 后端已返回 `fields[]` 控件元数据，规定人工复核控件复用和前后端边界；前端待接入。 |
 | Manual Invoice 手工开票生成 | `docs/project/requirements/M009-manual-invoice-generation-v1.md` | 当前有效；后端 CP2 已支持无订单 / 无任务手工填写字段、填 Excel 模板、转 PDF、OSS 输出和生成记录。 |
+| Rooming List Excel 生成 | `docs/project/requirements/M010-rooming-list-excel-generation-v1.md` | 当前有效；后端 CP1 已支持前端上传来源名单并填写目标字段，同步生成 `.xlsx` 直接下载，不落库、不上传 OSS。 |
 | 订单任务主流程 V2 | `docs/project/requirements/M002-order-task-workflow-v2.md` | 已实现阶段记录，保留用于理解当前代码中的 S000/S999、订单任务流转和 OPERA 模拟骨架。 |
 | 后端 checkpoint | `docs/project/requirements/M002-backend-checkpoint-plan.md` | 阶段记录，用于理解后端拆分和验收。 |
 | 前端可用接口与待补接口 | `docs/project/frontend-backend/frontend-to-backend-api-requests.md` | 前后端协作清单，已区分可用、后置和历史候选路径，不替代后端权威契约。 |
@@ -61,6 +62,7 @@
 - 真实 OPERA / OHIP 接入后置；当前仅有 OPERA 模拟骨架。
 - 任务卡字段控件契约 V1 后端第一版已完成，任务详情 `fields[]` 已返回 `control_type/edit_scope/write_target/options_source/raw_readonly/control_hint`；前端后续按契约接入，不要硬编码 PMS 房型、Rate Code 或未冻结枚举。
 - Manual Invoice 第一阶段按 M009 推进：后端已提供 `POST /api/reservation/invoices/manual-generations`，前端已新增 `/reservation/invoices/new` 手工开票页面，并已按 `invoice.html` 原型的三段式业务结构对齐；页面可以不依赖订单或任务，用户手工填写 / 选择字段后由后端业务接口填充 Excel 模板并生成 PDF；前端不得直接调用 M008 的调试上传转换接口来完成业务开票。侧边栏入口仍以登录后端返回的 menus 为准，建议后续在菜单管理中配置 `RESERVATION_MANUAL_INVOICE` / `/reservation/invoices/new` / `RESERVATION_INVOICE_GENERATE`。
+- Rooming List Excel 后端 CP1 已按 M010 落地：接口为 `POST /api/reservation/rooming-lists/generations`，前端上传来源名单、填写每房人数和目标列字段，后端同步返回 `.xlsx` 下载；该能力不依赖订单或任务，第一版不落库、不上传 OSS，权限码为 `RESERVATION_ROOMING_LIST_GENERATE`。

 ## 6. 前端开发注意事项

--- a/docs/project/frontend-backend/backend-to-frontend-notes.md
+++ b/docs/project/frontend-backend/backend-to-frontend-notes.md
@@ -74,6 +74,7 @@
 | `GET/POST/PUT /api/admin/menus...` | 系统管理菜单维护 | 需要 `SYSTEM_MENU_MANAGE`；允许保存未知路由，前端必须有未知路由兜底页；已提供完整菜单树查询和批量树排序保存。 |
 | `GET/POST/PUT /api/admin/hotels...` | 系统管理酒店维护 | 需要 `HOTEL_MANAGE`；新增酒店默认 `DISABLED`，单酒店阶段不能启用第二家 `ACTIVE`。 |
 | `GET /api/admin/audits` | 系统管理操作审计 | 需要 `SYSTEM_ADMIN_CONSOLE_ACCESS`；用于查看管理后台写操作审计，不包含密码、token、secret。 |
+| `POST /api/reservation/rooming-lists/generations` | 生成 Rooming List Excel | 必须带 Bearer token，需要 `RESERVATION_ROOMING_LIST_GENERATE`；请求为 multipart/form-data，成功后直接返回 `.xlsx` 文件流，前端按 Blob 下载处理。 |

 ### 5.1 本轮新增 / 修改接口说明

@@ -405,6 +406,38 @@ M009 后端 CP2 已实现：页面可不依赖订单或任务，用户手工填
 - 第一版暂未提供 Invoice 历史列表、详情查询、任务 / 订单预填接口和客户联系人目录查询接口；前端客户 / 联系人候选可先按 M009 文档中的种子数据实现。
 - 前端不得直接调用 `POST /api/system/document-conversions/excel-to-pdf` 来完成业务开票；该接口是 M008 调试 / 后台工具能力，受 access key 控制，不具备业务开票审计和权限边界。

+### 5.12 Rooming List Excel 生成页面接入方向
+
+M010 后端 CP1 已实现。第一版生成结果直接下载 `.xlsx`，不落库、不上传 OSS，不依赖订单或任务。
+
+接口：
+
+```text
+POST /api/reservation/rooming-lists/generations
+Authorization: Bearer <access_token>
+Content-Type: multipart/form-data
+```
+
+权限：
+
+```text
+RESERVATION_ROOMING_LIST_GENERATE
+```
+
+前端注意：
+
+- 第一版页面建议作为 Reservation 运营工具入口，例如 `/reservation/rooming-lists/new`。
+- 该页面上传来源名单 Excel，后端默认识别 `护照全名` 列。
+- 姓名支持 `LI/CHUNHONG` 和 `LI CHUNHONG` 两类格式；后端会把第一段写入目标 `Name`，剩余部分写入目标 `First Name`。
+- 前端必须让用户输入 `people_per_room`，后端按名单顺序分组，并用 `ceil(total_people / people_per_room)` 生成房间行。
+- 每组第一位旅客写入 `Name` / `First Name`，同组剩余旅客写入 `Accompanying Guests`，多人用英文逗号分隔。
+- 除 `Line`、`Name`、`First Name`、`Number of Rooms`、`Accompanying Guests` 外，目标 Excel 其他字段第一版都由前端输入或选择，例如 `Arrival`、`Departure`、`Room Type`、`Rate Code`、`Payment Type`、`Nationality`。
+- 第一版接口成功后直接返回 Excel 文件流，前端应按 Blob 下载处理，不要期待 JSON 里的 URL。
+- 失败时返回统一 JSON 错误，例如 `ROOMING_LIST_VALIDATION_FAILED`、`ROOMING_LIST_SOURCE_FILE_INVALID`、`HOTEL_ACCESS_DENIED` 或 `FRONTEND_PERMISSION_DENIED`。
+- `ROOMING_LIST_VALIDATION_FAILED` 已覆盖 multipart 必填字段缺失、日期格式错误和数字格式错误，`details[]` 会返回字段级提示。
+- 页面不要把上传文件内容、客人名单、生成文件内容写入浏览器日志、埋点、错误上报、URL 或 localStorage。
+- 第一版没有 preview 接口、生成记录接口、OSS URL、历史下载和订单 / 任务预填；前端不要在页面上承诺这些能力。
+
 ## 6. 不给前端直接调用的接口

 - `POST /api/system/reservation/demo-data` 只用于 dev/test 联调造数，不是生产业务页面接口；访问口令不能进入前端代码。
--- a/docs/project/requirements/M010-rooming-list-excel-generation-v1.md
+++ b/docs/project/requirements/M010-rooming-list-excel-generation-v1.md
@@ -0,0 +1,293 @@
+# M010 Rooming List Excel 生成 V1
+
+| 项目 | 内容 |
+| --- | --- |
+| 文档状态 | 后端 CP1 已实现，第一版直接下载 `.xlsx`，不落库、不上传 OSS |
+| 适用范围 | 从旅行团名单 Excel 解析护照姓名，并生成酒店 / PMS 可导入的 Rooming List Excel |
+| 当前目标 | 第一阶段已支持前端上传来源 Excel、填写分房和目标列默认值，后端同步生成目标格式 `.xlsx` 供浏览器下载 |
+| 依赖能力 | 登录权限、酒店上下文、Apache POI 或等价 Excel 读写能力 |
+
+## 1. 背景
+
+当前系统已经支持 Manual Invoice 生成，但运营中还存在另一类独立工具诉求：旅行社或渠道提供一份名单 Excel，里面包含旅客护照姓名，酒店侧需要整理成 PMS / 导入模板要求的 Rooming List Excel。
+
+本功能第一版只解决“来源名单到目标 Rooming List”的结构转换和分房填表问题，不依赖订单、任务、SuperAgent、AgentBus 或 OPERA。
+
+## 2. 第一阶段定位
+
+第一阶段应做到：
+
+- 前端上传 `.xls` / `.xlsx` 来源名单。
+- 后端解析来源名单中的护照姓名字段。
+- 前端输入每间房人数。
+- 前端填写或选择目标 Excel 中除姓名外的字段。
+- 后端按来源名单顺序分组，生成目标格式 Excel。
+- 浏览器直接下载生成后的 `.xlsx` 文件。
+
+第一阶段不做：
+
+- 不落业务订单。
+- 不创建任务。
+- 不上传 OSS。
+- 不新增生成记录表。
+- 不做历史查询和重下载。
+- 不接真实 OPERA / OHIP。
+- 不做复杂房型混住、拖拽换房或手工调整入住人顺序。
+- 不从任务详情或订单详情自动预填字段。
+
+## 3. 与现有模块关系
+
+本功能属于 Reservation 运营工具，不属于 M008 通用文件转换，也不属于 M009 Manual Invoice。
+
+边界说明：
+
+- M008 负责 Excel 转 PDF，面向平台文件转换和调试能力。
+- M009 负责 Proforma Invoice 生成，输出 PDF 并上传 OSS。
+- M010 负责 Rooming List Excel 生成，第一版只输出 `.xlsx` 文件流。
+
+因此第一版建议在 Reservation 模块内新增独立接口、权限码和服务，不复用发票生成权限，也不让前端调用 M008 调试接口。
+
+## 4. 来源 Excel 解析规则
+
+基于当前样例来源文件，第一版默认识别以下表头：
+
+| 来源字段 | 中文说明 | 第一版用途 |
+| --- | --- | --- |
+| `护照全名` | 护照姓名，可能包含 `/` 或空格 | 解析为目标 Excel 的 `Name` 和 `First Name` |
+
+第一版只使用 `护照全名` 生成目标姓名字段。来源文件中的证件号、生日、性别、年龄等字段暂不自动写入目标 Excel，除非后续单独确认。
+
+### 4.1 姓名拆分
+
+支持的输入格式：
+
+```text
+LI/CHUNHONG
+LI CHUNHONG
+LIU/JIAYI
+```
+
+规则：
+
+- 先 trim 首尾空格。
+- 优先按 `/` 拆分。
+- 如果没有 `/`，按连续空白拆分。
+- 第一段写入目标 `Name`。
+- 剩余部分合并后写入目标 `First Name`。
+- 如果无法拆出两段，返回明确校验错误，由前端提示用户修正来源 Excel 或后续增加字段映射。
+
+中文说明：
+
+- 当前目标模板中 `Name` 更接近姓氏字段，`First Name` 更接近名字段。
+- 第一版不尝试判断中文、韩文、英文姓名顺序，也不做大小写改写。
+
+## 5. 分房生成规则
+
+前端需要传入 `people_per_room`，表示每间房人数。
+
+规则：
+
+- 按来源 Excel 中旅客出现顺序分组。
+- `room_count = ceil(total_people / people_per_room)`。
+- 每组第一位旅客写入目标 Excel 的 `Name` 和 `First Name`。
+- 同组剩余旅客写入目标 Excel 的 `Accompanying Guests`。
+- 多个陪同人使用英文逗号 `,` 分隔。
+- 最后一组人数不足 `people_per_room` 时，仍按一间房生成一行。
+
+示例：
+
+```text
+people_per_room = 3
+
+第 1 组：
+  Name = LI
+  First Name = CHUNHONG
+  Accompanying Guests = ZHANG GAILI, LI HONG
+
+第 2 组：
+  Name = LIU
+  First Name = JIAYI
+  Accompanying Guests = ZHU XINGTONG, CHEN YUCHAI
+```
+
+## 6. 目标 Excel 字段
+
+目标 Excel 第一版按当前样例模板生成以下列：
+
+| 目标列 | 第一版来源 |
+| --- | --- |
+| `Line` | 后端按生成行号从 1 递增 |
+| `Name` | 每间房第一位旅客的姓氏 / 第一段姓名 |
+| `First Name` | 每间房第一位旅客的名字 / 剩余姓名 |
+| `Title` | 前端传入，第一版可为空 |
+| `Arrival` | 前端传入 |
+| `Departure` | 前端传入 |
+| `Room Type` | 前端传入 |
+| `Rate Code` | 前端传入 |
+| `Number of Rooms` | 第一版每行固定为 `1`，后续如目标模板变化再调整 |
+| `Adults` | 前端传入；为空时可由后端按当前分组人数派生 |
+| `Children` | 前端传入；第一版默认可为 `0` |
+| `Payment Type` | 前端传入 |
+| `VIP` | 前端传入，第一版可为空 |
+| `Accompanying Guests` | 同房其他旅客姓名，英文逗号分隔 |
+| `Nationality` | 前端传入 |
+| `Email` | 前端传入，第一版可为空 |
+| `ID Type` | 前端传入，第一版可为空 |
+| `ID Number` | 前端传入，第一版可为空 |
+
+中文说明：
+
+- 除 `Line`、`Name`、`First Name`、`Number of Rooms`、`Accompanying Guests` 外，第一版都由前端输入或选择。
+- 如果前端希望 `Adults` 自动等于当前房间人数，后端可以提供默认规则；但请求体仍建议显式保留覆盖字段，方便后续处理儿童、领队或特殊房间。
+
+## 7. 接口契约
+
+第一版已新增业务接口，不复用 M008 文件转换接口：
+
+```text
+POST /api/reservation/rooming-lists/generations
+Authorization: Bearer <access_token>
+Content-Type: multipart/form-data
+```
+
+表单字段：
+
+| 字段 | 类型 | 必填 | 中文说明 |
+| --- | --- | --- | --- |
+| `file` | file | 是 | 来源 Excel 文件，仅支持 `.xls` / `.xlsx` |
+| `hotel_id` | string | 否 | 酒店 ID；不传时按当前登录用户默认酒店或单酒店上下文解析 |
+| `people_per_room` | integer | 是 | 每间房人数，必须大于 0 |
+| `arrival` | string | 是 | 入住日期，酒店本地业务日期，格式 `yyyy-MM-dd` |
+| `departure` | string | 是 | 离店日期，酒店本地业务日期，格式 `yyyy-MM-dd` |
+| `room_type` | string | 是 | 目标 Excel 的 `Room Type` |
+| `rate_code` | string | 否 | 目标 Excel 的 `Rate Code` |
+| `adults` | integer | 否 | 目标 Excel 的 `Adults`；为空时可由后端按分组人数派生 |
+| `children` | integer | 否 | 目标 Excel 的 `Children`；为空时默认 `0` |
+| `payment_type` | string | 否 | 目标 Excel 的 `Payment Type` |
+| `vip` | string | 否 | 目标 Excel 的 `VIP` |
+| `nationality` | string | 否 | 目标 Excel 的 `Nationality` |
+| `email` | string | 否 | 目标 Excel 的 `Email` |
+| `id_type` | string | 否 | 目标 Excel 的 `ID Type` |
+| `id_number` | string | 否 | 目标 Excel 的 `ID Number` |
+
+成功响应：
+
+```text
+HTTP 200
+Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
+Content-Disposition: attachment; filename="rooming-list-<timestamp>.xlsx"
+```
+
+错误响应沿用后端统一错误模型，例如：
+
+```json
+{
+  "error_code": "ROOMING_LIST_SOURCE_FILE_INVALID",
+  "message": "来源名单文件不合法。",
+  "details": [
+    "未找到表头：护照全名"
+  ]
+}
+```
+
+已收口的第一版错误场景：
+
+- multipart 必填字段缺失，返回 `ROOMING_LIST_VALIDATION_FAILED`。
+- `arrival` / `departure` 日期格式错误，返回 `ROOMING_LIST_VALIDATION_FAILED`。
+- `people_per_room`、`adults`、`children` 数字格式错误，返回 `ROOMING_LIST_VALIDATION_FAILED`。
+- 来源文件缺失、非 `.xls` / `.xlsx`、无法读取或缺少 `护照全名` 表头，返回 `ROOMING_LIST_SOURCE_FILE_INVALID`。
+- 错误详情只返回字段名或行号，不回显完整名单、证件号或源文件内容。
+
+## 8. 权限、安全和审计
+
+接口分类：`FRONTEND_USER`。
+
+已新增权限码：
+
+```text
+RESERVATION_ROOMING_LIST_GENERATE
+```
+
+管控要求：
+
+- 必须登录。
+- 必须拥有 `RESERVATION_ROOMING_LIST_GENERATE` 权限。
+- 必须校验用户对 `hotel_id` 的访问权。
+- 第一版直接下载、不落库，因此不写生成记录表。
+- 当前 CP1 不新增持久化审计表；后续如增加生成记录或历史下载，再补业务审计落库。
+- 日志和错误响应不得输出完整名单、证件号、源文件内容或生成文件内容。
+
+## 9. 后端实现拆分
+
+已实现类职责：
+
+| 类 / 能力 | 中文职责 |
+| --- | --- |
+| `ReservationRoomingListGenerationController` | 接收前端上传请求，做登录、权限和酒店上下文校验 |
+| `ReservationRoomingListGenerationService` | 编排来源解析、分房、目标 Excel 渲染和文件响应 |
+| `ReservationRoomingListGenerationServiceImpl` | 具体业务实现 |
+| `RoomingListSourceExcelParser` | 解析来源 Excel，提取护照姓名 |
+| `RoomingListNameParser` | 拆分 `/` 或空格格式的护照姓名 |
+| `RoomingListGroupingService` | 按每房人数分组并生成目标行模型 |
+| `RoomingListExcelRenderer` | 生成目标格式 `.xlsx` |
+| `ReservationRoomingListGenerationRequest` | multipart 外的业务参数请求模型 |
+| `ReservationRoomingListGeneratedFile` | 生成后的下载文件字节和文件名 |
+| `ReservationRoomingListGuestDto` | 解析后的旅客姓名结构 |
+| `ReservationRoomingListRoomDto` | 分房后的目标行结构 |
+
+中文说明：
+
+- 第一版不需要新增 Entity、Mapper 和 Repository。
+- 如果后续要生成记录、OSS 上传、历史查询或重下载，再新增 `workflow_reservation_rooming_list_generation` 表。
+- 解析和渲染能力应和 Controller 解耦，便于单元测试。
+- 目标 Excel 固定列宽，不调用 POI `autoSizeColumn`，避免后端运行环境依赖本机字体或图形环境。
+
+## 10. 前端实现建议
+
+第一版页面可以放在 Reservation 工具入口，例如：
+
+```text
+/reservation/rooming-lists/new
+```
+
+页面能力：
+
+- 上传来源 Excel。
+- 填写每间房人数。
+- 填写或选择 Arrival、Departure、Room Type、Rate Code、Payment Type、Nationality 等字段。
+- 展示解析预览：总人数、预计房间数、前几行分房结果。
+- 点击生成后下载 `.xlsx`。
+
+前端注意：
+
+- 不要在前端解析完整 Excel 作为权威结果；前端预览可以后置为后端 preview 接口。
+- 第一版如果没有 preview 接口，可以只展示用户输入和文件名，生成成功后直接下载。
+- 不要把上传文件内容、客人名单或生成文件内容写进浏览器日志、错误上报、URL 或 localStorage。
+
+## 11. 测试范围
+
+后端测试建议覆盖：
+
+- 能识别 `护照全名` 表头。
+- `LI/CHUNHONG` 能拆成 `Name=LI`、`First Name=CHUNHONG`。
+- `LI CHUNHONG` 能拆成 `Name=LI`、`First Name=CHUNHONG`。
+- 姓名首尾空格会 trim。
+- `people_per_room=3` 时 32 人生成 11 行。
+- 尾房人数不足时仍生成一行。
+- `Accompanying Guests` 使用英文逗号拼接。
+- 未找到表头时返回明确错误。
+- 非 Excel 文件、空文件、超大文件返回明确错误。
+- 无 token、无权限、无酒店访问权被拦截。
+
+## 12. 后续版本候选
+
+后续可以继续扩展：
+
+- 生成记录表和历史下载。
+- 生成文件上传 OSS。
+- 后端预览接口。
+- 支持前端手工调整分房顺序。
+- 支持不同房间不同人数。
+- 支持字段映射配置，允许用户选择来源 Excel 中的姓名列。
+- 支持从订单、任务或 SourceMessage 附件自动带入名单。
+- 支持从任务详情或订单详情预填 Arrival、Departure、Room Type、Rate Code 等字段。
--- a/docs/project/security-access-control-boundary.md
+++ b/docs/project/security-access-control-boundary.md
@@ -55,6 +55,7 @@
 | `POST /api/reservation/tasks/{taskId}/opera-operations/{operationId}/retry` | `FRONTEND_USER` | 当前为 OPERA 模拟 | 登录 + `RESERVATION_OPERA_SIM_EXECUTE` + 酒店访问权 | 必须写业务审计和 attempt |
 | `GET /api/reservation/tasks/{taskId}/audits` | `FRONTEND_USER` | 已强制 Bearer 登录 + `RESERVATION_AUDIT_READ`；按任务实际所属酒店校验访问权 | 保持登录 + `RESERVATION_AUDIT_READ` + 酒店访问权 | 查询审计不再写审计 |
 | `POST /api/reservation/invoices/manual-generations` | `FRONTEND_USER` | 已实现 M009 CP2；强制 Bearer 登录 + `RESERVATION_INVOICE_GENERATE` + 酒店访问权；`task_id` / `order_id` 可为空，传入时反查对象所属酒店 | 保持登录 + `RESERVATION_INVOICE_GENERATE` + 酒店访问权；后续如增加历史列表或预填接口需单独登记权限 | 写业务审计，记录来源类型、模板版本、生成结果摘要；生成失败写入生成记录安全错误摘要 |
+| `POST /api/reservation/rooming-lists/generations` | `FRONTEND_USER` | 已实现 M010 CP1；multipart 上传来源名单并直接下载 `.xlsx` | 登录 + `RESERVATION_ROOMING_LIST_GENERATE` + 酒店访问权；第一版不落库、不上传 OSS | CP1 不落生成记录表；错误响应不得记录完整名单和证件信息，后续若增加历史记录再补业务审计 |

 ### 3.3 来源邮件接口

@@ -124,6 +125,7 @@
 | `RESERVATION_OPERA_SIM_EXECUTE` | 执行或重试 OPERA 模拟 / 未来真实操作 | OPERA execute / retry |
 | `RESERVATION_AUDIT_READ` | 查看业务审计流水 | 任务审计列表 |
 | `RESERVATION_INVOICE_GENERATE` | 生成 Reservation Proforma Invoice | Manual Invoice 生成、未来任务 / 订单预填生成 |
+| `RESERVATION_ROOMING_LIST_GENERATE` | 生成 Reservation Rooming List Excel | Rooming List 上传名单并生成 `.xlsx` 下载 |
 | `SOURCE_MESSAGE_READ` | 查看来源邮件安全摘要 | SourceMessage 列表、详情、会话摘要 |
 | `SOURCE_MESSAGE_ORIGINAL_READ` | 查看邮件正文、HTML 和附件外链 | original / conversation 完整正文；必须叠加 `SOURCE_MESSAGE_READ` 使用 |
 | `SYSTEM_DEBUG_EML_RUN` | 使用 Debug EML 调试链路 | Debug EML 上传、查询、stream |