# 开发 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 私自定死。

如果做不到以上标准，不应进入生产联调。