feat: 初始提交

docs/development/frontend.md

@@ -0,0 +1,73 @@
+# 前端开发
+
+本文档说明 my-app 前端的 React、TDesign、TanStack Query、组件、样式和前端测试约定。
+
+适用场景：修改 src/web/、前端共享类型使用方式、组件结构、样式规则或前端测试。
+
+## 技术栈
+
+| 层面   | 技术                                                | 用途                     |
+| ------ | --------------------------------------------------- | ------------------------ |
+| 框架   | React 19                                            | UI 组件开发              |
+| 构建   | Vite（开发）+ Bun compile（生产）                   | 开发服务 HMR 与生产构建  |
+| 语言   | TypeScript                                          | 类型安全                 |
+| UI 库  | TDesign React + tdesign-icons-react                 | 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/，保持纯函数无副作用
+
+## 样式开发规范
+
+前端基于 TDesign React 构建 UI，样式开发优先级：
+
+1. TDesign 组件
+2. TDesign 组件 props
+3. TDesign CSS tokens（--td-\*）
+4. styles.css CSS 类
+5. 自行开发组件
+
+红线：
+
+- 严禁在组件中使用 style 属性内联调整样式
+- 严禁通过 CSS 覆盖 TDesign 组件内部类名
+- 严禁使用 !important
+- 颜色统一使用 TDesign CSS tokens，不使用硬编码色值
+
+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 提供
+
+## 更新触发条件
+
+修改前端技术栈、组件边界、数据流、样式规则、测试环境或前端验证方式时，必须更新本文档。