---
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 整洁，无未使用的导入。