Files

lanyuanxiaoyao 15ba33db27 refactor: 前端 UI 框架从 TDesign 迁移到 antd 6.x

- 移除 tdesign-react + tdesign-icons-react，新增 antd@6.4.3 + @ant-design/icons@6.2.3
- Layout/Header/Sider/Content 替换 TDesign Layout，Sider 内置折叠管理
- Segmented 替换 RadioGroup 主题切换，ConfigProvider 主题算法切换
- Menu items prop 模式，Sidebar 简化为无 props 纯组件
- Table/Modal/Form/Input.TextArea/Tabs/Tag/Popconfirm 全量迁移
- App.useApp().message 替换 MessagePlugin（hooks 模式）
- --td-* CSS 变量替换为 --ant-* antd CSS 变量
- 测试适配：ConfigProvider+App wrapper，.ant-menu-item-selected，antd CSS-in-JS jsdom 兼容
- 文档更新：frontend.md, development/README.md, config.yaml, deploy.md
- vendor-antd chunk 755KB gzipped 240KB

2026-05-28 13:20:12 +08:00

3.0 KiB

Raw Blame History

前端开发

本文档说明 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 接收数据，通过回调返回事件
容器逻辑放在 hooks 中，组件只做数据消费
工具函数放在 utils/，保持纯函数无副作用

样式开发规范

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

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

红线：

严禁在组件中使用 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 提供

更新触发条件

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

3.0 KiB Raw Blame History Unescape Escape