huangting/th-hotel-simple
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

同步V4与M011文档状态

Browse Source
This commit is contained in:
andy
2026-07-20 14:44:14 +07:00
parent 8f893991dd
commit e5218e10eb
7 changed files with 53 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/project/README.md
View File

@@ -61,7 +61,7 @@
| `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。 |
| `requirements/M011-booking-excel-pre-superagent-enrichment-v1.md` | 当前有效 | M011 Booking Excel 附件预处理方案；CP1/CP2/CP3 已支持 Debug EML 和 AgentBus dispatch 调 SuperAgent 前排除人员名单类 Excel、抽取 Booking / 附加费类 Excel 高亮行并追加 `attachment_extractions[]`；生产 AgentBus 增强默认关闭。 |
| `requirements/M011-booking-excel-pre-superagent-enrichment-v1.md` | 当前有效 | M011 Booking Excel 附件预处理方案；CP1/CP2/CP3 已支持 Debug EML 和 AgentBus dispatch 调 SuperAgent 前排除人员名单类 Excel、抽取 Booking / 附加费类 Excel 高亮行并追加 `attachment_extractions[]`；测试机 AgentBus 增强已开启，生产默认关闭；CP4 暂不推进。 |
## 集成契约

4
docs/project/frontend-backend/README.md
View File

@@ -48,7 +48,7 @@
| 订单任务多卡模型 V4 | `docs/project/requirements/M002-v4-order-task-card-domain-model-cp2.md` | 当前 V4 主入口；后端已开放工作台统一列表、V4 订单任务列表 / 详情、卡片确认、复核解阻、S10/S99 来源通知详情和 ack；前端已完成 V4 页面第一版、目录 lookup 接入、订单详情 V4 时间线消费和系统设置目录管理 CP1。 |
| 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` 直接下载；前端 V1 已新增 `/reservation/rooming-lists/new`，按 Blob 下载处理，不落库、不上传 OSS。 |
| Booking Excel 附件预处理 | `docs/project/requirements/M011-booking-excel-pre-superagent-enrichment-v1.md` | 当前有效；Debug EML 和 AgentBus dispatch 已支持调 SuperAgent 前排除人员名单类 Excel、抽取 Booking / 附加费类 Excel 高亮行并生成 `attachment_extractions[]`；生产 AgentBus 增强默认关闭。 |
| Booking Excel 附件预处理 | `docs/project/requirements/M011-booking-excel-pre-superagent-enrichment-v1.md` | 当前有效；Debug EML 和 AgentBus dispatch 已支持调 SuperAgent 前排除人员名单类 Excel、抽取 Booking / 附加费类 Excel 高亮行并生成 `attachment_extractions[]`；测试机 AgentBus 增强已开启，生产默认关闭；CP4 暂不推进。 |
| 订单任务主流程 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` | 前后端协作清单，已区分可用、后置和历史候选路径，不替代后端权威契约。 |
@@ -65,7 +65,7 @@
- 任务卡字段控件契约 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 和前端 V1 已按 M010 落地：接口为 `POST /api/reservation/rooming-lists/generations`，前端页面为 `/reservation/rooming-lists/new`，上传来源名单、填写每房人数和目标列字段，后端同步返回 `.xlsx` 下载；该能力不依赖订单或任务，第一版不落库、不上传 OSS，权限码为 `RESERVATION_ROOMING_LIST_GENERATE`。
- Booking Excel 附件预处理已按 M011 落地 CP1/CP2/CP3：Debug EML 和 AgentBus dispatch 调用 SuperAgent 前由后端解析 Excel 附件，排除人员名单类文件，只把 Booking Update / 附加费表的高亮行业务摘要追加为 `attachment_extractions[]`；第一版不新增前端普通业务入口，AgentBus 增强生产默认关闭。
- Booking Excel 附件预处理已按 M011 落地 CP1/CP2/CP3：Debug EML 和 AgentBus dispatch 调用 SuperAgent 前由后端解析 Excel 附件，排除人员名单类文件，只把 Booking Update / 附加费表的高亮行业务摘要追加为 `attachment_extractions[]`；第一版不新增前端普通业务入口，测试机 AgentBus 增强已开启，生产默认关闭，CP4 暂不推进。
- Reservation V4 目录管理后台 CP1 已前后端接入：系统设置下新增 `/system/reservation-catalogs`，需要登录用户具备 `RESERVATION_CATALOG_MANAGE`；前端可维护 Account、Room Type、Rate Code 的列表、新增、启用 / 停用，并明确提示停用目录不再进入普通 V4 任务卡 lookup。
## 6. 前端开发注意事项

2
docs/project/integrations/superagent-agentbus-project-integration-guide.md
View File

@@ -497,7 +497,7 @@ AGENTBUS_TEST_SUPERAGENT_DISPATCH_INCLUDE_BOOKING_EXCEL_EXTRACTIONS=true
RESERVATION_BOOKING_EXCEL_EXTRACTION_ENABLED=true
```
中文说明：`agentbus.superagent-dispatch.include-booking-excel-extractions` 只控制 AgentBus worker 是否把抽取结果追加给 SuperAgent；`reservation.booking-excel-extraction.enabled` 是解析服务总开关。两者必须同时开启才会产生有效高亮行结果，生产环境默认关闭。
中文说明：`agentbus.superagent-dispatch.include-booking-excel-extractions` 只控制 AgentBus worker 是否把抽取结果追加给 SuperAgent；`reservation.booking-excel-extraction.enabled` 是解析服务总开关。两者必须同时开启才会产生有效高亮行结果。当前测试机已开启该增强，生产环境默认关闭，生产开启需单独确认。
当前表名为 `platform_superagent_dispatch_run`，详细字段、状态流转、错误分类和验收标准见
`docs/project/requirements/M007-agentbus-superagent-auto-dispatch-v1.md`。

56
docs/project/integrations/superagent-api-contract.md
View File

@@ -4,9 +4,9 @@
| 项目 | 内容 |
| --- | --- |
| 文档版本 | 0.9 |
| 日期 | 2026-07-18 |
| 状态 | 当前代码契约已支持 V4 入站解析基线、V2 `ai_task_results[]` 兼容、结构化 S10/S99、V3 业务根基础解析、旧 S000/S999 兼容和单酒店 hotel_id 后端解析 |
| 文档版本 | 0.10 |
| 日期 | 2026-07-20 |
| 状态 | 当前代码契约已支持 V4 订单任务 + 多卡入站、V4 S10/S99 来源通知、V2 `ai_task_results[]` 兼容、V3 业务根兼容、旧 S000/S999 兼容、M011 Booking Excel 调 SuperAgent 前预处理增强和单酒店 hotel_id 后端解析 |
| 适用范围 | SuperAgent 调用本系统查询上下文、查询邮件会话、提交 AI 任务结果 |
| 主要读者 | SuperAgent 对接方、后端、测试、运维 |
@@ -105,7 +105,7 @@ SuperAgent 不应知道或依赖内部 SourceMessage Inbox ID，也不需要为
查询接口 3、4 面向已经入库的邮件会话：缺省酒店由后端解析，`external_conversation_id` 最终仍按 `hotel_id + source_provider + source_channel + external_conversation_id` 查询；`source_message_id` 表示外部来源消息 ID，可作为锚点反查该邮件所属会话。
## 3.1 M002 V3 迁移提醒
## 3.1 M002 V3 / V4 迁移提醒
2026-07-11 起，项目需求基线已确认采用 `docs/project/requirements/M002-order-task-workflow-v3.md`；2026-07-12 起，Parent Group / Allotment 路由采用 `docs/project/requirements/M002-v3-p0.1-parent-group-routing-update.md`：
@@ -116,16 +116,39 @@ SuperAgent 不应知道或依赖内部 SourceMessage Inbox ID，也不需要为
- 完整 Parent split 的父事件必须使用 `Cancel Allotment + cancel_allotment_control_block`；`relationship_type=linked_parent_release_after_child_split` 只用于关联和 Preflight，不再作为独立任务 subtype。
- 当前新入站不接受 `Cancel Booking + linked_parent_release_after_child_split` 作为合法业务任务；该组合仅允许历史数据只读兼容。
当前后端已完成 M002 V3 CP1-CP6：
2026-07-18 起，M002 V4 以 `docs/project/requirements/M002-v4-agent-callback-field-contract.md` 和 `docs/project/requirements/M002-v4-order-task-card-domain-model-cp2.md` 为当前有效业务入站契约：
- V4 普通业务包使用 `route_code=null`、`source_message`、`order_contexts[]` 和 `message_events[]`。
- `source_message.source_message_id` 是外部来源消息 ID，对应 SourceMessage Inbox 的 `external_message_id`，不是本系统内部数据库 ID。
- 普通业务按 `source_message + order_ref` 创建 V4 订单任务，并在订单任务下创建来源消息只读卡、Basic Information 卡和业务事件卡。
- Basic Information 必须先确认；业务卡逐卡确认或复核解阻，确认后永久锁定；V4 第一版不提供前端草稿。
- `route_code=S10/S99` 使用 V4 来源通知模型，不创建隐藏技术订单，不进入订单详情时间线，不阻塞普通订单；前端只展示和 ack。
- Account / Market / Source、Room Type、Rate Code 以本系统数据库目录稳定代码为准；SuperAgent 不应输出显示文案作为业务判断依据。
当前后端仍兼容 M002 V3 CP1-CP6：
- 已建立 40 条 P0.1 路由枚举 / 稳定配置；`route_code` 保持历史稳定，不按总数连续重编号，`R41/R42` 仍可能出现在响应和历史 transition 中。
- 已支持结构化 `S10/S99` 入站，创建只读 `SOURCE_MESSAGE_ONLY` 任务。
- 已支持结构化 `S10/S99` 历史入站兼容；当前 V4 新入站使用来源通知模型。
- 已支持 V3 业务根 `source_message + message_events[]` 的基础解析；可派生到现有任务模型的 event 会创建业务任务，无法派生、显式契约错误或基础 manual_review / parent split 结构不完整的 event 只落 `adapter_contract_error` transition，不创建业务任务。
- 已支持 `unhandled_current_intents[]` 最小落库：只写 `UNHANDLED_CURRENT_INTENT` transition，不创建业务任务，也不按 adapter 契约错误返回。
- 已在 `workflow_reservation_ai_transition` 保存 `route_code`、`system_process_category`、`adapter_error_code` 和 `adapter_error_message`。
- 已支持 type-known manual review 同卡解阻、当前订单归属确认、P0 fixtures 回归测试和 V3 typed `infrastructure_input_error` 响应。
尚未完成：真实 OPERA / OHIP、普通任务切换订单、字段矩阵从当前扁平结构整体迁移到 0711 P0 新结构、历史旧 Parent Cancel Booking payload 批量迁移。
尚未完成：真实 OPERA / OHIP、普通任务切换订单、历史旧 Parent Cancel Booking payload 批量迁移、真实 PMS / OPERA / OHIP 目录同步和 SuperAgent 目录机器接口。
## 3.2 M011 Booking Excel 预处理输入增强
M011 已在 Debug EML 和 AgentBus 自动分发链路中接入 Booking Excel 附件预处理。该能力发生在 TH Hotel 后端调用 SuperAgent Open API 前，不属于 SuperAgent 调本系统的 `task-results` 请求体字段，但会影响 SuperAgent 实际看到的邮件 payload。
处理边界：
- 后端只处理邮件附件中的 `.xls` / `.xlsx`，识别并排除 `PASSENGER_ROSTER` 人员名单类 Excel。
- 对 `BOOKING_UPDATE` 和 `BOOKING_SURCHARGE` 类 Excel，按最近 6 个月候选窗口选择文件内实际存在的最新 3 个业务月，并抽取有背景色标记的业务行。
- 非空结果追加到 AgentBus Outlook-like payload 的 `attachment_extractions[]` 字段，供 SuperAgent 作为证据输入。
- `attachment_extractions[]` 只增强 SuperAgent 判断上下文，不直接创建订单、订单任务、任务卡、客户回复或 OPERA / OHIP 操作。
- 测试机 AgentBus 增强已开启；生产 AgentBus 增强默认关闭。只有 `reservation.booking-excel-extraction.enabled` 和 AgentBus dispatch include 开关同时开启时才会追加该字段。
字段契约、抽取规则和安全边界以 `docs/project/requirements/M011-booking-excel-pre-superagent-enrichment-v1.md` 为准。SuperAgent 生成最终 V4 结果时，仍必须按本文第 8 节的 `source_message + order_contexts[] + message_events[]` 契约回调本系统。
## 4. 接口 1：查询订单上下文
@@ -564,14 +587,15 @@ V4 字段说明：
当前已支持的 V4 行为：
- 命中 SourceMessage 后保存 AI batch / transition，并按 `message_events[]` 顺序处理。
- 可映射 event 先复用现有订单 / 任务 / 任务卡链路，`ai_payload_json` 会保留 `v4_source_message`、`v4_order_context`、`v4_message_event`。
- `route_code=S10/S99` 创建只读 `SOURCE_MESSAGE_ONLY` 任务，任务列表可见，订单列表不可见。
- V4 包级结构错误如果仍能通过 `source_message.source_message_id` 定位 SourceMessage，会返回成功接收并写入 `adapter_contract_error` transition；不创建订单、任务或用户可处理卡。`source_message_id` 缺失或找不到 SourceMessage 时仍返回明确错误。
- `PAYMENT.attachment_ids[]` 引用不存在的附件、`UPDATE_BOOKING` 携带 `rate_code`、以及其他 V4 event 契约错误，只写 `adapter_contract_error` transition，不创建用户可处理业务任务。
- 命中 SourceMessage 后保存 AI batch / transition，并按 `source_message + order_contexts[] + message_events[]` 处理。
- 普通业务包按 `source_message + order_ref` 创建 V4 订单任务，并创建 `SOURCE_MESSAGE_DISPLAY`、`BASIC_INFORMATION` 和业务事件卡。
- Basic Information 必须先确认；业务卡逐卡确认或复核解阻，确认后永久锁定；V4 第一版不提供前端草稿。
- `route_code=S10/S99` 创建 V4 来源通知，工作台可见，订单列表和订单详情不可见；来源通知只能 ack，不创建订单、不阻塞订单。
- V4 包级结构错误如果仍能通过 `source_message.source_message_id` 定位 SourceMessage，会返回成功接收并写入 `adapter_contract_error` transition；不创建订单任务、任务卡或来源通知。`source_message_id` 缺失或找不到 SourceMessage 时仍返回明确错误。
- `PAYMENT.attachment_ids[]` 引用不存在的附件、`UPDATE_BOOKING` 携带不允许字段、目录代码无法匹配当前酒店数据库目录，以及其他 V4 event 契约错误，只写 `adapter_contract_error` transition，不创建用户可处理业务任务。
- 技术契约错误不会自动转为 S10/S99，也不会创建前端可处理业务任务。
当前 V4 入站仍未完成完整多卡模型：Basic Information 独立卡、V4 页面模型、真实 OPERA / OHIP、普通任务切换订单均后置。
当前仍未完成：真实 OPERA / OHIP、真实 PMS / OPERA / OHIP 目录同步、普通任务切换订单、SuperAgent 目录机器接口和前端订单详情 V4 化。
### 8.3 V3 S10/S99 结构化请求体
@@ -682,7 +706,7 @@ V3 字段说明：
- MCP 路径缺失 `source_message.source_message_id` 或整个 `source_message` 时，保留业务入站层 `MISSING_SOURCE_MESSAGE_ID` 错误语义。
- 40 条 P0.1 路由进入后端枚举 / 稳定配置。
- `route_code` 是稳定代码，不因路由总数从 42 调整为 40 而重编号；联调方不要按数字连续性判断合法性。
- 结构化 `S10/S99` 创建只读 `SOURCE_MESSAGE_ONLY` 任务，任务列表可见，订单列表不可见。
- V3 结构化 `S10/S99` 兼容路径创建只读 `SOURCE_MESSAGE_ONLY` 任务，任务列表可见，订单列表不可见；V4 新入站不走该模型，改用来源通知。
- 业务 event 能派生到稳定路由时，复用现有订单 / 任务 / 任务卡创建链路。
- 完整 Parent split 父事件必须提交为 `event_type=Cancel Allotment`、`extracted_fields.cancel_scope=entire_allotment_control_block`、`task_subtype=cancel_allotment_control_block`，并保留 `relationship_type=linked_parent_release_after_child_split` 作为关系字段。
- 当前新入站若提交 `event_type=Cancel Booking` 且 `relationship_type=linked_parent_release_after_child_split`，写入 `adapter_contract_error` transition，不创建业务任务；旧 V2 兼容 `ai_task_results[]` 中的同等三元组按请求级 `ADAPTER_CONTRACT_ERROR` 拒绝。
@@ -759,7 +783,7 @@ V3 字段说明：
正式联调时，SuperAgent 不需要传 `hotel_id`。后端通过系统酒店和外部 `source_message_id` 查找唯一 `platform_source_message_inbox.external_message_id`，真实 provider/channel 以 Inbox 入库值为准。如果没有找到，返回 `SOURCE_MESSAGE_NOT_FOUND`；如果同一系统酒店下匹配到多条，返回 `SOURCE_MESSAGE_AMBIGUOUS`。本地旧夹具允许在缺少 `hotel_id` 时使用内部数字 SourceMessage ID，但该兼容路径不作为 SuperAgent 正式契约。
`informational_message` 结构化任务仅用于历史兼容。新数据如果是纯信息类邮件或无法形成业务素材包，应优先使用 V3 结构化 `S10/S99`；旧联调或兼容场景仍可使用下面的 `S000/S999` 文本请求体。
`informational_message` 结构化任务仅用于历史兼容。新数据如果是纯信息类邮件或无法形成业务素材包，应优先使用 V4 `S10/S99` 来源通知；V3 结构化 `S10/S99` 和下面的 `S000/S999` 文本请求体仅作为旧联调或兼容路径。
### 8.6 S000/S999 文本请求体
@@ -783,7 +807,7 @@ S999,mail-20260708-0001
| `S999` | 入口阶段无法形成业务素材包，不需要进入业务执行。 |
| `mail-20260708-0001` | 外部来源消息 ID，对应 SourceMessage Inbox 的 `external_message_id`。 |
S000/S999 不在 body 里传 `hotel_id`，后端使用平台酒店表唯一 `ACTIVE` 酒店和外部消息 ID 查询 SourceMessage Inbox。命中后创建 `SOURCE_MESSAGE_ONLY` 只读特殊任务：任务列表可见，订单列表不可见，不允许编辑、确认、转换订单、执行 OPERA 或重试 OPERA，也不参与同订单任务执行顺序阻塞。该文本格式仅为兼容路径，新数据优先使用结构化 `S10/S99`。
S000/S999 不在 body 里传 `hotel_id`，后端使用平台酒店表唯一 `ACTIVE` 酒店和外部消息 ID 查询 SourceMessage Inbox。命中后创建 `SOURCE_MESSAGE_ONLY` 只读特殊任务：任务列表可见，订单列表不可见，不允许编辑、确认、转换订单、执行 OPERA 或重试 OPERA，也不参与同订单任务执行顺序阻塞。该文本格式仅为兼容路径；新数据优先使用 V4 `S10/S99` 来源通知。
### 8.7 成功响应

12
docs/project/requirements/M011-booking-excel-pre-superagent-enrichment-v1.md
View File

@@ -2,7 +2,7 @@
| 项目 | 内容 |
| --- | --- |
| 文档状态 | 当前有效；CP1 / CP2 / CP3 已实现，生产链路默认关闭 |
| 文档状态 | 当前有效；CP1 / CP2 / CP3 已实现，测试机 AgentBus 增强已开启，生产链路默认关闭；CP4 暂不推进 |
| 适用范围 | AgentBus 入站邮件和 Debug EML 上传邮件中的 Excel 附件，在调用 SuperAgent Open API 前做结构化预处理 |
| 当前目标 | 排除旅行名单类 Excel，抽取 Booking / 附加费类 Excel 中带背景色的业务行，生成安全 JSON 并附加到发给 SuperAgent 的 payload |
| 依赖能力 | SourceMessage Inbox、Debug EML、AgentBus 自动分发、Apache POI、OSS 附件读取能力、SuperAgent Open API |
@@ -19,7 +19,7 @@
## 2. 目标
- 在 AgentBus 自动分发和 Debug EML 上传两条链路中复用同一套 Excel 附件预处理逻辑；当前两条链路均已接入，生产链路仍由配置默认关闭。
- 在 AgentBus 自动分发和 Debug EML 上传两条链路中复用同一套 Excel 附件预处理逻辑；当前两条链路均已接入，测试机 AgentBus 增强已开启，生产链路仍由配置默认关闭。
- 识别并排除旅行名单类 Excel，避免把人员名单误当成 Booking 更新或附加费数据。
- 对 Booking Update / Booking Surcharge 类 Excel，按最近月份筛选 sheet，只抽取有业务背景色的行。
- 把抽取结果追加到发给 SuperAgent 的 AgentBus Outlook-like payload 中，字段建议为 `attachment_extractions[]`。
@@ -352,7 +352,7 @@ server/src/main/java/cn/nianxx/thhotel/workflows/reservation/excelimport
| `agentbus.superagent-dispatch.booking-excel-download-max-size` | `10MB` | AgentBus 自动分发读取单个 Excel 附件的最大大小，避免 worker 下载异常大文件 |
| `debug.eml-upload.include-booking-excel-extractions` | `false` | Debug EML 是否返回并传递抽取结果 |
中文说明：建议先在 Debug EML 打开，验证样例 Excel 和 SuperAgent 结果稳定后，再在测试机打开 AgentBus 自动分发增强；生产仍保持默认关闭。
中文说明：Debug EML 和测试机 AgentBus 自动分发增强已可用于验证样例 Excel 与 SuperAgent 结果稳定性；生产仍保持默认关闭，生产开启需要单独确认。
## 11. 错误处理和安全边界
@@ -403,12 +403,12 @@ server/src/main/java/cn/nianxx/thhotel/workflows/reservation/excelimport
- AgentBus dispatch worker 在调用 SuperAgent 前读取 SourceMessage 已保存附件引用，并通过后端对象存储端口下载 Excel 内容。
- 复用 `ReservationBookingExcelAttachmentExtractionService` 执行同一预处理，非空结果追加到发给 SuperAgent 的 AgentBus Outlook-like payload。
- 生产链路默认配置关闭，测试机可通过 `agentbus.superagent-dispatch.include-booking-excel-extractions=true` 验证后再评估开启。
- 测试机 AgentBus 增强已开启；生产链路默认配置关闭，生产开启需单独确认。
- 附件读取或解析失败时追加安全跳过结果 / warning 并继续调用 SuperAgent；日志和 payload 不写完整附件 URL、签名参数、API Key、Cookie 或 Secret。
### CP4：可选持久化和运营查询
### CP4：可选持久化和运营查询（暂不推进）
如果后续需要追踪 Excel 解析历史，再单独设计持久化表，例如：
当前 CP4 不进入近期开发计划。如果后续需要追踪 Excel 解析历史，再单独设计持久化表，例如：
```text
workflow_reservation_booking_excel_import_batch

2
docs/project/security-access-control-boundary.md
View File

@@ -121,7 +121,7 @@
| SuperAgent Open API Client | `INTERNAL_ONLY` | 只能后端 Adapter 使用，Secret 不出后端 | 通过 debug run 或 dispatch run 追踪 |
| OSS Adapter | `INTERNAL_ONLY` | 前端只能拿后端返回的安全 URL，不能拿 OSS Secret | 上传和读取入口记录安全摘要 |
| AgentBus dispatch worker | `INTERNAL_ONLY` | 只由后端调度或受控管理入口触发 | `platform_superagent_dispatch_run` |
| Booking Excel 附件预处理 | `INTERNAL_ONLY` | M011 CP1 / CP2 / CP3 已接入 Debug EML 与 AgentBus dispatch；只允许后端在调用 SuperAgent 前通过 Service / Port 使用，不单独暴露给前端或第三方 | 记录安全 warning、附件名、hash 前缀、sheet 名、行号和高亮业务行摘要；不得记录完整 Excel、完整附件 URL、签名参数、API Key、Cookie、Secret 或名单类客户敏感原文 |
| Booking Excel 附件预处理 | `INTERNAL_ONLY` | M011 CP1 / CP2 / CP3 已接入 Debug EML 与 AgentBus dispatch，测试机 AgentBus 增强已开启；只允许后端在调用 SuperAgent 前通过 Service / Port 使用，不单独暴露给前端或第三方 | 记录安全 warning、附件名、hash 前缀、sheet 名、行号和高亮业务行摘要；不得记录完整 Excel、完整附件 URL、签名参数、API Key、Cookie、Secret 或名单类客户敏感原文 |
| Flyway / bootstrap 初始化 | `INTERNAL_ONLY` | 不提供运行时外部接口 | 通过部署记录和数据库 history 追踪 |
| 未来 OPERA / OHIP Adapter | `INTERNAL_ONLY` | 浏览器不得直接调用；只能业务服务触发 | 必须记录操作、attempt 和外部结果摘要 |