# 泰国 ERP Skill + Script 完整交接文档

## 1. 交接快照

- 日期：2026-07-12
- 工作区：当前 Codex 共享工作区
- 目标：让伙伴可以从自然语言输入稳定得到 task JSON，并通过安全脚本进入既有 LaoTai/LianTai ERP 能力。
- 本轮范围：任务契约、runner、8 个 Skill 包、整体说明、5 个业务交接文档。
- 真实 ERP：本轮未执行真实 ERP 保存、更新或导出；所有新增验证使用 dry-run、stub、既有 no-ERP 测试和 fixture。
- Git：当前 .git 目录不是可用 Git 仓库，因此没有提交 checkpoint；后续应在真正仓库中提交本轮文件。

## 2. 已交付文件

### 任务契约与脚本

- tools/erp_task_contract.js：erp-task-v1 标准化和校验。
- scripts/validate_erp_task.js：只校验任务，不调用 ERP。
- scripts/run_erp_task.js：读取任务、校验、调用 dispatcher、返回脱敏摘要。
- scripts/run_create_order.js：create_order 薄封装。
- scripts/run_update_order.js：update_order 薄封装。
- scripts/run_export_recovery.js：export_confirmation 薄封装。
- tools/erp_task_dispatcher.js：ready 任务契约门禁和 plannedExecutor 摘要。

### Skill 包

每个包都包含 SKILL.md、references/，需要 fixture 的业务包还包含 tests/fixtures/；skill-creator quick_validate 已逐包运行。

- skills/erp-coordinator/
- skills/erp-create-order/
- skills/erp-update-order/
- skills/erp-export-recovery/
- skills/erp-runtime-safety/
- skills/erp-session-runtime/
- skills/erp-diagnostics-maintenance/
- skills/erp-pdf-delivery/

### 交接文档

- docs/erp-skill-packages/overall-overview.md：整体架构和使用入口。
- docs/erp-skill-packages/complete-handoff.md：本文件，记录当前状态和继续工作方法。
- docs/erp-skill-packages/templates/business-handoff-template.md：业务文档模板。
- docs/erp-skill-packages/businesses/：创建、更新/旅客、导出恢复、安全/会话、诊断/PDF 五个业务交接。

## 3. 验证证据

本轮已验证：

- 任务契约和 dispatcher：ready 任务标准化、非法任务阻断、非 ready 不进入执行器。
- runner：有效 team_single dry-run、非法 route 不调用 handler、业务 wrapper 拒绝错 operation、stub completed 返回脱敏摘要。
- 8 个 Skill：各自 quick_validate 通过；各自内容/行为测试通过。
- 创建四路由 fixture：team_single、team_batch、split_parent、split_child 都能进入 dry-run；team_batch 文档要求 team_single fallback。
- 更新 fixture：房间/备注和旅客附件都能 dry-run；旅客任务只传 attachment path。
- 导出 fixture：Xingyou/JOB dry-run 通过；split_parent confirmation 在契约层阻断。
- 会话回归：现有 erp_session 测试 13/13 通过。
- PDF 单元测试：5/5 通过。
- no-ERP 健康检查：13/13 通过。

最终全量验收：npm test 通过 378 total / 375 passed / 3 skipped / 0 failed；health:no-erp 通过 13/13。后续变更后仍应重新运行这些命令。

## 4. 当前可用状态

| 能力 | 状态 | 说明 |
|---|---|---|
| Skill -> task JSON | 可用 | 规则和契约已落地，输入不完整先澄清 |
| 统一 dry-run | 可用 | 默认不保存 ERP |
| team_single create | 有现有 executor/测试 | 真实执行需重新授权 |
| team_batch | fallback 可用、native deferred | 不要调用或宣称 DoInfoJHs 已验证 |
| split_parent / split_child | 有现有 executor/fixture/测试 | 真实执行需重新授权和回查 |
| room/remark/traveler update | 有现有 parser/import/测试 | 价格/人数更新仍标 optional/unverified |
| source export/recovery | Xingyou 默认，Liantai/JOB 显式 | 不重新保存 |
| PDF delivery | 独立包 | 不由 create/update 自动触发 |
| diagnostics | maintainer-only | 默认 no-ERP/read-only |

## 5. 已知阻塞和边界

1. 原生 team_batch / DoInfoJHs 继续 deferred；如要恢复，需有 ERP 后端错误或已知正确 payload 的证据，且先做 dry-run。
2. update_order 的 price/pax 跨路由能力仍未统一验证，不能由 Skill 承诺。
3. visitor-detail 是独立只读导出能力，不能混入默认 confirmation export；若需要统一 dispatcher 入口，应先补契约和 handler 测试。
4. 真正执行依赖本地浏览器、ERP 登录、sender whitelist、allowRealSubmit 和 task lock；本轮没有替伙伴开启这些权限。
5. Windows quick_validate 需要 python -X utf8，避免 Python 默认 GBK 读取 UTF-8 Skill 文档。

## 6. 伙伴继续工作的标准流程

1. 阅读 overall-overview.md 和对应业务文档。
2. 让 Skill 生成一个 operation 的 task JSON，保留 originalText、attachments 路径和 schemaVersion。
3. 运行 validate_erp_task.js；invalid_task 或 needs_clarification 不得继续。
4. 默认运行 run_erp_task.js --mode dry-run，检查 route、plannedExecutor、字段和附件边界。
5. 只有在独立授权、配置和 session 都满足时才考虑 execute；执行后必须检查 audit、registry 和 ERP re-query。
6. 导出或 PDF 失败时走 recovery/delivery，不创建、不更新、不重保存。
7. 更新测试证据、业务文档和 .project-docs，再交接下一位伙伴。

## 7. 结果与客户回复边界

客户回复只说业务状态、ERP 编号、artifact 类型、下一步和必要阻塞原因。不得输出 selector、stack trace、凭据、cookie、授权码、内部路径或旅客 PII。execution_uncertain 必须先查询再决定，不得用“看起来成功”替代证据。

## 8. 负责人和下一步

- Skill 规则负责人：维护自然语言识别、字段映射、澄清和业务文档。
- 脚本负责人：维护契约、runner、dispatcher 摘要、审计和测试。
- ERP 运行负责人：维护 config、session、登录、白名单、实时授权和真实回查。
- 当前下一步：在可用 Git 仓库中提交本轮文件；随后为新增业务补标准模板、fixture、内容测试和 dry-run 证据，不先开真实保存。