64 lines
2.3 KiB
Markdown
64 lines
2.3 KiB
Markdown
|
---
|
|||
|
|
name: code-quality
|
|||
|
|
description: 通用编码质量规范。适用于所有前端项目，与具体技术栈无关。当涉及任何代码实施、审计任务时，PM 必须参考此 Skill 并将要点注入子 Agent。
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 通用编码质量规范
|
|||
|
|
|
|||
|
|
## 1. TypeScript 严格模式
|
|||
|
|
|
|||
|
|
- **禁止** `any` 类型。所有变量、参数、返回值必须有明确类型。
|
|||
|
|
- props 和 state 必须严格类型化，使用 `interface` 或 `type` 定义。
|
|||
|
|
- 接口定义统一放在 `data.d.ts` 文件中，便于服务层和组件层共享。
|
|||
|
|
- 无隐式 `any`，无未使用变量，确保通过所有 lint 规则。
|
|||
|
|
|
|||
|
|
## 2. 组件规模红线
|
|||
|
|
|
|||
|
|
- **严禁**单个 React 组件文件（`.tsx`）超过 **500 行**。
|
|||
|
|
- 超过必须进行拆分：
|
|||
|
|
- **UI 子组件化**: 将可复用的 UI 片段提取为独立组件。
|
|||
|
|
- **逻辑 Hooks 化**: 将复杂业务逻辑抽离到自定义 Hooks 中。
|
|||
|
|
- **Utils 分离**: 纯计算函数抽离到 `utils/` 目录。
|
|||
|
|
- 原则：保持 UI 组件简洁、逻辑模块化。
|
|||
|
|
|
|||
|
|
## 3. 安全规范
|
|||
|
|
|
|||
|
|
### 3.1 金额/货币精度
|
|||
|
|
|
|||
|
|
- **绝不**使用原始浮点运算处理金额。
|
|||
|
|
- 使用精度安全库（如 `big.js`、`decimal.js`）或将金额作为**整数（分）**处理。
|
|||
|
|
- UI 层展示时再进行格式化转换。
|
|||
|
|
|
|||
|
|
### 3.2 XSS 防护
|
|||
|
|
|
|||
|
|
- **禁止** `dangerouslySetInnerHTML` 或绕过 React 转义的直接 DOM 操作。
|
|||
|
|
- 任何动态内容都必须经过清理（sanitize）。
|
|||
|
|
|
|||
|
|
### 3.3 权限控制
|
|||
|
|
|
|||
|
|
- 敏感操作、路由或 UI 元素必须受权限系统保护。
|
|||
|
|
- 检查"基于 ID"的未授权访问风险。
|
|||
|
|
|
|||
|
|
## 4. 数据交互规范
|
|||
|
|
|
|||
|
|
### 4.1 服务层隔离
|
|||
|
|
|
|||
|
|
- **所有**页面数据交互必须通过 `src/services/` 层封装的函数。
|
|||
|
|
- **禁止**在组件（JSX）中内联 mock 数据或直接发起请求。
|
|||
|
|
- Mock 数据统一放在项目约定的 `mock/` 目录。
|
|||
|
|
|
|||
|
|
### 4.2 加载状态
|
|||
|
|
|
|||
|
|
- 所有异步操作（请求、提交、删除等）**必须**显示加载状态（按钮 spinner 或骨架屏）。
|
|||
|
|
|
|||
|
|
### 4.3 防重复点击
|
|||
|
|
|
|||
|
|
- 所有操作按钮在执行期间必须被禁用（通过 loading + disabled 联动）。
|
|||
|
|
- 防止用户双击导致重复提交。
|
|||
|
|
|
|||
|
|
## 5. 代码卫生
|
|||
|
|
|
|||
|
|
- **零 Lint 策略**: 代码必须通过所有 linting 规则。
|
|||
|
|
- 无隐式 `any`，无未使用变量，hooks 中无缺失依赖数组。
|
|||
|
|
- 保持 import 整洁，无未使用的导入。
|