9.9 KiB
Fuser Mate React 参考调研:PLoop 的前端工程边界
核查日期:2026-08-31。范围是对本机 ~/workspace/project/fuser_mate 前端源码和工程配置的静态阅读;没有启动其前端、后端或 Electron 包装,也没有复制其代码。它是 PLoop 第一轮的 React 实现参考;评测领域的信息架构仍以 Fuser Lab 参考调研 和 V1 平台契约 为准。
1. 结论
Fuser Mate 的价值不在于其聊天产品页面,而在于它已把一个复杂 React 应用中最容易失控的几件事拆开:路由层只做装配,领域功能按 feature 收拢,网络访问有单一 typed client,服务端状态通过 query hook 管理,布局/设计 token/基础组件位于共享层,测试把 API mock 与浏览器交互分开。
PLoop 采用这些工程边界,但不把 Mate 的全局 features/<domain> 当作 PLoop 的目录模板。V1 与 Fuser Lab 保持一致地采用页面优先:页面专属 API、query、DTO adapter、动作与业务组件放在当前 pages/<domain>/<route>/;全局只保留 transport、通用 UI/工具和真实跨页 API。它不复制 JSX、CSS、API 类型或视觉资产。
Fuser Lab → PLoop 的评测产品路径与 Python 分层参考
Fuser Mate → PLoop 的 React 文件组织、状态管理、组件与测试参考
PLoop 自己 → 数据契约、gold 访问控制、Run 状态机与所有实际 UI/API 实现
2. 已观察到的 React 组织
2.1 技术与启动层
该项目的 frontend/package.json 与入口显示:React + TypeScript + Vite,React Router 负责浏览器路由,TanStack React Query 管理服务端数据,Tailwind CSS 与 Radix primitives 构成组件基础;并配置 ESLint、Prettier、Vitest 和 Playwright。main.tsx 只挂载应用和全局样式,App.tsx 集中 QueryClient、应用级初始化和全局提示,routes.tsx 使用懒加载、骨架 fallback 与 route error boundary。
PLoop 的直接含义:应用启动、路由、数据缓存和全局错误不能散落到 Dataset/Run 页面中。这样 Run 详情所需的轮询、取消、重新评分等异步状态才有一致的加载、错误与失效策略。
2.2 feature 与 shared 的边界
观察到的主目录形态如下:
src/app/
├─ features/<业务域>/api # endpoint 函数、types、query keys、query hooks
├─ features/<业务域>/components
├─ features/<业务域>/hooks
├─ shared/api # request client 和跨 feature 的类型
├─ shared/layout # AppShell、导航、侧栏、页面头、错误边界
├─ shared/lib # token、格式化及纯工具函数
├─ shared/ui # 业务无关的卡片、状态标签、操作按钮等
├─ components/ui # Radix 包装的较低层基础组件
├─ pages # 路由级组合
└─ routes.tsx
例如,一个 feature 把 list/get/create endpoint、对象类型、稳定 query key 与 useQuery hook 放在一起;页面只消费 hook 和组件。共享 request<T>() 统一处理 JSON、HTTP 失败和业务错误,而不是由每一个调用点各自解析 fetch 的返回值。
PLoop 映射如下:
| Fuser Mate 模式 | PLoop 应用 | 边界 |
|---|---|---|
features/<domain>/api |
pages/<domain>/<route>/apis + model 的 endpoint、DTO adapter、query/mutation;跨页 transport/key 才放 shared/api |
不能把 FastAPI 的内部 SQL model 或 artifact 私有字段直接当浏览器 type。 |
shared/api/client |
一处处理认证预留、HTTP/validation error、分页和请求取消的 typed client | API response envelope 由 PLoop OpenAPI 决定;不继承其 { code, message, data } 协议。 |
AppShell / rail / sidebar / header |
PLoop 的左侧导航、页面标题与页面框架 | 导航项按 Dataset、SUT、Run,不复用聊天/帖子/设置的路径与文案;shell 不承载具体 Run query、Case drawer 或 mutation。 |
SurfaceCard / StatusBadge / Table / Drawer |
Run 分面指标、阶段状态、列表和 Case 下钻的统一组件 | 状态颜色必须覆盖 PLoop 的 queued 到 cancelled,不使用其业务状态枚举。 |
| 路由级 lazy + skeleton + error boundary | Dataset、SUT、Run、Case 四个工作区的可恢复加载体验 | Case 内容也必须遵守 gold 投影规则,不能因为详情页就拿到 private artifact。 |
2.3 组件与样式方式
Fuser Mate 将较低层的按钮、表格、dialog 等封装在 components/ui,共享业务组件又进一步封装 SurfaceCard、StatusBadge。色彩、间距、圆角、阴影、文本层级等由 CSS variable 与 TypeScript class-name token 集中命名,而不是分散成每页的魔法值。
PLoop 可将此方式用于:RunPhaseBadge、MetricValue、ArtifactLink、CaseDrawer、EmptyState 和状态/错误提示。使用 Tailwind、Radix 或同等可访问性 primitives 是实现选项;无论具体依赖如何,页面不得直接依赖 Fuser Mate 的 class 名、SVG、主题变量或组件源码。
2.4 二次核查:PLoop 不照搬的复杂度形态
继续阅读 Workspace 页面后,可以看到 useWorkspacePageController.tsx 约 394 行,useWorkspacePostsController.ts 约 136 行:它们集中组合 route/search params、多个 query/mutation、定时刷新、drawer selection 和页面动作。这对聊天工作区可以集中编排,但若直接映射到 PLoop,useRunPageController 很容易同时拥有 Run 轮询、Case 分页、URL drawer、创建/取消/重评和指标刷新,后续难以测试也不容易判断每个状态的事实来源。
此外,AppRail.tsx 约 635 行,并含有部分全局 React Query/通知工作。PLoop 的左侧导航不需要为此读取某个 Run 的动态详情。由当前页面目录管理资源读取与动作、由 URL 保存 Case 选择,可以让 AppShell 保持为稳定的可替换框架。
这些是对源码结构的静态观察,不代表 Fuser Mate 的设计有误;结论只是它的工作区复杂度与 PLoop 的长时评测 Run 不同,因此不能机械复制 controller 形态。
2.5 测试方式
该项目区分了:
- 客户端、query 和纯函数的 Vitest 测试;
lint、格式检查、TypeScript build 的前端质量脚本;- 用 Playwright 启动 Vite,并由 route interception / fake API / WebSocket fixture 驱动的浏览器用例;失败时保留 trace;
- 一个单独的移动端 smoke 用例。
PLoop 应保留前三层。浏览器测试可用 fake API 稳定覆盖 Run 页面与失败状态;它们不能替代 Docker Compose 下真实 worker 的端到端测试。首轮的关键真实验收仍是:创建 demo Run 后,实际出现 request、raw、trace、score 与可读的 Case 详情。
3. PLoop 第一轮的采用清单
在 V1 平台契约 的 React 工程约定下,优先采用:
- 单一 typed API client 与页面优先目录:每个 route 自己保存 API/query/组件,跨页能力才提升至
shared/; - 每个页面使用稳定 query key 与 React Query hook;服务端状态不复制到全局 store;
AppShell、route-level loading/error boundary 和共享空态;Case drawer 的选中项和 tab 保存于 URL,而非 shell/controller;- token 化的状态、指标、卡片、表格、抽屉基础组件;
- typecheck、lint、组件/逻辑测试、fake API 的 Playwright 用例,以及真实 Compose E2E 的分层质量门。
部署包装也可参考其“前端静态资源由反向代理把 /api 转给 FastAPI”的开发/发布思路;但 PLoop 还需要独立 worker、PostgreSQL、Redis 和 artifact volume,因此 Docker Compose 的服务边界仍以平台计划为准,不能照搬其单镜像聊天应用的包装方式。
4. 明确不采用的范围
- 聊天 workspace、消息流、实时 WebSocket、帖子、通知、mate/profile/settings 的任何业务模型或 UI。
- Electron 判断、桌面拖拽区域、编辑器/Tiptap、富文本/附件、语音或会话运行时。
- 其 API 返回 envelope、具体 REST 路径、类型、mock fixtures、业务状态和视觉资产。
- 为贴近参考项目而引入与 PLoop 无关的依赖。每个 package 必须由 Dataset/SUT/Run/Case 的实际需求证明。
- 在浏览器请求或前端缓存中保留 gold answer、gold evidence、翻译内部资料或未投影的 private artifact。
- 将其复杂工作区的全能页面 controller 或带业务数据的 App rail 作为 PLoop 的架构模板。
5. 核查来源
- 工程说明与约束:
README.md、AGENT.md、frontend/AGENT.md。 - 前端技术与质量脚本:
frontend/package.json、frontend/vite.config.ts、frontend/playwright.config.ts。 - 应用、路由、API、layout 与组件:
frontend/src/main.tsx、frontend/src/app/App.tsx、frontend/src/app/routes.tsx、frontend/src/app/shared、frontend/src/app/features、frontend/src/app/components/ui。 - 浏览器测试:
frontend/tests/e2e。