Metapi 前端架构约定

这份约定把管理端的技术入口收敛成一条可检查的路径，作为新增页面和重构时的维护者参考。它不改变现有页面能力、路由、协议或主题。

Canonical stack

pages/** → pages/<domain>/** → components/ui/** → Radix behavior primitives
                                      └──────────→ index.css design tokens/classes

生产页面使用 React 18 + TypeScript + Vite，并通过 src/web/api.ts 发起认证 HTTP/SSE 请求。
src/web/components/ui/** 是项目拥有的 UI 边界。只有这一层可以直接 import @radix-ui/*（以及其他交互原语库）；页面和领域组件只接收 Metapi 的语义 props。
CenteredModal、MobileDrawer、ModernSelect 是兼容 facade。新代码优先使用 components/ui 的 wrapper；旧导出在迁移完成前继续有效。
浏览器 renderer 的 Radix modal overlay 已负责 RemoveScroll；components/ui 只在 SSR/test/不完整 DOM fallback 使用引用计数 body lock，避免多个 owner 在卸载顺序不同步时留下页面滚动锁。
视觉来源是 src/web/index.css 的 CSS variables 和语义 class。不要为单个页面引入 CSS module、styled-components 或另一套 UI framework；复用布局时先扩展已有 class/primitive。
@import "tailwindcss" 只允许出现在 src/web/index.css。当前它作为 Vite 的单一 utility/preflight 入口保留；页面不得再创建第二个样式 runtime。

异步与状态边界

src/web/api.ts 负责认证、超时、错误提取、取消和 SSE 解析；页面只拥有自己的 server state、URL intent 和领域 mutation。
请求 effect 必须在 target 改变和卸载时 abort 或 stale-guard，并清理 timer、 listener、animation frame、portal 和 body-scroll lock。
loading、empty、error、cancel 状态使用共享窄职责 primitive 或既有语义 class；用户可见文本通过 t()/tr() 翻译。

维护检查

提交前运行：

npm run typecheck:web
npm run typecheck:web:test
npm run repo:drift-check
npm run build:web
git diff --check

repo:drift-check 会报告以下架构漂移：

页面/领域组件直接 import 第三方 UI 原语；
顶层 page 互相 import；以及
proxy-core、transformer 和整包响应读取等既有边界债务。

新的 wrapper 只能放入 src/web/components/ui/**，不能通过新增 allowlist 隐藏违规。若确有浏览器能力例外，应在拥有该能力的 helper 中记录原因、测试和后续迁移边界。

迁移策略

优先迁移低耦合的 modal/drawer、异步按钮和反馈状态，再处理大型领域页面。每个切片都应保留旧 props/class、桌面与移动断点、键盘行为和翻译，并以聚焦测试证明 focus return、Escape/backdrop、body-scroll 多实例清理和 stale 请求语义没有回归。不要为了“统一”机械替换所有历史 <button> 或业务卡片。

当前交付证据（2026-08-31）

本轮简化已经把以下高频路径接入同一套生命周期 owner：

Dashboard、ProxyLogs、Models 和 SearchModal 使用 src/web/components/useAsyncResource.ts；该 helper 负责 AbortController、 stale identity、single-flight、silent refresh、timeout/abort 分类和卸载清理。
Dashboard 的跨域测速集中在 pages/helpers/siteSpeedProbe.ts，固定 worker pool（目标并发不超过 4）、逐站 timeout 和 done/timeout/error/aborted 结果。这是有意保留的 browser-only fetch(..., { mode: 'no-cors' }) 能力，不属于认证管理 API。
ModelTester 的 SSE delta/raw event 通过 24ms batcher 提交；停止、完成、 abort 和卸载都会先 flush，再取消 reader/controller。批处理只改变 React commit 频率，不改变 cumulative delta 去重或 raw event 顺序。
TokensPanel 位于 pages/tokens/，pages/Tokens.tsx 只保留 legacy route redirect 和兼容导出；页面之间不再通过顶层 page 互引。

验证记录（本地 Node v22.23.1，包声明 Node >=25.0.0）：

npm run build:web：2614 modules transformed；CSS 136.83 kB（gzip 22.01 kB），构建通过；
npm test -- --run src/web：157 个文件、539 个测试通过，2 个跳过；
npm test -- --run src/server：301 个文件、2,155 个测试通过，6 个跳过；
npm test：480 个文件、2,777 个测试通过，1 个文件/8 个测试跳过；
npm run typecheck、npm run build、npm run repo:drift-check 和 git diff --check 通过；drift 结果为 0 violations / 0 tracked debt；
build 仍显示 vchart-vendor 约 2.15 MB（gzip 约 587 kB）的 large-chunk warning。当前没有真实浏览器 below-fold/network trace 来证明拆分收益，故把它记录为后续独立性能任务，不宣称本轮已经解决。

服务端对应边界

管理 route 只做输入解析、endpoint 选择和 HTTP 响应映射；账号验证诊断由 src/server/services/accountVerificationDiagnostics.ts 单一拥有， downstreamPolicy 与 multipart helper 由 src/server/services/ 拥有，旧 routes/proxy/* 文件只保留兼容 re-export。proxy-core surface 不得重新引入 routes/proxy，transformer 继续保持协议纯净。

OneApi/Veloera 的整套继承统一、以及 completions/embeddings/images/search/ Gemini 的所有 proxy-log 写入迁移暂缓：真实差异包括 header、quota divisor、 check-in 文案、model error propagation、usage/billing 默认值和 await 时序。只有补齐参数化协议回归后，才允许另建任务继续合并；“减少文件数”不是跳过这些契约的理由。

维护者工作流

新增 UI 交互时按以下顺序检查：

先搜索 components/ui、现有 responsive primitive 和 api.ts owner；
在 wrapper/helper 层补行为测试，再迁移一个页面；
运行 npm run repo:drift-check，确认没有第三方 UI/style runtime 直引；
记录请求并发、stale、timer/reader cleanup 和 chunk 证据；没有实测的收益写成“待验证瓶颈”，不要用构建成功替代性能结论。

ModernSelect 是兼容 facade，当前仍使用项目自己的 listbox 实现；它不是 “所有交互都已迁移到 Radix Select”的信号。未来若替换内部行为，必须保持现有 options/value/onChange/placeholder 契约并新增键盘/controlled 回归测试。

6.4 KiB Raw Permalink Blame History Unescape Escape