前端技能规范

适用范围

以下规范适用于本仓库 src/ 目录下的前端代码。

仅在本仓库前端代码中生效，不用于后端或脚本目录。

技术栈

• React 18+（函数组件 + Hooks）
• TypeScript 5+
• Vite 7+
• Ant Design 5+
• Zustand 5+
• React Router 6+
• SCSS Modules
• 接口访问统一通过 @/api 封装（业务模块中不直接使用 axios）

命名规范

• 组件文件名 / 组件名：PascalCase
• 变量 / 函数：camelCase
• 类型 / 接口：PascalCase
• 常量：UPPER_SNAKE_CASE
• 样式模块：index.module.scss + styles.camelCaseName
• 工具文件：.ts；界面组件：.tsx

组件规范

• 优先使用函数组件和 Hooks，避免 class 组件。
• props 优先使用显式接口定义。
• 在可行情况下，将业务状态/副作用与展示 UI 分离。
• 仅在确有收益时使用 memo，避免无差别包裹。
• 如果组件仅被单处使用且渲染成本低，不要机械加 memo。

接口规范

• 后端请求统一通过 @/api 调用。
• 业务组件中不要直接调用 axios。
• 保持与现有请求/响应拦截器行为一致。
• 当前项目响应会经过拦截器二次解析，mock/接口返回结构要兼容该行为。

状态规范（Zustand）

• Store 结构应同时包含状态与动作（actions）。
• 组件读取局部状态时使用带类型的 selector。
• 状态更新保持可预期、最小化。

类型规范

• 避免 any，为接口数据和 props 提供明确类型。
• 可复用的领域类型放在 src/interface。
• 仅组件内部使用的类型放在组件附近。

样式规范

• 组件样式使用 SCSS Modules。
• 除非必须处理动态值，否则避免内联样式。
• :global 仅用于第三方组件样式覆写（如 Ant Design 内部类名）。
• style={{...}} 仅用于必须动态计算的场景，其余统一放模块样式。
• 主题色、Antd 覆盖与全局变量见 styles-and-theme.md。

目录规范

遵循现有目录结构：

• src/modules：按业务功能划分的模块
• src/components：公共组件
• src/hooks：可复用 hooks
• src/api：接口封装与配置
• src/store：Zustand 状态管理
• src/interface：类型声明
• src/utils：通用工具函数

推荐模式

1) 数据处理与展示渲染分离

• 将副作用、流解析、请求编排放在 hooks/controllers 中。
• 展示组件尽量保持纯粹，通过 props 驱动。
• 优先“容器组件 + 展示组件”分层，减少业务逻辑散落在 JSX。

2) 表单与列表保持可预期

• 表单值、表格行数据使用强类型。
• 以请求边界为中心管理异步 loading/error 状态。

3) 低风险演进改造

• 如无明确迁移计划，保持现有外部 props/interface 不变。
• 分层重构：先提取 types/utilities -> 再提取 hooks -> 最后提取展示组件。

项目常见 UI 模式

Section 容器优先

• 如果页面属于标准表单/列表/配置页，优先使用 Section 与 Section.Module。
• 新页面优先复用统一页面壳，避免每个模块重复写标题/底部按钮布局。

CRUD 页面基线

• 使用带类型的表格行与表单值定义。
• loadData 请求流程集中在单一位置维护。
• 复用 @/api 封装与现有错误/加载反馈模式。

禁止事项

• class 组件
• var
• 在业务模块中直接使用 axios
• 滥用 any
• 大段内联样式
• 已有公共 dict/常量时仍硬编码业务文案

模板库

• 可复用模板见 templates.md。
• 当用户说“按模板生成一个模块/页面”时，优先从模板文件取骨架。
• 样式与 Antd 主题约定见 styles-and-theme.md。

代码生成与重构执行清单

1. 遵循上述命名与目录规范。
2. 类型定义保持明确且收敛。
3. 数据逻辑优先沉淀为可复用 hooks/utilities。
4. 展示组件聚焦渲染职责。
5. 网络请求统一走 @/api。
6. 仅在逻辑不直观处补充最小必要注释。
7. 合适场景优先复用 templates.md 中的模板骨架。