ploop/docs/reference/fuser-mate-react-reference.md
2026-08-31 15:27:34 +08:00

107 lines
9.9 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Fuser Mate React 参考调研:PLoop 的前端工程边界
核查日期:2026-08-31。范围是对本机 [`~/workspace/project/fuser_mate`](/Users/pptg/workspace/project/fuser_mate/README.md) 前端源码和工程配置的静态阅读;没有启动其前端、后端或 Electron 包装,也没有复制其代码。它是 PLoop 第一轮的 **React 实现参考**;评测领域的信息架构仍以 [Fuser Lab 参考调研](fuser-lab-reference.md) 和 [V1 平台契约](../design/v1-platform-contract.md) 为准。
## 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 类型或视觉资产。
```text
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 的边界
观察到的主目录形态如下:
```text
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 测试方式
该项目区分了:
1. 客户端、query 和纯函数的 Vitest 测试;
2. `lint`、格式检查、TypeScript build 的前端质量脚本;
3. 用 Playwright 启动 Vite,并由 route interception / fake API / WebSocket fixture 驱动的浏览器用例;失败时保留 trace;
4. 一个单独的移动端 smoke 用例。
PLoop 应保留前三层。浏览器测试可用 fake API 稳定覆盖 Run 页面与失败状态;它们不能替代 Docker Compose 下真实 worker 的端到端测试。首轮的关键真实验收仍是:创建 demo Run 后,实际出现 request、raw、trace、score 与可读的 Case 详情。
## 3. PLoop 第一轮的采用清单
在 [V1 平台契约](../design/v1-platform-contract.md) 的 React 工程约定下,优先采用:
1. 单一 typed API client 与页面优先目录:每个 route 自己保存 API/query/组件,跨页能力才提升至 `shared/`;
2. 每个页面使用稳定 query key 与 React Query hook;服务端状态不复制到全局 store;
3. `AppShell`、route-level loading/error boundary 和共享空态;Case drawer 的选中项和 tab 保存于 URL,而非 shell/controller;
4. token 化的状态、指标、卡片、表格、抽屉基础组件;
5. typecheck、lint、组件/逻辑测试、fake API 的 Playwright 用例,以及真实 Compose E2E 的分层质量门。
部署包装也可参考其“前端静态资源由反向代理把 `/api` 转给 FastAPI”的开发/发布思路;但 PLoop 还需要独立 worker、PostgreSQL、Redis 和 artifact volume,因此 Docker Compose 的服务边界仍以平台计划为准,不能照搬其单镜像聊天应用的包装方式。
## 4. 明确不采用的范围
1. 聊天 workspace、消息流、实时 WebSocket、帖子、通知、mate/profile/settings 的任何业务模型或 UI。
2. Electron 判断、桌面拖拽区域、编辑器/Tiptap、富文本/附件、语音或会话运行时。
3. 其 API 返回 envelope、具体 REST 路径、类型、mock fixtures、业务状态和视觉资产。
4. 为贴近参考项目而引入与 PLoop 无关的依赖。每个 package 必须由 Dataset/SUT/Run/Case 的实际需求证明。
5. 在浏览器请求或前端缓存中保留 gold answer、gold evidence、翻译内部资料或未投影的 private artifact。
6. 将其复杂工作区的全能页面 controller 或带业务数据的 App rail 作为 PLoop 的架构模板。
## 5. 核查来源
- 工程说明与约束:[`README.md`](/Users/pptg/workspace/project/fuser_mate/README.md)、[`AGENT.md`](/Users/pptg/workspace/project/fuser_mate/AGENT.md)、[`frontend/AGENT.md`](/Users/pptg/workspace/project/fuser_mate/frontend/AGENT.md)。
- 前端技术与质量脚本:[`frontend/package.json`](/Users/pptg/workspace/project/fuser_mate/frontend/package.json)、[`frontend/vite.config.ts`](/Users/pptg/workspace/project/fuser_mate/frontend/vite.config.ts)、[`frontend/playwright.config.ts`](/Users/pptg/workspace/project/fuser_mate/frontend/playwright.config.ts)。
- 应用、路由、API、layout 与组件:[`frontend/src/main.tsx`](/Users/pptg/workspace/project/fuser_mate/frontend/src/main.tsx)、[`frontend/src/app/App.tsx`](/Users/pptg/workspace/project/fuser_mate/frontend/src/app/App.tsx)、[`frontend/src/app/routes.tsx`](/Users/pptg/workspace/project/fuser_mate/frontend/src/app/routes.tsx)、[`frontend/src/app/shared`](/Users/pptg/workspace/project/fuser_mate/frontend/src/app/shared)、[`frontend/src/app/features`](/Users/pptg/workspace/project/fuser_mate/frontend/src/app/features)、[`frontend/src/app/components/ui`](/Users/pptg/workspace/project/fuser_mate/frontend/src/app/components/ui)。
- 浏览器测试:[`frontend/tests/e2e`](/Users/pptg/workspace/project/fuser_mate/frontend/tests/e2e)。