zhifu-platform/docs/course-demo.md

课程初始订单

每次课程使用独立客户和订单。商品为 keyboard-01 办公键盘，可申请数量为 1 件，创建时签收时间设为当前时间的两天前。课堂故障说明使用“键盘部分按键失灵，申请换货 1 件”。准备完成时保留空会话，换货申请由课堂操作创建。

每次上课前执行

在项目根目录使用 PowerShell 7：

.\scripts\start_course_demo.ps1

入口为本次课程生成名称，将订单登记到独立 OMS，经已授权的 SERVICE 账户同步到平台，并核对当前客户能读取订单。课程记录保存到 .work/course-demo/active.json，历史记录保存到 .work/course-demo/sessions/。客户密码与 OMS 凭据保存在 .work/course-demo/credentials.json；这些文件受 .gitignore 排除。

消费者使用本次记录中的 customer.username 登录 H5。主管使用现有 supervisor01 账户，员工密码保存在 .work/frontend-accounts.json。客户和主管使用不同浏览器会话。

入口加载课程 OMS 凭据到 fulfillment 容器，然后在后台每 60 秒从 OMS 读取订单并同步到平台，默认持续 180 分钟。确认和审批要求订单观察时间在最近五分钟内，因此演示期间需要保持同步进程运行。

可以指定课程名称和同步时长：

.\scripts\start_course_demo.ps1 -Session lesson-02 -DurationMinutes 120

相同名称复用同一客户、订单和会话，保留签收时间、商品数量、审批和履约结果。需要一份初始数据时使用新名称，或者执行不带 -Session 的命令。每次启动只维护当前课程的后台同步，此前的课程记录继续保留。

课中订单同步

单次同步当前课程：

.\.venv\Scripts\python.exe scripts\prepare_course_demo.py sync

同步读取 OMS 当前商品数量与来源版本，不改变 OMS 订单。每次请求使用新的 Idempotency-Key，使平台更新 observed_at。同一来源版本下的订单业务内容必须保持一致。

同步日志位置记录在 .work/course-demo/sync-process.json。遇到网络、权限或业务检查失败，进程终止并将错误写入对应日志；检查服务后可以为该课程再次启动同步。登录会话到期前重新获取同步账户令牌。

课后停止后台同步：

.\scripts\start_course_demo.ps1 -Action Stop

该命令按进程标识、创建时间和命令路径核验目标，停止本入口创建的同步进程，并保留课程数据及项目服务。

课堂登记仓储完成

客户确认、主管批准后，等待平台工单进入 PROCESSING、OMS 操作进入 ACCEPTED。在项目根目录执行：

.\.venv\Scripts\python.exe scripts\prepare_course_demo.py complete

命令读取当前课程记录，核验唯一的本订单履约操作，使用仓储凭据调用 POST /exchanges/{operation_id}/complete，并同步 OMS 当前订单数量。需要指定课程或操作时使用 --session lesson-02 和 --operation-id <UUID>。跨订单操作会被拒绝；重复完成返回原有完成结果。

OMS 返回 COMPLETED 后，平台履约进程继续查询并将工单更新为 COMPLETED。客户在进度页面点击“读取最新方案”检查结果。完成证据保存在该课程记录的 completion 字段。

环境与数据范围

• 使用已经运行的完整项目：平台 API 默认端口 28000，OMS 默认端口 28100，前端端口 18762。
• 本机 .env、.env.oms、.work/runtime.env、.work/models 和开发账户文件需要存在，Python 环境包含项目开发依赖。
• 准备命令只支持 development 或 test，并限定现有开发商家和店铺。当前已发布的键盘规则和商品需要有效。
• 课程客户仅拥有本人业务所需权限；同步账户仅拥有订单同步权限。平台 OMS 凭据与仓储完成凭据分别登记。
• 已存在其他 OMS 连接器时，准备命令终止并报告冲突；现有规则和发布资料保持原有配置。
• 新建 OMS 订单使用具有 can_fulfill 权限的凭据调用 PUT /orders/{order_id}，平台同步使用 SERVICE 身份调用 PUT /internal/v1/orders/{order_id}，客户查询使用本人会话。重复准备核对已有 OMS 订单并复用记录。
• 单次 HTTP 请求最长 10 秒；准备流程最长 90 秒。持续同步有明确时长，PowerShell 入口允许 1 至 180 分钟。
• 准备和同步不发送咨询消息，不创建 AgentRun，也不调用生成模型。课堂中的 AI 咨询使用项目当前已发布的模型配置。

已执行的真实业务验证

2026-09-28 使用独立验收课程 validation-20260928-1823，通过真实 API、当前履约进程、RabbitMQ 和独立 OMS 完成 DRAFT → WAITING_REVIEW → APPROVED → PROCESSING → COMPLETED。

同键重复确认返回一致，确认与审批记录各 1 条；重复登记仓储完成保持同一操作标识和外部版本。完成后平台与 OMS 的可申请数量均为 0，来源版本均为 2。该客户 AgentRun 与 ModelAttempt 数据库记录数量均为 0。验收耗时 14.09 秒，直接 HTTP 请求 21 次，单并发，流程期限 120 秒；另外执行两次同步命令和一次重复完成命令。

报告保存在 .work/course-demo/validation-report.json。课堂初始数据使用独立课程 lesson-01-20260928，保持数量 1、来源版本 1、空会话及零工单。模型生成与工具选择由课堂咨询触发，其运行结果需要按当次记录查看。

同日通过真实浏览器检查课程客户登录、订单列表、订单详情及申请入口：列表与详情均显示可申请数量 1，申请表数量默认 1、故障说明为空。会话消息为 0，当前 Agent 运行为空，页面错误和失败响应均为 0。浏览器报告保存在 .work/course-demo/lesson-01-20260928-browser.json。