跳到主要内容

ZhenRobot 架构基线

Status: formal repo-local architecture baseline.

Upstream references:

  • /www/wwwroot/default/swam_architecture_zhenrobot.md
  • /www/wwwroot/default/swam_zhen_business_matrix.md
  • /www/wwwroot/default/swam_zhen_platform_unification_plan.md
  • /www/wwwroot/default/swam_test_standard_zhenrobot.md
  • /www/wwwroot/default/swam_zhen_unified_mainline_execution_adjudication.md

本文件定义 www.zhenrobot.com 的 repo-local 架构边界。若与上游冲突，以上游为准。

0.1 2026-04-17 门槛专项 Round 1 repo-local 补充​

为跨过 2026-04-17-zhenrobot-gate-run01 的首个前台门槛，repo-local 当前新增一条受控公开链路：

  • index.html / solution.html
    • 首要 CTA 进入 quote.html
  • quote.html
    • 生成 request_id
    • 同步生成 tracking_token
  • track.html?tracking_token=<tracking_token>
    • 读取最小状态对象
  • proof.html?tracking_token=<tracking_token> / exception.html?tracking_token=<tracking_token>
    • 读取终态结果摘要

当前实现说明：

  • 由于本仓上线形态仍是 Nginx 直接静态出页、未提供同域 /api/* repo-local 写入端点，Round 1 先使用同域浏览器本地持久层完成受控提交与读取
  • 该实现用于压实“不是 mailto:、不是占位页、能生成 request_id / tracking_token 并进入公开结果页”的最小前台门槛
  • 它不是共享层订单真相，不替代 zhen-platform-core / zhen-platform-console 对正式订单、账单、组织、权限与审计的解释权
  • 因此本仓当前状态应理解为：repo-local 受控证据链已建立，正式共享层订单主链仍待进一步接入

0.2 2026-04-17 主链联调 Round 1 边界冻结​

本轮主链联调不再把 gate 通过口径外推成 public live 履约闭环，而是固定解释为：

  • 当前 live
    • 线索收口
    • 报价受理
    • 方案咨询
    • 后续承接
  • 当前 non-live
    • 公开采购
    • 机器人履约
    • 签收证明
    • 异常结果 / 人工接管结果

执行约束：

  • track.html 当前只能解释为 报价受理 / 方案跟进 的公开读页
  • proof.html 与 exception.html 当前保留路径与边界说明，不得被当成 public live 交付真相
  • 只有当共享层订单、交付、签收与异常回流被真实证据再次证明后，才允许把上述 non-live 项上调

1. 架构目标​

把 www.zhenrobot.com 建成一个以机器人 / 设备主执行为主链的现实履约前台，而不是集团门户、第二控制台或泛化品牌站。

当前 repo-local 架构只需要服务以下链路：

公开流量入口 -> 聊天或报价承接 -> 下单/试点申请 -> 状态/签收证明 -> 文档/白皮书/下载 -> 统一平台 handoff

固定理解：

  • ZhenRobot 是 Robot 物理世界履约网络
  • 主边界按主执行主体判定，不按“是否发生在线下”判定
  • 机器人 / 设备主执行归 ZhenRobot
  • 人工异常接管归 ZhenRent 异常子链
  • 不把真人履约伪装成机器人主链

2. 六位一体前台结构​

repo-local 前台默认围绕以下六类能力组织：

  1. 网页聊天窗口端
    • 用于服务区域判断、试点咨询、报价承接、演示预约与白皮书分发
    • 它是承接入口，不是独立经营后台
  2. 业务展示网页端
    • 首页、场景页、服务区域页、定价页、安全 / SLA 说明页、案例页
  3. 订单与证明页面
    • 报价页、下单页、订单状态页、签收证明页、异常处理页
  4. 文档 / 白皮书 / 下载中心
    • 主站入口页 + 独立 docs 域名或等价文档站
    • 必须能公开访问产品介绍、订单接口、Webhook、协议标准与白皮书
  5. 聊天和文件传输 App
    • 供运营、商家、现场人员做异常接管、证据上传、签收回传与协同
    • 当前 repo-local 可以先定义边界，不要求第一阶段全部实现完
  6. API Key / 会员购买平台 handoff
    • 登录后订单、账单、Key、组织、工作区与权限动作统一收敛到 zhen-platform-console

解释：

  • 前台职责是解释和承接履约流程
  • 平台职责是解释统一身份、统一账单、统一 entitlement 与统一审计
  • 文档站、白皮书和下载中心属于正式前台的一部分，不是附属材料

3. 页面信息架构优先级​

当前应优先围绕以下页面家族组织：

  • 首页
  • 场景页
  • 服务区域 / 报价页
  • 下单页
  • 订单状态页
  • 签收证明页
  • 异常处理 / SLA 说明页
  • 文档中心 / 白皮书 / 协议与下载中心

若页面优先级冲突，默认排序如下：

报价/下单 -> 状态/证明 -> 服务区域与场景 -> 文档/白皮书 -> 品牌补充内容

3.1 首个最小真实链路页面 IA 冻结版​

在首份非示例真实 manifest 出现前，页面 IA 不得继续发散，先冻结为以下最小集合：

  1. landing / scenario
    • 推荐路由：/ 或 /scenarios/<slug>
    • 目的：说明服务区域、履约边界、适用场景和下一步入口
    • 必须存在明确 CTA，导向 quote
  2. quote
    • 推荐路由：/quote
    • 目的：收集最小必要信息并生成可追踪标识
    • 不得继续用 mailto: 代替正式提交入口
  3. track
    • 推荐路由：/track/<tracking_token> 或 /track?tracking_token=<tracking_token>
    • 目的：展示当前最小状态与阶段说明
  4. proof
    • 推荐路由：/proof/<tracking_token>
    • 目的：展示签收证明、交付回执或等价终态结果
  5. exception
    • 推荐路由：/exception/<tracking_token>
    • 目的：展示异常原因、人工接管结果或下一步处理入口

固定要求：

  • 首条真实主链至少需要 landing / scenario -> quote -> track -> (proof 或 exception) 跑通
  • proof 与 exception 可以二选一先落地，但不得两者都缺失
  • pricing、docs、whitepaper、download、console handoff 仍重要，但在最小真实链未建立前不应抢占最高优先级

3.2 URL 规则冻结版​

首个最小真实链路的 URL 规则推荐固定为：

  • 公共写入口使用稳定路径：
    • /quote
  • 公共读入口使用单一追踪标识：
    • /track/<tracking_token>
    • /proof/<tracking_token>
    • /exception/<tracking_token>

固定原则：

  • 公共页面不应直接暴露内部主键、租户主键或可枚举的订单序号
  • 用户侧公开查询推荐统一使用 tracking_token 或等价的不可枚举公开标识
  • 若内部仍使用 request_id / quote_id / order_id，应通过受控映射转成公开查询 token，而不是直接把内部 id 暴露到 URL
  • 若必须使用查询参数作为兼容模式，参数名也统一为 tracking_token

3.3 首个最小真实链路页面区块冻结版​

为避免页面实现时再次发散，首阶段页面区块推荐固定为：

landing / scenario​

  • Hero
    • 一句话说明服务边界
    • 主要 CTA：进入 quote
  • 服务区域说明
    • 当前覆盖城市 / 园区 / 楼宇类型
  • 适用场景
    • 2-4 个高频场景卡片
  • 机器人主执行边界
    • 什么能做
    • 什么不能做
    • 何时会升级 manual_takeover
  • SLA / 安全说明
    • 最小可信度表达
  • 次级入口
    • 文档 / 白皮书 / 协议

quote​

  • 表单区
    • 最小必要字段
  • 服务边界提醒
    • 明确“提交报价不等于自动接单”
  • 提交成功区
    • 返回 request_id
    • 明确下一步为 track

track​

  • 标识区
    • tracking_token
    • 当前阶段名
  • 状态时间线
    • 最小状态流转
  • 当前说明区
    • 当前状态含义
    • 下一步动作
  • 分流区
    • 若完成则进入 proof
    • 若异常则进入 exception

proof​

  • 终态摘要
    • delivered
    • 完成时间
  • 交付结果
    • 签收说明 / 回执摘要
  • 受控证明附件区
    • 图片、文本或等价证明摘要

exception​

  • 异常摘要
    • 异常类型
    • 异常发生时间
  • 人工接管结果
    • 是否进入 manual_takeover
  • 下一步处理
    • 重试 / 联系 / 升级入口

固定原则：

  • 每个页面都要先解释当前阶段，再给动作，不允许只堆品牌内容
  • track / proof / exception 必须围绕同一 tracking_token 组织
  • 若实现预算有限，先把页面做薄，但区块顺序不要乱

3.4 首个最小真实链路页面验收冻结版​

为避免“页面已做完”但实际上不可用，首阶段每页至少满足以下通过条件：

landing / scenario​

  • 用户在首屏 5 秒内能看懂：
    • 服务边界
    • 适用场景
    • 下一步入口
  • 页面存在明确主 CTA 指向 /quote
  • 页面不把品牌介绍压过履约入口

quote​

  • 用户能完成表单提交
  • 提交失败时能看到可读错误
  • 提交成功后能看到 request_id
  • 提交成功后知道下一步如何进入 track

track​

  • 使用同一 tracking_token 可以打开页面
  • 页面能显示当前状态
  • 页面能显示最近更新时间
  • 页面能明确告诉用户下一步动作或结果入口

proof​

  • 终态为 delivered
  • 页面能展示至少一个可理解的交付结果摘要
  • 若有证明附件，页面能展示受控摘要或访问说明

exception​

  • 页面能展示异常原因或异常摘要
  • 页面能说明是否进入 manual_takeover
  • 页面能提供下一步处理说明

固定原则：

  • 任一页面若只能展示静态文案而不能绑定真实标识或真实状态，不得记为通过
  • 首个最小真实链路的页面验收应优先于视觉扩展和品牌延展

3.5 首个最小真实链路逐页文案冻结版​

为避免设计稿、静态页和实现页出现三套话术，首阶段逐页文案建议固定如下：

landing / scenario​

  • 主标题：
    • 门到门机器人履约
  • 副标题：
    • 适用于园区、楼宇与受控场景的机器人配送与现实交付。
  • 主按钮：
    • 申请报价
  • 次按钮：
    • 查看履约说明

quote​

  • 页面标题：
    • 申请履约报价
  • 说明文案：
    • 提交场景与服务区域信息后，我们会生成可追踪的受理标识。
  • 提交按钮：
    • 提交报价申请
  • 成功标题：
    • 报价请求已受理
  • 成功提示：
    • 请保存 request_id，并使用追踪入口查看后续状态。

track​

  • 页面标题：
    • 履约状态查询
  • 输入标签：
    • 追踪标识
  • 空状态：
    • 请输入有效的追踪标识以查看当前状态。
  • 结果区标题：
    • 当前履约状态

proof​

  • 页面标题：
    • 交付结果与签收证明
  • 结果标题：
    • 交付已完成
  • 结果说明：
    • 以下为本次履约的最小结果摘要与证明信息。

exception​

  • 页面标题：
    • 异常与人工接管结果
  • 结果标题：
    • 本次履约进入异常处理
  • 结果说明：
    • 以下为异常原因、人工接管状态与后续处理说明。

4. 主链路与升级链​

当前正式主链应按以下方式理解：

媒体 / 官网 / 文档站 -> 报价或下单 -> zhen-platform-core -> zhen-brain-core -> robot_execute / manual_takeover -> proof / exception -> console handoff

其中：

  • robot_execute
    • 机器人 / 设备主执行的配送、搬运、巡检、交付
  • manual_takeover
    • 机器人主链上的人工异常接管，异常子链归 ZhenRent
  • console handoff
    • 登录后订单、账单、Key、工作区、组织与审计统一在 zhen-platform-console 收口

4.1 首个最小真实链路状态说明​

为避免页面先做出来但语义不一致，首个最小真实链路推荐只展示以下最小状态：

  • created
  • scheduled
  • delivering
  • delivered
  • exception
  • manual_takeover

解释：

  • manual_takeover 不是普通完成态，而是机器人主链上的异常升级
  • delivered 必须能关联 proof
  • exception 与 manual_takeover 至少要有一个可进入结果页，而不是只停留在状态标签

4.2 track / proof / exception 页面展示字段冻结版​

为保证前台、接口和证据包一致，首阶段页面展示字段推荐固定为：

track​

  • tracking_token
  • current_status
  • status_label
  • scenario_type
  • service_area_text
  • last_updated_at
  • next_step_hint

proof​

  • tracking_token
  • final_status
  • fulfilled_at
  • proof_summary
  • proof_asset_count
  • proof_access_note

exception​

  • tracking_token
  • final_status
  • exception_code
  • exception_summary
  • manual_takeover
  • resolution_hint

固定原则：

  • 前台只展示最小必要字段，不在站点里解释账单、租户、配额和 entitlement 真相
  • 若当前真实数据还不足，可先用字段壳驱动实现，但不得伪装成真实履约结果

4.3 实现顺序冻结版​

若工程资源有限，推荐实现顺序固定为：

  1. quote
  2. track
  3. proof
  4. exception
  5. landing / scenario 的强化说明与白皮书 / 文档承接

顺序原因：

  • quote 决定是否能生成首个真实标识
  • track 决定是否能把标识变成可读取状态
  • proof / exception 决定是否能形成终态结果页
  • 只有这三者先成立，landing / scenario 的转化价值才真正闭环

5. 共享层边界​

www.zhenrobot.com 负责​

  • 公开获客页面
  • 报价、下单前说明和公开表单承接
  • 订单状态与交付证明可见性
  • 现实履约能力、边界和信任表达

zhen-platform-core 负责​

  • 身份、组织、账单、订单主事实、entitlement、Key、事件与推荐

zhen-platform-console 负责​

  • 登录后订单、账单、Key、工作区、企业管理与后续控制面动作

zhen-brain-core 负责​

  • 执行路由、可执行性判断、workflow、risk、eval、memory 与 sandbox

6. 数据边界​

本站可见但不应成为最终真相的数据​

  • 订单状态展示
  • 签收证明展示
  • 异常处理展示
  • 报价输入与公开咨询信息
  • 公开文档下载、白皮书下载与来源页信息

需由共享层解释的数据​

  • 订单最终状态主事实
  • 账单与支付主事实
  • entitlement 与 quota
  • API Key 生命周期
  • 租户、组织与工作区边界

7. 与 ZhenContract / ZhenRent / ZhenRobot 的边界​

  • ZhenContract
    • 交付数字结果、协议状态、结算状态与审计记录
  • ZhenRent
    • 交付以人为执行主体的判断结果、人工操作结果、现场服务结果与证据回传
  • ZhenRobot
    • 交付以机器人 / 设备为执行主体的配送结果、搬运 / 巡检 / 交付结果、签收证明与现场状态回写

固定裁决：

  • 线下发生但以人为主执行的任务，不归 ZhenRobot 主链
  • 机器人主执行、人工补位的订单，主链仍归 ZhenRobot，异常子链归 ZhenRent

8. 关键禁止事项​

  • 不把本站做成第二控制台
  • 不让前台长期解释订单、账单、entitlement 真相
  • 不在正式生产路径里前台直连 zhen-brain-core
  • 不把历史 HTML 结构误当成当前长期架构真相
  • 不把文档站、白皮书、下载中心当成可有可无的营销附件

9. 首个最小真实链路实现任务拆分​

为便于工程直接排期，首阶段推荐拆成以下工作包。

9.1 WP1-Quote​

目标：

  • 交付 /quote
  • 完成最小字段收集、校验、成功 / 失败响应
  • 返回 request_id

通过条件：

  • 页面可访问
  • 表单可提交
  • 成功后返回 request_id
  • 失败时返回结构化错误

9.2 WP2-Track​

目标：

  • 交付 /track/<tracking_token>
  • 能用同一标识读到最小状态

通过条件：

  • tracking_token 可打开页面
  • 页面显示 current_status
  • 页面显示 last_updated_at
  • 页面显示 next_step_hint

9.3 WP3-Proof​

目标：

  • 交付 /proof/<tracking_token>
  • 为 delivered 提供最小结果页

通过条件：

  • 页面可打开
  • 页面显示 final_status=delivered
  • 页面显示 proof_summary

9.4 WP4-Exception​

目标：

  • 交付 /exception/<tracking_token>
  • 为异常或人工接管提供终态页

通过条件：

  • 页面可打开
  • 页面显示 exception_summary
  • 页面显示 manual_takeover
  • 页面显示 resolution_hint

9.5 WP5-Landing​

目标：

  • 强化首页或场景页
  • 把用户稳定导向 /quote

通过条件：

  • Hero 有明确 CTA
  • 服务边界清晰
  • 场景与 SLA 说明清晰
  • 不再以 mailto: 作为主提交链

9.6 WP6-Evidence​

目标：

  • 按 manifest 模板收集桌面端、移动端、状态页和终态页证据

通过条件：

  • 有 request_id
  • 有 tracking_token
  • 有 desktop-* 与 mobile-* 证据
  • 有 proof 或 exception 终态证据

9.7 总体完工定义​

只有当以下条件同时成立，才可记为首个最小真实链路完成：

  1. WP1 完成
  2. WP2 完成
  3. WP3 或 WP4 至少一个完成
  4. WP6 完成

若缺少上述任一项，不得对外宣称“现实履约前台已跑通”。

10. 当前静态站文件映射建议​

考虑到当前仓库仍以静态站为主，首阶段建议按以下文件映射推进：

  • index.html
    • 作为默认 landing
  • solution.html
    • 作为可选 scenario 强化页
  • quote.html
    • 新建，承接 WP1-Quote
  • track.html
    • 新建，承接 WP2-Track
  • proof.html
    • 新建，承接 WP3-Proof
  • exception.html
    • 新建，承接 WP4-Exception
  • api.html
    • 保留开发者 / 接入说明语义，不替代 quote / track / proof / exception

固定原则：

  • quote / track / proof / exception 应成为独立页面，而不是继续寄生在历史品牌页里
  • 若 index.html 与 solution.html 同时保留，只允许一个承担默认主入口，避免双首页竞争
  • 若后续切换到新前端框架，路由语义保持不变，文件名可以变，但 ownership 不应漂移

11. 首阶段 HTML 骨架顺序​

为避免工程在不同页面上使用不同结构套路，首阶段推荐固定以下骨架顺序：

  • index.html
    • hero -> service-area-summary -> scenario-cards -> fulfillment-boundary -> sla-summary -> docs-and-whitepaper
  • quote.html
    • quote-intro -> quote-form -> quote-validation -> quote-success
  • track.html
    • track-intro -> track-token-input -> track-status-card -> track-timeline -> track-next-step
  • proof.html
    • proof-intro -> proof-result-card -> proof-summary -> proof-assets
  • exception.html
    • exception-intro -> exception-result-card -> manual-takeover-status -> resolution-hint

固定原则：

  • 先功能，后品牌
  • 先结果，后补充说明
  • 区块命名与页面职责应保持一一对应，避免一个区块同时承载多个阶段语义