提交一次全量代码

2026-07-09 11:59:34 +08:00
parent 855396e553
commit 9fa608f602
58 changed files with 8439 additions and 116 deletions
--- a/docs/import/20260706/开发AI先读_工作顺序.md
+++ b/docs/import/20260706/开发AI先读_工作顺序.md
@@ -0,0 +1,536 @@
+# 开发 AI 先读：AI 过渡表落地工作顺序
+
+本文档给信息系统开发侧的 AI 使用。  
+请在写代码、建表、做前端任务卡之前先读完本文档。
+
+你的角色不是邮件处理 AI，也不是 Booking Skill。  
+你的角色是：**信息系统开发 AI**。
+
+你需要根据项目资料和 Excel 契约，帮助开发人员完成：
+
+- MySQL 过渡表设计；
+- AI 输出 JSON 入库；
+- 任务卡前端展示与编辑；
+- 用户确认后的 `confirmed_payload_json`；
+- Opera API 写入前参数组装；
+- Opera 写入结果底表落库。
+
+## 1. 你要先读哪些文件
+
+请按以下顺序读取，不要跳读。
+
+### 第 1 份：本文档
+
+先读：
+
+```text
+开发AI先读_工作顺序.md
+```
+
+目的：先知道你的工作边界和执行顺序。
+
+### 第 2 份：开发契约 README
+
+再读：
+
+```text
+AI过渡表开发契约_README.md
+```
+
+目的：理解两张 Excel 表怎么使用，哪些字段能改，哪些字段不能改，哪些字段不能写 Opera。
+
+### 第 3 份：Excel 契约
+
+再读：
+
+```text
+AI过渡表开发契约_两张样例表.xlsx
+```
+
+只需要读这两张 sheet：
+
+- `AI输出参数并集字典`
+- `任务卡展示编辑矩阵`
+
+不要把以下文件当成业务契约：
+
+```text
+AI过渡表开发契约_两张样例表.xlsx.inspect.ndjson
+```
+
+它只是生成 Excel 时的检查日志，不给开发使用。
+
+### 第 4 份：AI 项目资料
+
+项目资料在桌面文件夹：
+
+```text
+/Users/chillishark/Desktop/0630AI_副本
+```
+
+请按以下顺序读取：
+
+```text
+01_main_agent_prompt.md
+02_agent_workflow.md
+03_skill_catalog.md
+```
+
+然后再读各个 Skill：
+
+```text
+skill/S01_new_booking_skill.md
+skill/S02_update_booking_amendment_skill.md
+skill/S03_cancel_booking_skill.md
+skill/S04_voucher_received_skill.md
+skill/S05_rooming_list_name_list_skill.md
+skill/S06_amend_group_code_skill.md
+skill/S07_trace_reservation_notes_skill.md
+skill/S08_ta_recorder_skill.md
+```
+
+最后按需读取 reference：
+
+```text
+references/qbd_liantai_email_table_rules.md
+skill/S01_new_booking_skill/references/room_type_mapping_rules.md
+skill/S01_new_booking_skill/references/rate_code_rules.md
+skill/S02_update_booking_amendment_skill/references/room_type_mapping_rules.md
+skill/S02_update_booking_amendment_skill/references/rate_code_rules.md
+```
+
+## 2. 你必须先理解的整体链路
+
+系统链路是：
+
+```text
+邮件
+  -> Main Agent 拆分 current 事件
+  -> 调用对应 Skill
+  -> Skill 输出 ai_task_result JSON
+  -> 信息系统写入过渡表
+  -> 信息系统创建任务卡
+  -> 用户确认或修改任务卡参数
+  -> 信息系统生成 confirmed_payload_json
+  -> 信息系统调用 Opera API
+  -> Opera 写入结果落底表
+```
+
+AI 阶段只输出 JSON。  
+AI 不直接写 Opera。  
+AI 不直接写数据库。  
+AI 不直接创建真实任务卡。
+
+信息系统负责：
+
+- 保存 AI 原始 JSON；
+- 根据 AI 输出创建任务卡；
+- 接收用户确认或修改；
+- 生成最终确认参数；
+- 调用 Opera API；
+- 保存写入结果。
+
+## 3. 你的工作总顺序
+
+请按以下阶段工作。
+
+## 阶段一：理解 AI 输出结构
+
+先读：
+
+```text
+AI输出参数并集字典
+```
+
+你要搞清楚：
+
+- AI 总共可能输出哪些字段；
+- 每个字段的 `字段路径`；
+- 字段类型；
+- 是否数组；
+- 是否可为空；
+- 建议数据库落法；
+- 是否建议建索引；
+- 开发使用方式。
+
+这一阶段不要急着写前端。
+
+这一阶段的产出应该是：
+
+- 过渡表主表设计草案；
+- JSON 字段设计草案；
+- 常用冗余物理列设计草案；
+- 索引设计草案。
+
+## 阶段二：设计 MySQL 过渡表
+
+推荐使用：
+
+```text
+核心物理列 + 完整 JSON
+```
+
+核心物理列用于查询、筛选、幂等和状态机。
+
+完整 JSON 用于保留 AI 原始输出。
+
+建议至少保留：
+
+```text
+ai_payload_json
+case_keys_json
+extracted_fields_json
+manual_review_json
+informational_message_json
+attachments_json
+context_used_json
+confirmed_payload_json
+```
+
+建议物理列包括：
+
+```text
+source_message_id
+source_event_index
+catalog_code
+skill_id
+result_type
+task_type
+current_or_history
+group_code
+confirmation_number
+idempotency_key
+manual_reason_code
+parent_source_event_index
+linked_task_group_id
+blocked_until_parent_completed
+execution_order
+created_at
+updated_at
+```
+
+不要把所有嵌套字段都建成物理列。  
+只有高频查询、筛选、幂等、任务状态机需要的字段才冗余建列。
+
+## 阶段三：理解任务卡展示矩阵
+
+再读：
+
+```text
+任务卡展示编辑矩阵
+```
+
+任务卡选择逻辑是：
+
+```text
+result_type + task_type + task_subtype/业务动作
+```
+
+不要只看 `task_type`。
+
+比如：
+
+- `result_type = normal_task` + `task_type = New Booking`：普通 New Booking 任务卡；
+- `result_type = manual_review` + `task_type = New Booking`：New Booking 人工复核卡；
+- `result_type = informational_message` + `task_type = Message Notification`：信息提醒卡。
+
+## 阶段四：开发前端任务卡
+
+每个字段按矩阵行处理。
+
+规则如下：
+
+| 矩阵列 | 前端动作 |
+|---|---|
+| `是否展示 = 是` | 展示该字段 |
+| `是否可编辑 = 是` | 用户确认前允许修改 |
+| `是否为输入方式编辑 = 是` | 用文本输入框 |
+| `是否为下拉框方式编辑 = 是` | 用下拉框或多选下拉 |
+| `是否日期选择 = 是` | 用日期选择器 |
+| `是否数字输入 = 是` | 用数字输入框 |
+| `是否文件展示 = 是` | 用图片 / PDF / 附件预览 |
+| `是否表格编辑 = 是` | 用表格组件 |
+
+下拉框选项只能来自：
+
+```text
+下拉选项/枚举值
+```
+
+不要自行扩展枚举。
+
+## 阶段五：实现用户确认逻辑
+
+AI 原始输出必须保留，不得覆盖。
+
+建议保存：
+
+```text
+ai_payload_json
+confirmed_payload_json
+```
+
+含义：
+
+| 字段 | 含义 |
+|---|---|
+| `ai_payload_json` | AI 原始输出，只读保存 |
+| `confirmed_payload_json` | 用户确认或修改后的最终参数 |
+
+用户在任务卡里修改字段后，写入：
+
+```text
+confirmed_payload_json
+```
+
+后续 Opera API 参数必须从 `confirmed_payload_json` 读取。  
+不要直接从 `ai_payload_json` 读取 Opera 参数。
+
+## 阶段六：实现 Opera API 写入前判断
+
+只有满足以下条件，才允许进入 Opera API 写入：
+
+```text
+result_type = normal_task
+用户已确认任务卡
+字段矩阵中 是否参与Opera写入 = 是 / 条件参与
+后端硬校验通过
+```
+
+以下情况不得写 Opera：
+
+- `manual_review`
+- `informational_message`
+- 证据区字段；
+- 只读展示字段；
+- 标注“不确定 / 需确认”的字段；
+- S04 的 `voucher_display_fields`；
+- history-only evidence；
+- 没有经过用户确认的 AI 原始值。
+
+## 阶段七：实现底表
+
+Opera API 调用完成后，需要落底表。
+
+底表保存：
+
+- 调用的 Opera API 参数；
+- Opera API 返回结果；
+- 写入状态；
+- 错误信息；
+- 酒店业务需要查看的字段。
+
+例如 New Booking：
+
+| 对象 | 底表业务字段 |
+---|---|
+| Group Block | `block_id`、`block_name` |
+| FIT Reservation | `reservation_no` |
+| Allotment / Control Block | `block_id`、`block_name` 或后续业务确认字段 |
+
+底表是给酒店业务看结果的，不是 AI 原始输出表。
+
+## 4. result_type 处理规则
+
+第一版只使用：
+
+```text
+normal_task
+manual_review
+informational_message
+```
+
+不要使用：
+
+```text
+exception_task
+no_action
+```
+
+处理方式：
+
+| result_type | 处理方式 |
+|---|---|
+| `normal_task` | 创建普通任务卡，用户确认后可写 Opera |
+| `manual_review` | 创建人工复核卡，不写 Opera |
+| `informational_message` | 创建信息提醒卡，不写 Opera |
+
+## 5. task_type 覆盖范围
+
+当前需要支持：
+
+```text
+New Booking
+Update Booking
+Cancel Booking
+Voucher Received
+Rooming List
+Amend Group Code
+Trace / Reservation Notes
+TA Recorder
+Message Notification
+Fallback
+```
+
+S09 Note Skill 尚未正式落地。  
+不要把 S09 当成正式任务卡开发。
+
+## 6. normal_task 与 manual_review 的区别
+
+`normal_task` 是可确认、可执行的任务候选。
+
+`manual_review` 是结构化人工复核，不是失败，也不是空任务。
+
+即使 `manual_review` 中有已知字段，也不能自动转成 `normal_task`。
+
+人工复核卡需要展示：
+
+```text
+manual_review.reason_code
+manual_review.visible_reason
+manual_review.blocking_points[]
+manual_review.missing_fields[]
+manual_review.conflicting_points[]
+manual_review.evidence_to_check[]
+manual_review.suggested_human_actions[]
+```
+
+注意：
+
+- S04 `Voucher Received` 的 manual_review 是精简结构。
+- S05 `Rooming List` 的 manual_review 是精简结构。
+- 前端和后端都要兼容字段为空或不存在。
+
+## 7. linked task 处理规则
+
+S07 和 S08 可能是 linked task。
+
+典型场景：
+
+- S01 / S02 / S06 同一事件里有 extra bed，需要生成 S07 linked task；
+- S05 Rooming List 确认后，为每个目标 group_code 派生 S08 TA Recorder；
+- linked task 必须等待父任务完成后再执行。
+
+相关字段：
+
+```text
+parent_source_event_index
+linked_task_group_id
+depends_on_task_type
+depends_on_source_event_index
+blocked_until_parent_completed
+execution_order
+source_rooming_list_task_id
+```
+
+处理原则：
+
+- 主任务先执行；
+- linked task 后执行；
+- 父任务未完成时，linked task 不得写 Opera；
+- 不得把 S07 trace 吞进主任务而不生成独立 S07；
+- S08 是一个目标 `group_code` 一张卡，不是一个 workbook 一张卡。
+
+## 8. QBD / LianTai 表格处理规则
+
+QBD / LianTai 表格非常重要。
+
+请遵守：
+
+- 一行 current 有效高亮 / 黄色行 = 一个 `source_event_index`；
+- 一行 = 一个 `ai_task_result`；
+- 一行 = 一个任务卡候选；
+- 不同表格行不得合并；
+- 不得用数组型 `case_keys.group_code` 合并多个任务；
+- 每个行级结果都要保留 `extracted_fields.table_evidence`。
+
+受控例外：
+
+- 同一行同时有主业务动作和 Trace / Guest Request / extra bed 时，可以生成主任务 + S07 linked task。
+- 这不是合并任务，而是父子任务。
+
+## 9. 字段路径不能改
+
+Excel 中的 `字段路径` 就是 AI 输出 JSON 路径。
+
+开发 AI 不得：
+
+- 重命名字段；
+- 自行新增字段；
+- 改嵌套层级；
+- 把顶层字段挪进 `extracted_fields`；
+- 把 `extracted_fields` 字段挪成顶层字段。
+
+如果字段标注“不确定 / 需确认 / 建议命名”，只能做兼容设计，不能当成最终强 schema。
+
+## 10. 重点禁止事项
+
+开发 AI 不得：
+
+- 一上来直接写前端，不先理解数据库和 JSON 契约；
+- 只看 `task_type`，不看 `result_type`；
+- 把 `manual_review` 写 Opera；
+- 把 `informational_message` 写 Opera；
+- 覆盖 AI 原始输出；
+- 直接从 `ai_payload_json` 组 Opera API 参数；
+- 从 `body_thread` 生成 normal task；
+- 把多个 `group_code` 合并到一个任务；
+- 把 QBD / LianTai 多行合并；
+- 用 S04 `voucher_display_fields` 做房型、价格、房量、Rate Code 或自动更新；
+- 把 extra bed 计入 `room_quantity`；
+- 把 `U-เตียงเสริม` 当成 PMS 房型；
+- 自行扩展未定义枚举；
+- 编造 Opera API endpoint、鉴权或返回结构。
+
+## 11. 推荐第一轮产出
+
+读完本文档、README、Excel 和项目资料后，开发 AI 第一轮不要立刻写代码。
+
+建议先输出：
+
+1. 我理解的系统链路。
+2. 我理解的两张表职责。
+3. 我计划如何设计 MySQL 过渡表。
+4. 我计划如何保存 AI 原始 JSON 和 confirmed payload。
+5. 我计划如何渲染任务卡。
+6. 我计划如何处理 normal / manual / informational。
+7. 我识别到的不确定点。
+8. 我需要人工确认的问题清单。
+
+确认后，再进入具体开发。
+
+## 12. 推荐开发顺序
+
+确认理解无误后，按以下顺序开发：
+
+1. 建过渡表主表。
+2. 建必要索引和幂等约束。
+3. 实现 AI 输出 JSON 入库。
+4. 实现 `ai_task_results[]` 拆分，一条结果一条过渡表记录。
+5. 实现任务卡读取接口。
+6. 按任务卡矩阵实现前端动态展示。
+7. 实现用户确认和字段修改。
+8. 生成 `confirmed_payload_json`。
+9. 实现 Opera API 参数组装。
+10. 实现 Opera API 调用。
+11. 实现底表落库。
+12. 做 normal / manual / informational / linked task / QBD-LianTai 多行测试。
+
+## 13. 最终判断标准
+
+开发结果至少要满足：
+
+- AI 原始输出能完整保存；
+- 每条 `ai_task_result` 能独立落过渡表；
+- 任务卡能按矩阵展示；
+- 可编辑字段能按矩阵编辑；
+- 下拉字段枚举来自矩阵；
+- 用户确认后生成 `confirmed_payload_json`；
+- Opera API 只读取 confirmed 参数；
+- manual_review 不写 Opera；
+- informational_message 不写 Opera；
+- linked task 能等待父任务；
+- QBD / LianTai 多行不会被合并；
+- 不确定字段不会被开发 AI 私自定死。
+
+如果做不到以上标准，不应进入生产联调。