Alfred/docs/development/frontend.md

前端开发

本文档说明 alfred 前端的 React、Ant Design、TanStack Query、组件、样式和前端测试约定。

适用场景：修改 src/web/、前端共享类型使用方式、组件结构、样式规则或前端测试。

技术栈

层面	技术	用途
框架	React 19	UI 组件开发
构建	Vite（开发）+ Bun compile（生产）	开发服务 HMR 与生产构建
语言	TypeScript	类型安全
UI 库	Ant Design (antd) + @ant-design/icons	UI 组件与图标
数据层	TanStack Query (React Query) + React Query Devtools	服务端状态管理与自动刷新
路由	React Router v7 (Declarative mode)	SPA 路由与页面导航

不引入额外状态管理库。TanStack Query 承担服务端状态，组件内状态使用 useState。

组件开发规范

• 每个 React 组件一个 .tsx 文件，文件名使用 PascalCase
• 组件 props 定义为 interface XxxProps，紧邻组件函数声明
• 类型从 src/shared/api.ts 导入，使用 import type
• 展示组件放在 components/，通过 props 接收数据，通过回调返回事件；页面专属展示组件可就近放在 pages/*/components/
• 容器逻辑放在 hooks 中，组件只做数据消费；全局共享查询可提取为独立 hook（如 use-meta）
• 工具函数放在 utils/，保持纯函数无副作用

页面组件保持编排职责，组合 hooks 和展示组件；当页面同时承担查询、筛选、分页、表格列、弹窗表单和 mutation 时，应按工具栏、表格、表单弹窗等功能边界拆分。拆分以降低职责复杂度为目标，避免为了拆分而拆分。

Ant Design 使用规范

• 优先使用 antd 组件默认状态和官方交互模式；没有明确产品定制需求时，不额外改写组件视觉。
• 优先通过组件 props 配置行为和外观，例如 collapsible、theme、scroll、locale、status、variant、color。
• 全局使用 ConfigProvider 配置 antd 中文 locale；从 antd/locale/zh_CN 导入 zhCN。
• 需要 message、modal、notification 等 antd 应用级能力时，在 ConfigProvider 内包裹 App（代码中可别名为 AntApp），组件内通过 App.useApp() 获取。
• 状态页、异常页、空结果优先使用 Result、Empty、Alert、Spin 等 antd 组件。
• 信息展示优先使用 Typography、Card、Descriptions、Table 等 antd 组件，避免用原生标签加自定义 CSS 复刻。
• 搜索输入优先使用 Input.Search，保持回车搜索、按钮搜索和清空行为一致。
• 表格在窄屏有挤压风险时必须提供明确的 scroll 或响应式列策略。

样式开发规范

前端基于 Ant Design 构建 UI。样式开发优先级：

1. antd 组件
2. 组件 props
3. antd Design Token / CSS 变量（--ant-*）
4. styles.css CSS 类
5. 自行开发组件

红线：

• 严禁在组件中使用 style 属性内联调整样式
• 严禁通过 CSS 覆盖 antd 组件内部类名
• 严禁使用 !important
• 颜色统一使用 antd Design Token / CSS 变量，不使用硬编码色值

默认状态原则：如果 antd 组件默认样式已经满足当前需求，不为其增加额外 CSS 类；不要通过外层 CSS 修改 Sider、Menu、Table、Modal 等组件内部结构样式。

styles.css 组织：

• 自定义 CSS 变量定义在 :root 中
• 布局类仅定义全局页面外壳，例如 app-layout、app-header、app-content
• 组件修饰类仅用于项目自有视觉组件，不用于覆盖 antd 内部结构
• 通用工具类必须有明确复用场景；只有一处使用时优先改为 antd 布局组件或局部结构
• AppShell 可以保留最小必要样式，如页面高度、Header 内容分布和 Content 间距

表单与交互规范

• Modal + Form 提交使用 Form onFinish 处理业务提交，Modal onOk 只触发 form.submit()。
• 不在 Modal onOk 中直接执行异步 validateFields 和提交逻辑，也不通过 lint disable 绕过该问题。
• 文本必填字段同时配置 required: true 和 whitespace: true，保持前端校验与后端 trim 后校验一致。
• 提交中状态传给 antd 组件的 loading/confirmLoading 等 props，避免自行实现重复状态样式。
• 操作确认优先使用 Popconfirm，成功/失败反馈优先使用 antd message。

运行时外壳规范

• 生产入口必须启用 ErrorBoundary，运行时渲染异常使用 antd Result status="500" 或等价组件展示。
• ReactQueryDevtools 仅在 import.meta.env.DEV 条件下渲染，不进入生产渲染路径。
• 主题切换统一通过 ConfigProvider 的 antd theme algorithm 控制，不使用硬编码主题色。

TanStack Query 规范

• Query key 使用 structured array，使用 as const 保持字面量类型
• 全局面板级查询可持续刷新，详情级查询必须按状态条件启用
• 多处页面使用同一后端资源时，应提取共享 hook，避免重复定义 fetch 函数。

fetch 封装

统一使用 fetch，不引入 axios。错误抛异常，由 TanStack Query 的 error 状态承接。

前后端共享的请求和响应类型定义在 src/shared/api.ts。前端 fetch 函数的返回类型必须匹配后端真实 JSON 形状；如果后端返回包装对象，例如 { project: Project }，应声明对应响应类型并在 hook 内提取业务对象。

前端测试

• 测试目录为 tests/web/，结构对应 src/web/
• 单元测试重点覆盖 utils/ 和 hooks 中的纯逻辑
• 组件测试使用 jsdom 和 @testing-library/react
• 测试用户行为而非实现细节
• 只 mock 系统边界，使用真实的 QueryClientProvider 包裹组件
• 组件测试环境由 tests/setup.ts 和 bunfig.toml preload 提供
• 断言优先基于用户可见文本、role、按钮和交互结果，不依赖 .ant-* 内部类名。
• 对 antd 组件只断言本项目传入的可观察行为或配置结果，避免把 antd 内部 DOM 结构当作稳定契约。

更新触发条件

修改前端技术栈、组件边界、数据流、样式规则、测试环境或前端验证方式时，必须更新本文档。