5.9 KiB
5.9 KiB
泰国 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. 已知阻塞和边界
- 原生 team_batch / DoInfoJHs 继续 deferred;如要恢复,需有 ERP 后端错误或已知正确 payload 的证据,且先做 dry-run。
- update_order 的 price/pax 跨路由能力仍未统一验证,不能由 Skill 承诺。
- visitor-detail 是独立只读导出能力,不能混入默认 confirmation export;若需要统一 dispatcher 入口,应先补契约和 handler 测试。
- 真正执行依赖本地浏览器、ERP 登录、sender whitelist、allowRealSubmit 和 task lock;本轮没有替伙伴开启这些权限。
- Windows quick_validate 需要 python -X utf8,避免 Python 默认 GBK 读取 UTF-8 Skill 文档。
6. 伙伴继续工作的标准流程
- 阅读 overall-overview.md 和对应业务文档。
- 让 Skill 生成一个 operation 的 task JSON,保留 originalText、attachments 路径和 schemaVersion。
- 运行 validate_erp_task.js;invalid_task 或 needs_clarification 不得继续。
- 默认运行 run_erp_task.js --mode dry-run,检查 route、plannedExecutor、字段和附件边界。
- 只有在独立授权、配置和 session 都满足时才考虑 execute;执行后必须检查 audit、registry 和 ERP re-query。
- 导出或 PDF 失败时走 recovery/delivery,不创建、不更新、不重保存。
- 更新测试证据、业务文档和 .project-docs,再交接下一位伙伴。
7. 结果与客户回复边界
客户回复只说业务状态、ERP 编号、artifact 类型、下一步和必要阻塞原因。不得输出 selector、stack trace、凭据、cookie、授权码、内部路径或旅客 PII。execution_uncertain 必须先查询再决定,不得用“看起来成功”替代证据。
8. 负责人和下一步
- Skill 规则负责人:维护自然语言识别、字段映射、澄清和业务文档。
- 脚本负责人:维护契约、runner、dispatcher 摘要、审计和测试。
- ERP 运行负责人:维护 config、session、登录、白名单、实时授权和真实回查。
- 当前下一步:在可用 Git 仓库中提交本轮文件;随后为新增业务补标准模板、fixture、内容测试和 dry-run 证据,不先开真实保存。