lanyuanxiaoyao
b5301ec7d1
- 修正 API 响应类型，增加 ProjectResponse 包装类型 - ConfigProvider 配置中文 locale (zhCN) - 生产入口启用 ErrorBoundary，使用 Result 组件 - ReactQueryDevtools 仅开发环境渲染 - Sider 增加 collapsible 配置，使用 antd 默认折叠行为 - 项目页面拆分为 ProjectToolbar/ProjectTable/ProjectFormModal - 搜索改用 Input.Search，表单增加 whitespace 校验 - 404/ErrorBoundary/Dashboard 使用 antd Result/Typography/Card/Descriptions - 清理未使用的 ProtectedRoute 和冗余样式类 - styles.css 仅保留必要布局样式，无 antd 内部类覆盖 - 更新测试覆盖，避免依赖 antd 内部类名 - 更新 docs/development/frontend.md 开发规范
74 lines
3.1 KiB
Markdown
74 lines
3.1 KiB
Markdown
# 前端开发
|
||
|
||
本文档说明 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/，保持纯函数无副作用
|
||
|
||
## 样式开发规范
|
||
|
||
前端基于 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 变量，不使用硬编码色值
|
||
|
||
styles.css 组织：
|
||
|
||
- 自定义 CSS 变量定义在 :root 中
|
||
- 布局类定义全局页面结构
|
||
- 组件修饰类为自定义视觉组件提供样式变体
|
||
- 通用工具类提供公用排版能力
|
||
|
||
## TanStack Query 规范
|
||
|
||
- Query key 使用 structured array，使用 as const 保持字面量类型
|
||
- 全局面板级查询可持续刷新，详情级查询必须按状态条件启用
|
||
|
||
## fetch 封装
|
||
|
||
统一使用 fetch，不引入 axios。错误抛异常，由 TanStack Query 的 error 状态承接。
|
||
|
||
## 前端测试
|
||
|
||
- 测试目录为 tests/web/，结构对应 src/web/
|
||
- 单元测试重点覆盖 utils/ 和 hooks 中的纯逻辑
|
||
- 组件测试使用 jsdom 和 @testing-library/react
|
||
- 测试用户行为而非实现细节
|
||
- 只 mock 系统边界，使用真实的 QueryClientProvider 包裹组件
|
||
- 组件测试环境由 tests/setup.ts 和 bunfig.toml preload 提供
|
||
|
||
## 更新触发条件
|
||
|
||
修改前端技术栈、组件边界、数据流、样式规则、测试环境或前端验证方式时，必须更新本文档。
|