docs: 前端开发规范分层整理

- openspec/config.yaml 保留最高级前端规约和样式红线
- docs/development/README.md 引用前端专题文档避免重复
- docs/development/frontend.md 补充 antd、组件、样式、表单、测试等具体规范

docs/development/README.md

@@ -57,8 +57,7 @@
 - 运行工具使用 bunx，禁止使用 npx、pnpx。
 - 新增代码优先复用已有组件、工具和依赖库，不引入新依赖；确需新增依赖时先说明原因。
 - 后端优先使用 Bun 内置 API，其次是 es-toolkit、标准 Web API、主流三方库，最后才自行实现。
-- 前端样式优先使用 antd 组件、组件 props、antd Design Token / CSS 变量、styles.css CSS 类，最后才自行开发组件。
+- 前端优先使用 Ant Design 组件默认能力和组件 props 组合界面，具体组件、样式、数据流和测试细节见 [frontend.md](frontend.md)。
-- 前端禁止组件内联 style、覆盖 antd 内部类名、使用 !important、硬编码色值。
 - 当前项目无需考虑向前兼容。
 
 ## 包管理、依赖与提交

docs/development/frontend.md

@@ -26,9 +26,22 @@
 - 容器逻辑放在 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，样式开发优先级：
+前端基于 Ant Design 构建 UI。样式开发优先级：
 
 1. antd 组件
 2. 组件 props
@@ -43,22 +56,42 @@
 - 严禁使用 !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/
@@ -67,6 +100,8 @@ styles.css 组织：
 - 测试用户行为而非实现细节
 - 只 mock 系统边界，使用真实的 QueryClientProvider 包裹组件
 - 组件测试环境由 tests/setup.ts 和 bunfig.toml preload 提供
+- 断言优先基于用户可见文本、role、按钮和交互结果，不依赖 `.ant-*` 内部类名。
+- 对 antd 组件只断言本项目传入的可观察行为或配置结果，避免把 antd 内部 DOM 结构当作稳定契约。
 
 ## 更新触发条件
 

openspec/config.yaml

@@ -17,8 +17,8 @@ context: |
   - src/server目录下是基于bun实现的后端代码
     - 后端库使用优先级：Bun 内置 API > es-toolkit > 主流三方库 > 项目公共工具 > 自行实现
   - src/web目录下是基于Bun HTML import、React、Ant Design实现的前端代码
-    - 前端样式开发优先级：antd组件 > 组件props > antd Design Token/CSS变量(--ant-*) > styles.css CSS类 > 自行开发组件
+    - 前端最高规约：优先使用 antd 组件默认能力和组件 props 组合界面，具体组件、样式、数据流和测试细节遵循 docs/development/frontend.md
-    - 前端严禁：组件内联style属性、CSS覆盖antd内部类名、使用!important、硬编码色值
+    - 前端样式红线：禁止组件内联 style、覆盖 antd 内部类名、使用 !important、硬编码色值
   - Git提交: 仅中文; 格式"类型: 简短描述", 类型: feat/fix/refactor/docs/style/test/chore; 多行描述空行后写详细说明
   - 禁止创建git操作task
   - 积极使用subagents精心设计并行任务，节省上下文空间，加速任务执行