# 课程初始订单

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

## 每次上课前执行

在项目根目录使用 PowerShell 7：

```powershell
.\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 分钟。确认和审批要求订单观察时间在最近五分钟内，因此演示期间需要保持同步进程运行。

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

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

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

## 课中订单同步

单次同步当前课程：

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

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

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

课后停止后台同步：

```powershell
.\scripts\start_course_demo.ps1 -Action Stop
```

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

## 课堂登记仓储完成

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

```powershell
.\.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`。