API Contract Baseline

面向外部接入者：本页包含站点主链的接口命名与边界基线。要对接公开 C2AI2X 接口，请同时阅读 API Reference、首次请求与鉴权与 Scopes。

当前对外接口边界

公开咨询/入口、正式协议 API 和登录后的平台控制面是不同 surface。外部团队只能将明确发布在协议文档与 OpenAPI 中、并带有相应鉴权与稳定性说明的接口视为可调用能力；不要从站点表单、Widget 或内部实施字段推导出 SDK、Sandbox、SLA、结算或未公开控制面已经可用。

本页记录 www.zhenrobot.com 站点侧的最小接口边界说明，用于联调与实现对齐；它不是平台正式 contract 的替代品。

若接口语义与平台正式 contract 冲突，以 zhen-platform-core 为准。

提示如何使用这份基线

把它当成“命名与边界对照表”，帮助你避免字段和 URL 各写各的。
它解释的是本站需要暴露的最小前台接口，不代表你可以据此推导平台能力或开放范围。

0.1 2026-04-17 Round 1 实际落地说明

截至 2026-04-17-zhenrobot-gate-run01：

站点侧已补齐 quote.html、track.html、proof.html、exception.html
由于当前站点仍以 Nginx 静态出页为主、未提供同域 /api/* 写入端点，Round 1 的 quote_submit / track_read / proof_read / exception_read 先通过同域前端持久层完成最小受控实现
成功响应字段仍对齐本文件冻结命名：request_id、tracking_token、next_step_url
对外判定应保持克制：这说明本站的最小链路可跑通，不代表共享层订单主链已经对外成立

1. 当前接口家族应覆盖的业务对象

报价请求
下单引导或订单创建入口
订单状态读取
签收证明读取
异常上报或人工接管入口
文档 / 白皮书 / 协议下载入口
Webhook 转发或验证壳

2. 主链 contract 约束

站点侧只定义当前必须暴露的最小前台接口，不定义共享层的最终业务解释。

正式主链固定为：

public submit/read -> zhen-platform-core -> zhen-brain-core -> robot_execute / manual_takeover -> result writeback

固定原则：

浏览器或公开前台不直接调用 zhen-brain-core
任何付费、entitlement、Key、生效状态最终都由 zhen-platform-core 解释
若需要开发者读写订单、管理 Webhook 或读取账单，应经 zhen-platform-console 或共享层授权接口完成

3. Repo-local 允许承接的接口语义

公开咨询 / 报价表单提交
公开状态页所需的最小只读信息
文档、白皮书和企业接入入口跳转
当前仓库必需的 Webhook 路由或转发壳
公开订单跟踪页的状态与证明只读查询
异常上报、人工接管申请或客服升级入口

3.1 首个最小真实链路接口冻结版

在站点侧首个真实执行包出现前，最小必须补齐以下接口族，而不是继续扩散更多名词接口：

quote_submit
- 输入：最小必要联系信息、场景信息、服务区域信息
- 输出：request_id，以及后续可映射的 quote_id 或 order_id
track_read
- 输入：tracking_token
- 输出：最小状态对象与当前阶段说明
proof_read
- 输入：tracking_token 或等价受控公开访问凭证
- 输出：签收证明、交付回执或等价终态结果
exception_read
- 输入：tracking_token 或等价受控公开访问凭证
- 输出：异常原因、人工接管结果或下一步处理入口

3.2 `quote_submit` 字段冻结版

首个最小真实链路中，quote_submit 不应一次收集过多字段；推荐冻结为：

contact_name
contact_phone 或 contact_email
city
service_area_text
scenario_type
pickup_context
dropoff_context
preferred_time_window
payload_type
payload_weight_kg
notes
source_channel

固定原则：

首阶段只收最小必要字段，避免把企业完整建档、账单信息或组织信息塞进公开表单
至少要能支持后续生成 request_id
若需要更细字段，应在共享层或登录后流程继续补，而不是一次把公开表单做成“万能大表单”

3.2.1 `quote.html` 表单字段命名冻结版

首阶段公开表单的 HTML name 应与提交 payload key 保持一致，推荐固定为：

contact_name
contact_phone
contact_email
city
service_area_text
scenario_type
pickup_context
dropoff_context
preferred_time_window
payload_type
payload_weight_kg
notes
source_channel

固定原则：

公开表单不得混用 camelCase、中文 name、缩写 name 或临时别名
若字段出现在 DOM、前端状态对象、请求体中，默认应保持同名
source_channel 可以由前端无感填充，不要求用户手工输入
若未来需要字段升级，应追加新字段，不应静默改名覆盖旧字段

3.3 标识符冻结版

为避免 URL、状态页和证据包各写各的，首阶段标识符推荐固定为：

request_id
- 公开写入口提交成功后的最小受理标识
quote_id
- 报价已生成时的业务标识；若首阶段尚无独立报价对象，可暂不公开
order_id
- 进入履约主链后的内部或业务订单标识
tracking_token
- 用户侧公开读取 track / proof / exception 页时使用的不可枚举 token

固定原则：

页面 URL 优先使用 tracking_token
证据包中可以同时记录 request_id / quote_id / order_id / tracking_token 的映射关系
若当前实现还没有 tracking_token，则应把它视为首个真实链路的必补项，而不是继续裸露内部 id

3.3.1 公共 URL 与查询参数命名冻结版

为避免页面、测试脚本和接口层各写各的，首阶段公开读取入口推荐固定为：

路径优先：
- /track/<tracking_token>
- /proof/<tracking_token>
- /exception/<tracking_token>
查询参数仅作兼容回退时使用：
- /track?tracking_token=<tracking_token>
- /proof?tracking_token=<tracking_token>
- /exception?tracking_token=<tracking_token>

固定原则：

新实现优先使用路径参数，不优先使用查询参数
若必须支持查询参数，参数名统一为 tracking_token
不应再新增 token、id、order_id 之类的公开读参数别名
页面跳转、邮件文案、证据索引和自动化测试都应使用同一命名

3.3.2 前端字段与 payload 映射冻结版

首阶段前端字段映射规则固定为：

HTML name = 前端状态对象 key = 请求体 key
路径参数名与读取接口输入名统一使用 tracking_token
成功响应中的 request_id、tracking_token、next_step_url 不得随意换名

固定原则：

若确需做前后端字段转换，必须在 adapter 层显式实现并单独写明
未经文档更新，不得把 contact_name 改写成 name，或把 service_area_text 改写成 serviceArea
测试用例、日志字段、证据文件命名应复用同一组 contract 名称

3.4 `quote_submit` 校验规则冻结版

首阶段公开表单校验推荐固定为：

contact_name
- 必填
- 1-50 字符
contact_phone
- contact_phone 与 contact_email 至少二选一
contact_email
- contact_phone 与 contact_email 至少二选一
city
- 必填
service_area_text
- 必填
- 用于人工或系统判断服务覆盖
scenario_type
- 必填
- 必须来自受控枚举，不允许自由文本泛滥
pickup_context
- 必填
dropoff_context
- 必填
preferred_time_window
- 选填
payload_type
- 必填
payload_weight_kg
- 选填
- 若填写，必须为正数
notes
- 选填
- 应限制最大长度
source_channel
- 必填
- 用于来源归档，但不得增加用户额外负担

固定原则：

校验失败要返回可读错误，不允许静默失败
表单提交成功后必须返回 request_id
若尚未生成 tracking_token，也应明确告诉用户下一步如何进入 track

3.5 `track_read / proof_read / exception_read` 返回字段冻结版

首阶段公开读接口建议最小返回字段如下：

`track_read`

tracking_token
current_status
status_label
scenario_type
service_area_text
last_updated_at
next_step_hint

`proof_read`

tracking_token
final_status
fulfilled_at
proof_summary
proof_assets

`exception_read`

tracking_token
final_status
exception_code
exception_summary
manual_takeover
resolution_hint

提示公开读接口规则

公开读接口不返回跨租户敏感信息。
proof_assets 若包含附件，只返回受控访问地址或摘要，不暴露存储细节。
manual_takeover 必须是布尔或等价受控语义，不能写成模糊文案。

3.6 最小成功响应样例冻结版

首阶段接口可以很薄，但成功响应建议至少保持以下形状稳定：

`quote_submit` success

{
  "success": true,
  "request_id": "req_20260416_0001",
  "tracking_token": "trk_xxxxx",
  "next_step_url": "/track/trk_xxxxx",
  "message": "报价请求已受理"
}

`track_read` success

{
  "success": true,
  "tracking_token": "trk_xxxxx",
  "current_status": "scheduled",
  "status_label": "已排期",
  "scenario_type": "park_delivery",
  "service_area_text": "Shanghai Pudong",
  "last_updated_at": "2026-04-16T10:00:00Z",
  "next_step_hint": "等待设备出发"
}

`proof_read` success

{
  "success": true,
  "tracking_token": "trk_xxxxx",
  "final_status": "delivered",
  "fulfilled_at": "2026-04-16T11:20:00Z",
  "proof_summary": "已完成签收",
  "proof_assets": [
    {
      "type": "image",
      "label": "delivery-proof-1"
    }
  ]
}

`exception_read` success

{
  "success": true,
  "tracking_token": "trk_xxxxx",
  "final_status": "exception",
  "exception_code": "AREA_BLOCKED",
  "exception_summary": "配送路径受阻",
  "manual_takeover": true,
  "resolution_hint": "已转人工接管"
}

提示成功响应的稳定性要求

首阶段返回可精简，但键名不要频繁漂移。
tracking_token 一旦发出，后续所有公开读接口都应能复用。

3.7 最小失败响应样例冻结版

最小失败响应建议统一形状如下：

{
  "success": false,
  "error_code": "VALIDATION_ERROR",
  "error_message": "scenario_type is required",
  "field": "scenario_type"
}

提示失败响应的稳定性要求

失败时返回机器可读 error_code。
字段错误尽量回传 field，便于前端定位。
不要只返回空白页或静默失败；应有结构化错误可供处理。

3.8 错误码与前端文案映射冻结版

为避免接口错误与页面提示各写各的，首阶段建议固定如下映射：

VALIDATION_ERROR
- 前端文案：请完善必填信息后重试。
MISSING_SCENARIO_TYPE
- 前端文案：请选择场景类型。
MISSING_SERVICE_AREA
- 前端文案：请填写服务区域。
MISSING_CONTACT_CHANNEL
- 前端文案：请至少填写手机号或邮箱。
INVALID_TRACKING_TOKEN
- 前端文案：未找到对应的追踪记录。
RESULT_NOT_READY
- 前端文案：当前结果暂不可用，请稍后重试。

提示错误码与前端提示的协作方式

后端优先返回稳定 error_code。
前端优先按 error_code 映射提示文案，而不是硬编码猜测。
新增错误码时，同步更新文档与页面提示。

冻结原则：

首个真实链路至少要跑通上述四类中的 quote_submit + track_read + (proof_read 或 exception_read) 组合
若仍只有 mailto:、静态页或不可追踪表单，不得记为最小接口链已成立

4. 建议覆盖的最小状态语义

若当前站点需要展示订单状态，推荐最小状态集合如下：

created
scheduled
dispatching
delivering
delivered
exception
manual_takeover

补充规则：

manual_takeover 只能表示机器人主链上的人工异常接管，不得被解释为普通完成态
delivered 必须能关联签收证明、回执或等价交付结果
exception 必须能关联异常原因、升级动作或后续处理入口

5. 不在本站对外解释的字段

paid
activated
entitlement
workspace
key_issued
跨租户订单主事实
billing_status
quota
scoped_key_policy

这些字段以平台侧的正式契约与控制台的可见行为为准。

6. 鉴权与作用域原则

公开表单只收最小必要字段
开发者写订单、读订单、管理 Webhook、读取账单时，必须使用 Scoped Key 或等价的分权限凭证
订单写入、订单读取、Webhook 管理、账单读取不得共用万能 key
订单、签收证明与异常结果必须受 workspace / tenant 边界保护

7. 当前最小 contract 原则

公开写入口只收集最小必要信息
状态页只展示被授权公开展示的状态与证明
任何涉及账单、配额、Key、组织的动作，最终应跳转或收敛到 zhen-platform-console
任何需要智能判断、风控或升级执行的流程，应通过平台接入层进入执行服务（对外只按公开入口与白名单路由对接）
机器人主执行链与人工异常接管链必须可区分、可审计、可回写
在首个真实链路落地前，接口范围应收敛而不是发散，避免出现“文档里有很多接口名，但现实只剩邮箱入口”的假完整

8. 首阶段接口交付清单

8.1 前端必须对齐的接口动作

/quote
- 调用 quote_submit
/track/<tracking_token>
- 调用 track_read
/proof/<tracking_token>
- 调用 proof_read
/exception/<tracking_token>
- 调用 exception_read

8.2 后端最小交付要求

能生成 request_id
能生成或映射 tracking_token
能返回结构化成功响应
能返回结构化失败响应

8.3 首阶段禁止事项

不允许前端提交成功后只显示“我们会联系你”
不允许 track 页面只读静态样例
不允许 proof / exception 页面脱离真实标识独立存在
不允许接口成功但不返回 request_id 或等价可追踪标识

9. 字段与 DOM 钩子映射

为减少前后端、前端和自动化之间的错位，首阶段建议固定以下映射：

`quote_submit`

request_id
- DOM:
  - #request-id-value
  - [data-testid="request-id-value"]
validation error
- DOM:
  - #quote-validation-message
  - [data-testid="quote-validation-message"]

`track_read`

tracking_token
- DOM input:
  - #tracking-token-input
  - [data-testid="tracking-token-input"]
current_status
- DOM:
  - #track-current-status
  - [data-testid="track-current-status"]
last_updated_at
- DOM:
  - #track-last-updated-at
  - [data-testid="track-last-updated-at"]
next_step_hint
- DOM:
  - #track-next-step-hint
  - [data-testid="track-next-step-hint"]

`proof_read`

proof_summary
- DOM:
  - #proof-summary
  - [data-testid="proof-summary"]
proof_assets
- DOM:
  - #proof-assets
  - [data-testid="proof-assets"]

`exception_read`

exception_summary
- DOM:
  - #exception-summary
  - [data-testid="exception-summary"]
manual_takeover
- DOM:
  - #manual-takeover-status
  - [data-testid="manual-takeover-status"]
resolution_hint
- DOM:
  - #resolution-hint
  - [data-testid="resolution-hint"]

固定原则：

接口字段名、页面显示节点和自动化定位节点应保持一一对应
如果某字段当前暂未展示，不应提前占用错误的 DOM 钩子名

当前对外接口边界​

0.1 2026-04-17 Round 1 实际落地说明​

1. 当前接口家族应覆盖的业务对象​

2. 主链 contract 约束​

3. Repo-local 允许承接的接口语义​

3.1 首个最小真实链路接口冻结版​

3.2 quote_submit 字段冻结版​

3.2.1 quote.html 表单字段命名冻结版​

3.3 标识符冻结版​

3.3.1 公共 URL 与查询参数命名冻结版​

3.3.2 前端字段与 payload 映射冻结版​

3.4 quote_submit 校验规则冻结版​

3.5 track_read / proof_read / exception_read 返回字段冻结版​

track_read​

proof_read​

exception_read​

3.6 最小成功响应样例冻结版​

quote_submit success​

track_read success​

proof_read success​

exception_read success​

3.7 最小失败响应样例冻结版​

3.8 错误码与前端文案映射冻结版​

4. 建议覆盖的最小状态语义​

5. 不在本站对外解释的字段​

6. 鉴权与作用域原则​

7. 当前最小 contract 原则​

8. 首阶段接口交付清单​

8.1 前端必须对齐的接口动作​

8.2 后端最小交付要求​

8.3 首阶段禁止事项​

9. 字段与 DOM 钩子映射​

quote_submit​

track_read​

proof_read​

exception_read​

当前对外接口边界

0.1 2026-04-17 Round 1 实际落地说明

1. 当前接口家族应覆盖的业务对象

2. 主链 contract 约束

3. Repo-local 允许承接的接口语义

3.1 首个最小真实链路接口冻结版

3.2 `quote_submit` 字段冻结版

3.2.1 `quote.html` 表单字段命名冻结版

3.3 标识符冻结版

3.3.1 公共 URL 与查询参数命名冻结版

3.3.2 前端字段与 payload 映射冻结版

3.4 `quote_submit` 校验规则冻结版

3.5 `track_read / proof_read / exception_read` 返回字段冻结版

`track_read`

`proof_read`

`exception_read`

3.6 最小成功响应样例冻结版

`quote_submit` success

`track_read` success

`proof_read` success

`exception_read` success

3.7 最小失败响应样例冻结版

3.8 错误码与前端文案映射冻结版

4. 建议覆盖的最小状态语义

5. 不在本站对外解释的字段

6. 鉴权与作用域原则

7. 当前最小 contract 原则

8. 首阶段接口交付清单

8.1 前端必须对齐的接口动作

8.2 后端最小交付要求

8.3 首阶段禁止事项

9. 字段与 DOM 钩子映射

`quote_submit`

`track_read`

`proof_read`

`exception_read`