📖 1. 概述
💡 核心理念
在基于 OpenClaw + Claude Code 的端到端研发自动化系统中，前端代码生成是核心环节之一。本规范旨在建立统一的前端代码生成标准模板与代码规范约束规则。
1.1 设计目标
一致性
所有 AI Agent 生成的代码遵循统一规范，确保团队协作无障碍
可维护性
代码结构清晰，易于理解和维护，降低技术债务
可扩展性
支持模块化扩展和复用，适应业务快速发展
安全性
内置安全防护机制，防范 XSS、CSRF 等常见攻击
可测试性
便于单元测试和集成测试，确保代码质量
AI 友好
优化 Prompt 工程，提升 AI 代码生成准确率
1.2 设计原则
参考 OpenClaw Pi 框架的极简设计理念，本规范遵循以下原则：
| 原则 | 说明 |
|---|---|
| 极简主义 | 保持模板简洁，避免过度工程化 |
| 用户驱动 | 允许开发者根据项目需求自定义扩展 |
| 确定性 | 确保 AI 生成的代码行为可预测 |
| 可观测性 | 所有生成过程透明可见，可追溯 |
| 串行优先 | 避免并行 SubAgent 导致的代码冲突 |
📝 2. 前端代码生成标准模板
2.1 React 组件模板
采用 TypeScript 严格模式，包含完整的类型定义、状态管理、事件处理和副作用处理。
✨ 模板特点
- 完整的 JSDoc 文档注释
- TypeScript 类型安全
- React Hooks 最佳实践
- 模块化 SCSS 样式
- 错误边界处理
- 性能优化（memo、useMemo、useCallback）
2.2 Vue 组件模板
基于 Vue 3 Composition API + TypeScript，采用 <script setup> 语法糖。
2.3 页面模板
完整的页面级组件，包含路由、数据获取、状态管理、错误处理等。
2.4 API 调用层模板
Axios 封装，包含请求/响应拦截器、错误处理、重试机制等。
2.5 自定义 Hook 模板
可复用的逻辑抽象，遵循 React Hooks 规则。
2.6 测试文件模板
使用 Vitest + Testing Library，包含完整的测试用例。
📏 3. 代码规范约束规则
3.1 命名规范
| 类型 | 规范 | 示例 |
|---|---|---|
| 组件文件 | PascalCase.tsx | UserProfile.tsx |
| Hook 文件 | camelCase.ts | useAuth.ts |
| 工具函数 | camelCase.ts | formatDate.ts |
| 常量文件 | UPPER_CASE.ts | API_ENDPOINTS.ts |
| 样式文件 | PascalCase.module.scss | UserProfile.module.scss |
3.2 代码风格规范
- 缩进：2 个空格
- 行尾分号：必须
- 最大行宽：100 字符
- 引号：单引号
- 箭头函数：单参数省略括号
3.3 TypeScript 规范
⚠️ 严格模式要求
- 禁止使用 any 类型
- 启用严格空值检查
- 所有函数必须有返回类型
- 启用未使用变量检查
3.4 安全规范
- XSS 防护：使用 DOMPurify sanitization
- CSRF 防护：包含 CSRF Token
- 敏感数据：不在日志中打印密码等敏感信息
- 输入验证：所有用户输入必须验证
3.5 性能规范
React.memo
避免不必要的组件重渲染
useMemo
缓存计算结果
useCallback
缓存函数引用
代码分割
懒加载大型组件
3.6 ESLint + Prettier 配置
提供完整的 ESLint 和 Prettier 配置文件，确保代码风格统一。
🔄 4. AI Coding 工作流集成
4.1 端到端研发流程
需求输入
→
PRD 设计
→
技术方案
→
API 协议
→
AI Coding
→
规范检查
→
Unit Test
→
集成测试
→
CI/CD
→
自动部署
4.2 AI 代码生成 Prompt 模板
📝 Prompt 结构
- Role: 定义 AI 角色（资深前端工程师）
- Task: 明确任务描述
- 技术要求: 指定技术栈和规范
- 输出要求: 列出需要生成的文件
- 约束条件: 设定代码限制
4.3 代码审查 Checklist
- 命名规范是否符合
- 类型定义是否完整
- 是否有未处理的错误情况
- 是否有安全漏洞（XSS、CSRF 等）
- 性能优化是否到位
- 测试覆盖率是否达标（>80%）
- 注释是否清晰完整
- 代码重复度是否过高
- 是否符合无障碍访问标准
- 响应式设计是否完善
✅ 5. 质量保障体系
5.1 单元测试
使用 Vitest + Testing Library，确保组件功能正确性。
- 渲染测试
- 交互测试
- 错误处理测试
- 可访问性测试
- 性能测试
5.2 集成测试
使用 Playwright 进行端到端测试，覆盖多浏览器场景。
5.3 CI/CD 流水线
Lint 检查
ESLint + Prettier 代码风格检查
测试执行
单元测试 + 集成测试
构建打包
生产环境构建
自动部署
Docker + K8S 部署
💡 6. 示例代码
完整示例项目包含以下文件：
examples/UserProfile.tsx- React 组件示例examples/UserProfile.vue- Vue 组件示例examples/api.ts- API 调用层示例examples/useAuth.ts- 自定义 Hook 示例examples/UserProfile.test.tsx- 测试示例