# ADR-0015: 平台前端底座 (引擎前端 console + godoc 开发者门户) + Claude Design 设计系统采纳 + 物流对账作首个真实工作流 (承运商无关), 两线"工作流验证底座"纪律

- Status: **Accepted (PM 2026-06-05 确认形状, 实现中)** -- 本文是把 2026-06-05 对话里拍下的方向写成一页; PM "可以" 确认形状并授权自主做前端 (线 1 底座).
- 关联: ADR-0002 (REST 业务 / gRPC 观测 bifurcation, 前端走 REST/SSE 契约) · ADR-0013 (billcost overlay) · ADR-0014 (统一成本格式 + overlay 跨层核对).
- 姊妹 (待落): **ADR-0016 物流对账引擎** (三方审计模型 + 计费合并 + WMS 运单查询 + 承运商工厂 + 坑规则集 + 产出形态) -- 等 PM 的"坑清单"列完再落. 本 ADR 只定**底座 + 对账作为工作流如何骑在底座上**, 不定对账的内部算法.

---

## 1. 背景 / Context

### 1.1 billcost 工作流前端已累积成团 (PM 2026-06-05 提的问题 1)

billcost 这条工作流的前端是**累积长出来的**: 上传表单 / 5 下拉承运商配置 / base 价格表 / overlay 临时加价面板 / 视觉审核卡 / 审核纠错环 / `/analysis` 跨层覆盖视图, 每加一个能力就往同一张 `index.html` / `main-screen.jsx` 上焊自己的配置和显示, **没有统一外壳**. 配置与显示纠缠成团, 继续往上堆 (对账是目前最大的一块新面) 必然更乱.

诊断: **乱的根因是没分层** -- 引擎配置 (用哪个 provider/model) / 应用配置 (承运商/数据库/流程) / 运行时显示 全焊在同一张 app 级 HTML 上.

### 1.2 platform 核心是智能体引擎, 引擎需要它自己的前端

PM 指出: platform 的核心是智能体引擎. 引擎本身需要一个**前端** -- 配置面 (provider/model/tools) + 操作面 (看 run / 介入) + **开发者文档面 (godoc API + 指南)**. 具体应用 (对账等) 从引擎配好的资源里选, 按工厂模式装配不同流程. 这套前端是所有 vertical 共用的可复用层, 不该是某个应用的附属.

### 1.3 Claude Design 交付了 `flyto-design-system` bundle

设计师 (Claude Design, claude.ai/design) 产出一个 handoff bundle, 经 chat1/chat2 多轮迭代. 评估 (读 bundle + 两段 chat 全文):

- **强, 可直接采纳**: (a) 设计系统底座 (`colors_and_type.css` + `components.css` 的 `.fc-` "Control Surface" 组件库) -- 深色优先 + 暖中性 + 发丝边 + 小圆角 + **两层品牌一键换肤** (`data-brand` 网络橙 ↔ 云仓青) + 把 logo 几何做成系统 (45° 切角 / 角标 / 旋转方块 LED). (b) **字体策略** Geist (拉丁) + 系统中文 (苹方, 思源回退) + 光学字号 -- 即 PM 要的 "claude 中英都漂亮"; chat1 实证设计师是被 PM 怼 "小字很丑" 后才 landing 这个的. (c) **Atlas 三角色控制台** (`agent-views/`): 委托人 / 开发者 (React Flow 编排图) / 运维 (集群健康 + 介入队列) -- 恰好咬合本 ADR 的分层, 委托人视角 = 业务用户面.
- **已被 PM 否的死路, 不复活**: chat2 的游戏引擎宇宙 / 作战室 (真地球/银河塞进 2D canvas) -- PM 连否三次 ("太恶心 / 像 20 年前 / 没代入感"). 没进 bundle 头牌 (头牌是干净的 Atlas, 设计师后来 pivot 回来了). 2D canvas 假装 3D 是错的技术路.
- **缺的最关键一块**: 没有**对账 hero 屏** (三方审计省钱看板). 它拿到的 brief 是 "做飞驼设计系统 + 游戏 UI", 不是 "设计对账看板". 故它给了**语言** (设计系统) 和**外壳** (Atlas), 没给对账那块. PM 拍板: **hero 屏 later 做** (本 ADR 不做).

### 1.4 物流对账 = 业务原点, 作首个真实工作流

对账是整个物流 vertical 的业务原点 (报价抽取一直为它服务). PM 要它作**第一个真实工作流**搭在底座上, 且**注意通用性 -- 未来不止圆通一个承运商**.

---

## 2. 决策 / Decision

### 2.0 confirmed (设计前提, 不 relitigate)

1. **不拆仓, 拆契约** (ADR 对话 2026-06-05): 乱不是 "同一个仓" 造成的, 是没分层没契约. 拆仓 = 两个仓里一团乱 (更糟) + 跨仓改接口要协调两边. 解耦来自**契约干净**, 不来自仓库边界. 拆仓的触发器 (独立团队 own / SDK 边界稳 / 独立产品打包) 现都未发生, 故在仓内拆三层契约, 触发器来了再拆是便宜的机械动作 (见 §6).
2. **采纳 Claude Design 设计系统**作底座皮 (§2.5 定边界).
3. **两条线** (§2.2 / §2.3): 线 1 平台底座 (引擎前端) + 线 2 物流对账 (首个工作流).
4. **承运商无关** (§2.3): 通用性在**形状** (工厂缝), 不在预先实现多家.

### 2.1 build on 既有 `frontend/` (ADR-0009), 不新建模块 (2026-06-05 实勘修正)

实勘: 仓内**已有 `frontend/`** (ADR-0009 拍的 P2 前端, 已 commit), 栈就是 Vite + React + TS + **Tailwind + shadcn** + R3F + React Flow + framer-motion + Zustand; 5 页面骨架 (workspace / flow / runtime / settings / login) + 双层 preset (worker / decision / sales-walkthrough) + REST/SSE client 已就位, 各页面是有意的 stub. `/runtime` 注释明写它是 "Claude Design 协作流第一个 prototype 目标". 故:

- **build on `frontend/`, 不新建模块** (本 ADR 初稿 "新建 like tui/" 作废 -- 当时没勘到既有 frontend/).
- **保留 shadcn + Tailwind** (ADR-0009 已 PM 拍板, 铁律, 不推翻; 初稿 "不套 shadcn 用 `.fc-` 当皮" 作废 -- 那跟 ADR-0009 正面冲突).
- **设计系统采纳 = 把 Claude Design 的视觉语言映进既有 shadcn/Tailwind token 系统**: 品牌色 (科技灰 navy `#485068` + 未来橙 orange `#F18200`) 替掉现有泛蓝 shadcn 主题; Geist + 系统中文 (苹方) 字体策略; 几何 (45° 切角 / 角标 / LED) 做成 Tailwind utility/组件. **不**把 bundle 的裸 `.fc-` CSS 直接塞进来 (绕过 shadcn 违 ADR-0009).
- **两层 `data-brand` (网络/云仓) 加成新 accent 轴**, 与既有 worker/decision preset + dark/light **正交可组合** (preset = 信息密度/动效强度; theme = 明暗; data-brand = 品牌accent).
- 后端仍是 `platform/common` (Go), 对前端只暴露**稳定 REST/SSE** (ADR-0002 bifurcation). billcost SSE 端点已在 (`/api/v1/billcost/dispatch/{id}/answer`).

### 2.2 线 1 = 平台底座 = 引擎的完整前端

底座 = 操作引擎的外壳 + 引擎的文档, 是跨 vertical 复用层:

- **配置面**: providers / models / tools 在引擎级配好 (key / 启用哪些), 应用从中选.
- **操作面**: Atlas 式运行控制台 (委托人 / 开发者 / 运维三视角), 看 run / 介入队列 / 编排图.
- **文档面 = godoc 开发者门户**: 引擎开发者门户 = 使用指南 + **自动从 godoc 生成的 Go API 参考** (PM 2026-06-05 确认 "当然要包括 godoc API"), 用飞驼设计语言渲染. bundle 里的 `ui_kits/website/engine.html` 是种子.

### 2.3 线 2 = 物流对账 = 首个真实工作流, 承运商无关

- 对账骑在底座上, 是第一个证明底座可用的真实工作流.
- **承运商无关工厂**: 账单列映射 / 对账规则集 / WMS 口径做成可插拔; 审计骨架 (多源数据 -> 逐规则 verdict) 中性. **圆通是第一个实例, 装在工厂缝后面**.
- **不预造第二家承运商**: 通用性兑现在 "缝留对了", 不在 "先写好 N 家". 第二家来时填缝便宜 (见 §6 触发器).
- 对账的**内部算法** (三方审计 = 账单实收 vs WMS 权威口径 + 报价算的应收 / 计费合并 / 时间基准 join / 坑规则集 / 产出形态) **在 ADR-0016 定**, 本 ADR 不展开.

### 2.4 "工作流验证底座" 纪律 (反向思维, 防空抽象)

两条线**不是平行的, 是线 2 验证线 1**. 底座若脱开真实工作流空抽象, 极可能抽错 (rule-of-two 陷阱). 故纪律:

- **底座只长到对账用得着的程度**. 不堆 "没有任何工作流在用" 的配置项 / 视图.
- **对账是底座的试金石** -- 底座的每个能力 (某个配置项 / 某个控制台视图 / 某条 REST 端点) 必须有对账或 godoc 门户在真用, 否则不建.
- 同 §2.3 对账自己的通用性纪律 (缝留对, 别预造).

### 2.5 设计系统采纳边界 (取语言, 不照搬代码)

- **采纳**: design token (`colors_and_type.css` 的色/字/间距/圆角/阴影变量) + `.fc-` 组件的**视觉语言** + 字体策略 (Geist + 系统中文 + 光学字号) + 两层 `data-brand` 换肤机制.
- **不照搬**: bundle 的 htm/preact 模板代码 (`html\`\`` 字面量) -- bundle README 自己说 "recreate in whatever tech makes sense (React)". 取视觉, 在 React 重建.
- **godoc 门户**用 `engine.html` 当视觉种子.
- **Atlas 三视角**作引擎控制台的参考实现 (委托人视角直接服务对账等业务用户).

### 2.6 游戏引擎宇宙 = 否决 (不复活)

chat2 的 2D canvas 宇宙/作战室 PM 已连否. 真要沉浸式 3D 是 R3F + 真实资源 (已拍的 P2 栈), **单独立项**, 不在本 ADR, 也不捡 2D canvas 那摊.

---

## 3. 替代方案 / Alternatives

- **拆出独立仓库**: 否. 拆契约即得解耦; 拆仓在触发器未到时只增跨仓协调税 (§2.0).
- **裸 shadcn/ui 起步**: 否. 设计系统已是带换肤的飞驼品牌组件库; 裸 shadcn 冲淡那套切角/角标几何, 且丢掉已 landing 的字体策略. 改为采纳设计系统当皮, shadcn/Radix 仅供交互原语 (§2.1).
- **底座先抽象, 之后再接工作流**: 否. rule-of-two 空抽象风险, 极可能抽错. 改为对账当试金石 (§2.4).
- **对账预先支持多承运商**: 否. 通用性在形状 (工厂缝) 不在预实现; 圆通先做扎实 (§2.3).
- **复活游戏引擎宇宙**: 否. PM 连否 + 2D canvas 假 3D 是错路; 真 3D 另立项 (§2.6).
- **hero 屏现在做**: 否 (PM 拍 later). 先底座 + 对账工作流跑通.

---

## 4. 影响 / Consequences

### 4.1 正面

- 治 "前端乱" (问题 1): 引擎配置 / 应用配置 / 显示三面用契约分开, 不再焊一张 HTML.
- 引擎前端成形: 可 dogfood / 可作销售门面 / godoc 门户让 SDK 消费者上手.
- 对账有**品牌化的家**, 不是又一个焊上去的页.
- 设计系统跨 vertical 复用 (网络 ↔ 云仓一键换肤), 对齐 project_strategy 领域无关定位.

### 4.2 风险 / 边界 (诚实记)

- **设计系统移植有工作量**: bundle 是 htm/preact + `.fc-` CSS, 视觉语言移进 React 要重建 (非零成本).
- **godoc 自动渲染需选方案** (pkgsite 风格自渲 / 第三方), 留 ADR-0016 或实现时定.
- **对账 hero 屏 deferred**: 销售门面那块暂不做 (PM 拍 later); 现交付到 "对账工作流跑通 + 在底座里有视图" 为止.
- **对账坑规则集在 ADR-0016**: 本 ADR 不含对账内部算法; 没有它对账只是空壳工作流.
- **WMS 运单查询是 ADR-0016 的 load-bearing 前置**: 现 `wms` 包只接字典查询 (承运商/月结账号/标准成本); 按运单号查 省/揽收/签收/重量/退件 的接口是 net-new, 数据在 ADS replica 里 (PM 业务确认), 待 ADR-0016 核实表/字段.

### 4.3 trap (实现时显式 flag)

- **别把底座抽象到没有工作流在用** (§2.4 试金石纪律) -- 每个底座能力要有对账或 godoc 在真用.
- **别照搬 bundle 的 htm/preact 代码** -- 取视觉语言在 React 重建 (§2.5).
- **对账别 hardcode 圆通** -- 走工厂缝 (§2.3); 但也别预造第二家.

---

## 5. 验证 / Validation

- **底座**: 引擎前端三视角 (委托人/开发者/运维) 渲染 + providers/models/tools 配置回环 + godoc 门户 (自动 API + 指南) 渲染 + 设计系统换肤 (网络 ↔ 云仓 一属性切换) 端到端.
- **对账作工作流**: 骑底座跑通首个工作流 (上传 -> 解析 -> 对账 -> 产出, 内部算法见 ADR-0016); 承运商工厂缝可插拔单测 (换一个 fake 承运商 strategy 不改骨架).
- **契约**: 前端只经 `platform/common` REST/SSE 消费, 不直连 DB; 后端契约改动前后端同 PR.
- 全量 `go test -race` (后端) + 前端构建 + 真 ytosample 端到端.

## 6. 触发重新评估的条件 / Trigger conditions

- **第二家承运商来** -> 兑现 §2.3 工厂缝 (填新 strategy, 不改骨架).
- **拆仓触发器任一发生** -> 重估 §2.0: (a) 独立团队/人 own 前端 (如 Claude Design 设计师-to-code 闭环接管); (b) 引擎 Go SDK 边界稳 (apps 经 SDK 消费, 不再 go.mod replace); (c) 要当独立产品打包卖.
- **要做对账 hero 屏** -> 把它当真 brief 喂 Claude Design (真账单 + 真坑), 单独推进.
- **要沉浸式 3D** -> R3F + 真实资源单独立项 (§2.6), 不复活 2D canvas.

## 7. 工程量 / Engineering footprint

- **设计系统落地 (build on 既有 `frontend/`)**: 把品牌 token (navy/orange) + Geist/系统中文字体策略 + 几何映进既有 shadcn/Tailwind token 系统 (`index.css` + `tailwind.config.ts`), 替掉泛蓝主题; 加 `data-brand` 轴. 不新建模块.
- **引擎前端三面**: 配置 (providers/models/tools) + 控制台 (Atlas 三视角) + godoc 门户 (自动 API + 指南).
- **后端 REST/SSE**: `platform/common` 补底座所需端点 (引擎配置读写 / run 流 / godoc 数据).
- **对账工作流接入**: 对账视图骑底座 (内部算法 ADR-0016); 承运商工厂缝.
- **不做**: 拆仓 / 预造多承运商 / hero 屏 / 游戏引擎 3D / 对账内部算法 (ADR-0016) / 坑规则集 (ADR-0016).

## 8. 修订记录 / Revision history

- 2026-06-05 v1 (Proposed, 草稿待 PM 确认形状): 经 2026-06-05 多轮对话确认 -- (1) 不拆仓拆契约; (2) 采纳 Claude Design 设计系统底座 (评估了 bundle + 两段 chat: 强在设计系统+字体策略+Atlas 三视角, 否决游戏引擎宇宙, 缺对账 hero 屏 -> later); (3) 两线 (平台底座引擎前端含 godoc API + 物流对账首工作流); (4) 工作流验证底座纪律 (对账当试金石防空抽象); (5) 承运商无关工厂 (圆通首实例不预造第二家). 对账内部算法 + 坑规则集留 ADR-0016 (待 PM 坑清单).
- 2026-06-05 v2 (Accepted, 实勘修正 + 授权实现): PM "可以" 确认形状 + 授权自主做前端. **实勘发现既有 `frontend/` (ADR-0009)** -- 修正 §2.1/§7: build on 既有 frontend/ 不新建模块; **保留 shadcn + Tailwind (ADR-0009 铁律)**, 设计系统采纳改为 "把视觉语言映进既有 shadcn/Tailwind token 系统" 而非塞裸 `.fc-` CSS; data-brand 与既有 worker/decision preset 正交可组合. 初稿 "新建模块 + 不套 shadcn" 两处与 ADR-0009 冲突, 已作废.
- 2026-06-05 v3 (Accepted, **采纳全量设计系统 + 推翻 v2 的"不塞 .fc-"**): PM 强烈反馈 v2 的做法**不尊重设计师的品牌资产** ("设计师做了那么多组件你来了个啥" / "麻烦你赶紧做, 忠于设计"). 修正: **(1)** 设计师的伪冲突澄清 -- 他的 bundle 本就是 HTML/CSS 原型让 coding agent 在目标栈 recreate (他不交 shadcn React); ADR-0009 选 shadcn 是为其性质 (可改到极致 + Radix 行为 + 非 MUI/Ant 锁主题), 而 `.fc-` 同样具备且**就是飞驼真品牌**, 故无真冲突. **(2)** **采纳设计师全量 `.fc-` 组件库** (`flyto-components.css` + `-ext.css` + `agent.css` 引进 `src/styles/`, index.css 全局 import), 退役我自撸的 `components/flyto/kit.tsx`. **(3) shadcn 降级**: 视觉纯用 `.fc-`, Radix 仅在交互件 (下拉/弹窗) 真需键盘无障碍时上 (PM "radix 有助于代码我愿意"). **(4)** 首页改为**忠实 recreate 设计师的 Agent 引擎站** (`engine.html`: Nav/Hero/FeatureGrid/ProviderStrip/Tools/TeamsBanner/InstallCTA/Footer), 网络母品牌, 全幅在 Layout 外. **(5)** 5 个操作界面 (工作台/控制台/对账/文档/设置) 全部 reskin 到 `.fc-`; 设置对齐 P2 §九 八大模块. **教训记**: 应先读 P2 设计文档 (`docs/p2-ui-design/...`) + 设计师全量交付再动手, 而非凭 token 层自撸 -- v1/v2 跳过了这步.