537 lines
13 KiB
Markdown
537 lines
13 KiB
Markdown
# 开发 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 私自定死。
|
||
|
||
如果做不到以上标准，不应进入生产联调。
|