107 lines
9.9 KiB
Markdown
107 lines
9.9 KiB
Markdown
# 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)。
|