Yozu API完整参考:/api/cases工单创建、查询与状态流转一网打尽
Yozu API完整参考:/api/cases工单创建、查询与状态流转一网打尽
Yozu 是面向企业差旅的 AI 决策与执行协调平台(AI Travel Decision & Execution Layer),其核心 REST 接口 Yozu API /api/cases 承载了全部差旅工单(Trip Case)的生命周期管理:通过 POST 从 intake 表单一键创建工单、通过 GET 查询工单列表与详情、通过 PATCH 驱动审批状态流转(approvalState)与 preflight 预检门禁。本篇指南带你从请求参数、响应结构到状态机门禁规则,完整掌握 /api/cases 的每个接口。
🔎 30 秒看懂:/api/cases 接口总览
/api/cases 由两个路由文件实现,共提供 4 个接口:
| 路径 | 方法 | 作用 |
|---|---|---|
/api/cases |
GET |
查询工单列表(自动合并存储层数据与演示种子工单) |
/api/cases |
POST |
从 intake 表单数据创建新工单 |
/api/cases/{id} |
GET |
查询单个工单详情,同时返回审计事件列表 |
/api/cases/{id} |
PATCH |
更新工单:审批状态流转、preflight 预检、disclosure 披露 |
所有响应都带一个 mode 字段,表示当前存储模式:postgres(已配置 POSTGRES_URL)或 memory-fallback(内存兜底)。列表接口在存储层异常时会降级返回 memory-fallback-degraded 并仅回传演示种子数据,保证接口永不 5xx。
接口实现分别在 app/api/cases/route.ts 与 app/api/cases/[id]/route.ts。
🛠 工单创建:POST /api/cases 请求参数详解
创建工单只需发送一段 JSON,字段与 /intake 表单一一对应(全部为可选字符串,缺省为空):
| 参数名 | 说明 | 示例 |
|---|---|---|
company |
公司 / 账户 | Northstar Capital |
approvalOwner |
审批负责人 | CEO / Founder / Managing Partner |
decisionDeadline |
决策截止时间,决定优先级 | Today / Tomorrow / This week |
destination |
目的地 | New York + Boston |
dates |
日期与弹性 | June 20-23 |
travelers |
出行人 | Solo executive |
budget |
预算范围 | Under $4,500 |
stakes |
行程风险与目标 | 需保住投资人会面窗口 |
constraints |
约束 / 偏好 | 避免末班航班风险 |
contact |
回复联系方式 | name@example.com |
一个典型的创建请求:
curl -X POST http://localhost:3000/api/cases \
-H "Content-Type: application/json" \
-d '{
"company": "Northstar Capital",
"approvalOwner": "CEO",
"decisionDeadline": "Tomorrow",
"destination": "New York + Boston",
"dates": "June 20-23",
"travelers": "Solo executive",
"budget": "Under $4,500",
"contact": "name@example.com"
}'
成功时返回工单 ID(格式为 OPS- + 6 位时间戳尾数):
{
"mode": "memory-fallback",
"id": "OPS-654321",
"status": "created"
}
创建时服务端会自动完成三件事(见 app/lib/ops.ts 的 buildTripCaseFromIntake):
- 计算优先级:
decisionDeadline为Today→urgent,Tomorrow→high,其余 →normal; - 初始化状态:
state置为new,approvalState置为draft_review(草稿评审),disclosureMode置为operator_assembled(运营汇编); - 写入审计事件:记录一条
case_created事件,标记"工单已创建并进入受保护运营队列"。
前端 /intake 页面的提交按钮正是调用此接口,实现见 app/intake/intake-form.tsx。
📋 工单查询:GET 列表与详情接口
GET /api/cases 列表查询
返回结构为 { mode, cases }。其合并策略很巧妙:
- 存储层中非种子工单会先经过
sanitizeCaseForPublicOps脱敏(公司名、出行人、目的地下沉为Protected *占位),避免公开演示面泄露真实 intake 数据,脱敏逻辑见 app/lib/ops.ts; - 3 条演示种子工单(
YC-2401~YC-2403)始终展示,若存储层存在同 ID 记录则优先取存储版本。
运营队列页 app/ops/cases/queue-client.tsx 就是消费该接口的示例。
GET /api/cases/{id} 详情查询
返回 { case, events } 两部分:工单完整快照 + 按时间倒序的审计事件列表。工单不存在时返回 404:
{ "error": "not_found" }
详情接口实现见 app/api/cases/[id]/route.ts。
🔁 状态流转全解:approvalState 状态机
每个工单有两层状态:
state(工作流状态):new→reviewing→options_sent→awaiting_approval→coordinating→closed,由审批状态自动推导,无需手动设置;approvalState(审批状态):流转的核心,只能通过PATCH按状态机规则推进。
7 个审批状态及其中文含义(标签定义见 app/lib/ops.ts):
| approvalState | 含义 |
|---|---|
draft_review |
草稿评审 |
options_prepared |
方案已备妥 |
approval_requested |
已请求审批 |
approval_blocked |
审批被阻塞 |
approval_granted |
审批已通过 |
returned_to_review |
退回重审 |
ready_for_handoff |
可移交协调 |
合法流转表(状态机定义见 app/lib/ops.ts):
| 当前状态 | 允许流转到 |
|---|---|
draft_review |
options_prepared |
options_prepared |
approval_requested |
approval_requested |
approval_granted / approval_blocked / returned_to_review |
approval_blocked |
(终态,需人工介入) |
approval_granted |
ready_for_handoff |
returned_to_review |
options_prepared |
ready_for_handoff |
(终态) |
对应的工作流状态映射(app/lib/ops.ts):
| approvalState | 推导出的 state |
|---|---|
draft_review / returned_to_review |
reviewing |
options_prepared |
options_sent |
approval_requested / approval_blocked / approval_granted |
awaiting_approval |
ready_for_handoff |
coordinating |
🛡 PATCH 更新门禁:为什么状态改不动
PATCH /api/cases/{id} 是最复杂也最"安全"的接口,所有变更先过三道守卫,任何一道不过都会拒绝写入并留下审计记录:
1️⃣ 受保护工单守卫 → 403 protected_case
intake 创建并落库的真实工单(受保护工单)不允许在公开演示面被修改,直接返回 403 并写入 protected_mutation_denied 事件。见 app/api/cases/[id]/route.ts。
2️⃣ 状态流转守卫 → 400 transition_denied
目标 approvalState 若不在上文合法流转表内(例如想从 draft_review 直接跳到 approval_granted),返回 400:
{
"error": "transition_denied",
"message": "Transition from Draft review to Approval granted is not allowed."
}
3️⃣ Handoff 守卫 → 400 transition_denied
要进入 ready_for_handoff 必须同时满足三个条件(守卫逻辑见 app/lib/ops.ts):
- 当前已是
approval_granted(显式审批通过); - preflight 已执行且结果不是
blocked/reconfirm_required; - disclosure 披露已被确认(
disclosureAcknowledgedAt非空)。
4️⃣ Preflight 守卫 → 400 preflight_denied
preflight 预检只能在审批通过之后执行:approvalState 必须为 approval_granted 或 ready_for_handoff,否则拒绝(app/lib/ops.ts)。
一次合法的"审批通过"更新:
curl -X PATCH http://localhost:3000/api/cases/YC-2402 \
-H "Content-Type: application/json" \
-d '{ "approvalState": "approval_granted" }'
一次合法的 preflight 更新(preflightStatus 取值:pass / warn / blocked / reconfirm_required;preflightReasonCode 取值如 price_inventory_stale_risk、source_freshness_stale、required_approval_missing 等,定义见 app/lib/ops.ts):
curl -X PATCH http://localhost:3000/api/cases/YC-2402 \
-H "Content-Type: application/json" \
-d '{ "preflightStatus": "warn", "preflightReasonCode": "price_inventory_stale_risk" }''
PATCH 成功后返回最新完整工单快照与 requestId。另外注意一个自动回退规则:若 preflight 结果为 blocked 或 reconfirm_required,而工单处于 ready_for_handoff,服务端会自动回退到 approval_granted(app/api/cases/[id]/route.ts)。运营详情页的状态操作按钮调用此接口,见 app/ops/cases/[id]/case-detail-client.tsx。
🧾 审计事件:每一次操作都留痕
/api/cases 的写操作(包括被拒绝的操作)都会追加一条 AuditEvent,字段包括 eventId、actorType(requester / operator / system / public_demo)、action、beforeState → afterState、source、summary。GET /api/cases/{id} 返回的 events 数组即按时间倒序的完整操作轨迹,常见 action 值:
| action | 触发场景 |
|---|---|
case_created |
POST 创建工单 |
options_prepared / approval_requested / approval_granted |
审批状态推进 |
approval_transition_denied |
非法流转被拒 |
preflight_passed / preflight_warn / preflight_blocked |
preflight 结果写入 |
disclosure_shown / disclosure_acknowledged |
披露展示与确认 |
protected_mutation_denied |
受保护工单被尝试修改 |
审计事件的类型定义见 app/lib/ops.ts。
💾 存储模式与本地运行指南
存储层由 app/lib/case-store.ts 统一管理,支持两种模式:
- postgres 模式:配置环境变量
POSTGRES_URL后启用,自动建表case_core(工单主表)与audit_event(审计表),并做增量alter table兼容旧库; - memory-fallback 模式:未配置数据库时使用进程内存 Map 兜底,接口行为完全一致,但重启后数据清空,适合本地体验。
本地快速上手:
git clone https://gitcode.com/gh_mirrors/yo/yozu-web
cd yozu-web
npm install
npm run dev
打开 http://localhost:3000,在 /intake 页提交表单即可触发 POST /api/cases,再到 /ops/cases 队列与详情页面观察状态流转。
📁 核心文件索引
| 文件 | 说明 |
|---|---|
| app/api/cases/route.ts | 列表查询 + 工单创建 |
| app/api/cases/[id]/route.ts | 详情查询 + 状态流转 PATCH |
| app/lib/ops.ts | 状态机、守卫规则、审计类型与演示种子数据 |
| app/lib/case-store.ts | postgres / 内存双模存储层 |
| app/intake/intake-form.tsx | 调用创建接口的前端表单 |
| app/ops/cases/queue-client.tsx | 消费列表接口的运营队列 |
| app/ops/cases/[id]/case-detail-client.tsx | 消费 PATCH 接口的工单详情页 |
掌握以上四个接口与状态机规则后,你就完全可以围绕 /api/cases 构建自己的差旅工单自动化流程了。