agent/.opencode/skills/engineering/code-quality/SKILL.md

name, description

name	description
code-quality	通用编码质量规范。适用于所有前端项目，与具体技术栈无关。当涉及任何代码实施、审计任务时，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 整洁，无未使用的导入。