Yozu API完整参考:/api/cases工单创建、查询与状态流转一网打尽

原创2026-10-16 11:09:371,431 阅读

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):

  1. 计算优先级:decisionDeadline 为 Today → urgent,Tomorrow → high,其余 → normal;
  2. 初始化状态:state 置为 new,approvalState 置为 draft_review(草稿评审),disclosureMode 置为 operator_assembled(运营汇编);
  3. 写入审计事件:记录一条 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 构建自己的差旅工单自动化流程了。

登录后查看全文
yozu-web