huangting/th-hotel-simple

Fork 0

Files

andy 9fa608f602 提交一次全量代码

2026-07-09 11:59:34 +08:00

13 KiB

Raw Permalink Blame History

开发 AI 先读：AI 过渡表落地工作顺序

本文档给信息系统开发侧的 AI 使用。
请在写代码、建表、做前端任务卡之前先读完本文档。

你的角色不是邮件处理 AI，也不是 Booking Skill。
你的角色是：信息系统开发 AI。

你需要根据项目资料和 Excel 契约，帮助开发人员完成：

MySQL 过渡表设计；
AI 输出 JSON 入库；
任务卡前端展示与编辑；
用户确认后的 confirmed_payload_json；
Opera API 写入前参数组装；
Opera 写入结果底表落库。

1. 你要先读哪些文件

请按以下顺序读取，不要跳读。

第 1 份：本文档

先读：

开发AI先读_工作顺序.md

目的：先知道你的工作边界和执行顺序。

第 2 份：开发契约 README

再读：

AI过渡表开发契约_README.md

目的：理解两张 Excel 表怎么使用，哪些字段能改，哪些字段不能改，哪些字段不能写 Opera。

第 3 份：Excel 契约

再读：

AI过渡表开发契约_两张样例表.xlsx

只需要读这两张 sheet：

AI输出参数并集字典
任务卡展示编辑矩阵

不要把以下文件当成业务契约：

AI过渡表开发契约_两张样例表.xlsx.inspect.ndjson

它只是生成 Excel 时的检查日志，不给开发使用。

第 4 份：AI 项目资料

项目资料在桌面文件夹：

/Users/chillishark/Desktop/0630AI_副本

请按以下顺序读取：

01_main_agent_prompt.md
02_agent_workflow.md
03_skill_catalog.md

然后再读各个 Skill：

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：

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. 你必须先理解的整体链路

系统链路是：

邮件
  -> 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 输出结构

先读：

AI输出参数并集字典

你要搞清楚：

AI 总共可能输出哪些字段；
每个字段的 字段路径；
字段类型；
是否数组；
是否可为空；
建议数据库落法；
是否建议建索引；
开发使用方式。

这一阶段不要急着写前端。

这一阶段的产出应该是：

过渡表主表设计草案；
JSON 字段设计草案；
常用冗余物理列设计草案；
索引设计草案。

阶段二：设计 MySQL 过渡表

推荐使用：

核心物理列 + 完整 JSON

核心物理列用于查询、筛选、幂等和状态机。

完整 JSON 用于保留 AI 原始输出。

建议至少保留：

ai_payload_json
case_keys_json
extracted_fields_json
manual_review_json
informational_message_json
attachments_json
context_used_json
confirmed_payload_json

建议物理列包括：

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

不要把所有嵌套字段都建成物理列。
只有高频查询、筛选、幂等、任务状态机需要的字段才冗余建列。

阶段三：理解任务卡展示矩阵

再读：

任务卡展示编辑矩阵

任务卡选择逻辑是：

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 / 附件预览
`是否表格编辑 = 是`	用表格组件

下拉框选项只能来自：

下拉选项/枚举值

不要自行扩展枚举。

阶段五：实现用户确认逻辑

AI 原始输出必须保留，不得覆盖。

建议保存：

ai_payload_json
confirmed_payload_json

含义：

字段	含义
`ai_payload_json`	AI 原始输出，只读保存
`confirmed_payload_json`	用户确认或修改后的最终参数

用户在任务卡里修改字段后，写入：

confirmed_payload_json

后续 Opera API 参数必须从 confirmed_payload_json 读取。
不要直接从 ai_payload_json 读取 Opera 参数。

阶段六：实现 Opera API 写入前判断

只有满足以下条件，才允许进入 Opera API 写入：

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 处理规则

第一版只使用：

normal_task
manual_review
informational_message

不要使用：

exception_task
no_action

处理方式：

result_type	处理方式
`normal_task`	创建普通任务卡，用户确认后可写 Opera
`manual_review`	创建人工复核卡，不写 Opera
`informational_message`	创建信息提醒卡，不写 Opera

5. task_type 覆盖范围

当前需要支持：

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。

人工复核卡需要展示：

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 必须等待父任务完成后再执行。

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. 重点禁止事项