# 泰国 LaoTai/LianTai ERP Skill + Script 总体说明

## 1. 文档目的

本文是伙伴协同的总入口，说明系统由哪些 Skill、脚本和既有 ERP 工具组成，一条用户消息如何变成结构化任务，以及什么条件下可以进入真实 ERP 执行。

单个订单不再单独复制成长篇交接文档。订单级信息以 task JSON、dispatcher audit JSON、order registry 记录和输出 artifact 管理；业务规则和交接方法由本目录的业务文档统一管理。

## 2. 分层职责

| 层 | 负责内容 | 不负责内容 |
|---|---|---|
| Skill | 理解中文/微信输入、判断唯一业务意图、选择 route、字段标准化、澄清缺失信息、生成 task JSON、把脚本结果转成业务回复 | ERP 页面/API、浏览器 selector、保存动作、旅客表格内容读取 |
| scripts | 读取任务文件、校验 erp-task-v1、调用统一 dispatcher、返回脱敏摘要、提供 create/update/export 薄封装 | 自己复制 ERP 表单逻辑、绕过安全开关、代替 Skill 解释自然语言 |
| tools | dispatcher、adapter、route executor、browser/API、重复检查、session、lock、registry、导出和审计 | 把未经校验的自然语言直接送入 ERP |
| docs/.project-docs | 维护整体说明、业务交接、验证证据、决策、当前状态和下一步 | 记录单个订单的隐私明细或替代 audit JSON |

## 3. Skill 包清单

| 包 | 业务边界 | 主要脚本/工具 | 当前定位 |
|---|---|---|---|
| erp-coordinator | 统一理解与路由 | validate_erp_task.js、run_erp_task.js | P0 总协调 |
| erp-create-order | team_single、team_batch 回退、split_parent、split_child | run_create_order.js、各 route executor | P0 创建 |
| erp-update-order | 已有订单房间/备注/旅客更新 | run_update_order.js、update parser/import/handlers | P0 更新 |
| erp-export-recovery | 既存订单 source export 和保存后恢复 | run_export_recovery.js、operation handlers、registry | P0 导出恢复 |
| erp-runtime-safety | dry-run、真实提交授权、重复、回查、不确定状态 | dispatcher、submit guard、registry、task lock | P1 安全支撑 |
| erp-session-runtime | 登录、人工验证码、共享 session、条件等待、锁恢复 | session manager、interactive login、condition waits | P1 会话支撑 |
| erp-diagnostics-maintenance | no-ERP 健康、只读探针、维护诊断 | health check、API probes、inspect/performance tools | 维护者专用 |
| erp-pdf-delivery | source artifact 转 PDF 和交付 | erp_pdf_conversion.js、convert_erp_docs_to_pdf.ps1 | 独立交付 |

## 4. 统一任务生命周期

    用户中文输入
      -> Skill 理解与澄清
      -> 生成一个 operation 的 task JSON
      -> scripts/validate_erp_task.js
      -> scripts/run_erp_task.js 或业务薄封装
      -> tools/erp_task_dispatcher.js
      -> route executor / operation handler
      -> ERP 或 source artifact
      -> 脱敏结果 JSON
      -> Skill 生成业务回复

ready 任务使用 schemaVersion: erp-task-v1。创建任务必须有 operation=create_order 和 route；更新任务必须有 identifier 和 updatePlan.actions；导出任务必须有已有 identifier 和 exportTypes。输入不完整时使用 needs_clarification，不调用脚本。

## 5. 任务和运行规则

- 默认运行模式是 dry-run。dry-run 只验证任务、路由和计划，不打开真实 ERP 保存链路。
- allowRealSubmit 只能来自本地配置和安全授权，不能由 Skill 写入 task JSON，也不能由用户一句“马上保存”替代。
- attachments 只传路径；Skill/agent 不在实时下单过程中打开或改写旅客工作簿。
- 一个输入只进入一个 operation。创建和确认件导出是两个阶段；保存成功后导出失败走 recovery，不重新创建。
- team_batch 原生 DoInfoJHs 仍是 deferred；使用已经验证的 team_single fallback，不能宣称原生批量接口成功。
- 完成必须有 ERP 证据和保存后 re-query；HTTP 200、旧列表行或泛化成功弹窗都不能单独证明完成。

## 6. 统一脚本入口

    node scripts/validate_erp_task.js --task <task.json> --json
    node scripts/run_erp_task.js --task <task.json> --mode dry-run --config config/erp-deployment.local.json --json
    node scripts/run_create_order.js --task <task.json> --mode dry-run --json
    node scripts/run_update_order.js --task <task.json> --mode dry-run --json
    node scripts/run_export_recovery.js --task <task.json> --mode dry-run --json

CLI 返回状态包括 dry_run、completed、blocked、invalid_task、needs_clarification、post_save_recovery_required 和 execution_uncertain。脚本输出只保留安全摘要字段，不把旅客 PII 放到客户回复中。

## 7. 验证入口

开发变更至少运行：

    npm test
    npm run health:no-erp
    python -X utf8 C:\Users\wxy\.codex\skills\.system\skill-creator\scripts\quick_validate.py skills/<skill-name>

当前任务的 Skill 内容测试、行为测试、任务契约测试和 runner 测试都位于 tools/tests。真实 ERP 测试不属于本次打包验收；若后续执行，必须单独授权、使用非关键订单并保留 ERP re-query 证据。

## 8. 交接方式

伙伴先阅读本文，再按业务阅读 businesses/ 下的交接文档，最后查看 complete-handoff.md。新增业务必须复制 templates/business-handoff-template.md，补齐测试证据、阻塞、负责人和下一步，不在订单目录里写长篇自由格式说明。

## 9. 责任边界

Skill 维护者负责自然语言规则、字段映射和澄清话术；脚本维护者负责契约校验、dispatcher 薄封装、执行结果和审计；ERP 运行维护者负责登录、session、配置和真实授权；交接负责人负责证据、状态和下一步更新。