# Agent Park v2 项目章程 ## 核心原则 ### I. TypeScript 严格模式与类型安全 TypeScript 严格模式是强制要求。所有代码必须: - 在 tsconfig.json 中启用 `strict: true` 和所有严格选项 - 所有函数必须显式声明参数和返回值类型(禁止隐式 any) - 禁止使用 `@ts-ignore` 和 `@ts-nocheck`(除非用于临时迁移, 需要工单跟踪) - 外部数据必须经过运行时验证(如使用 Zod、Yup 等架构验证库) - 所有 API 响应必须定义明确的类型接口 **理由**: TypeScript 严格模式在编译时捕获潜在错误, 减少运行时问题, 提高代码可维护性和开发体验。类型安全使重构更安全, 代码更自文档化。 ### II. 组件优先架构 采用 Next.js App Router 架构模式, 遵循以下规则: - 优先使用 Server Components 而非 Client Components - 仅在需要交互性(状态、事件处理、浏览器 API)时使用 'use client' 指令 - 组件必须保持单一职责和可复用性 - 布局组件必须使用嵌套布局模式充分利用 Next.js 特性 - 路由处理程序(Route Handlers)用于 API 端点, 遵循 RESTful 原则 - 数据获取优先使用 Server Actions 或 Server Components 内的异步函数 **理由**: Server Components 提升性能、减少客户端 JavaScript 体积、改善 SEO。单一职责组件提高可维护性和可测试性。 ### III. 测试驱动开发(不可协商) TDD 是强制要求。测试必须在功能实现之前编写: - 红-绿-重构循环必须严格遵循 - 单元测试覆盖率必须达到 80% 以上 - 关键业务逻辑必须有集成测试 - UI 组件必须有可视化测试(如 Playwright 或 Storybook) - 所有测试必须在 PR 合并前通过 - 测试代码质量与生产代码同等重要 **理由**: TDD 确保代码可测试性、捕获早期错误、作为活文档、提供重构安全网。高测试覆盖率降低生产环境 Bug 风险。 ### IV. 性能优先 性能是核心质量指标, 必须满足: - 首次内容绘制(FCP) < 1.8s - 最大内容绘制(LCP) < 2.5s - 首次输入延迟(FID) < 100ms - 累积布局偏移(CLS) < 0.1 - 首次字节时间(TTFB) < 800ms - 图片必须使用 Next.js Image 组件(自动优化、懒加载) - 启用增量静态再生(ISR)或静态生成(SSG)而非服务端渲染(SSR)(如适用) - 客户端导航使用 Link 组件 - 禁止全量导入大型库(如 lodash), 使用按需导入 - 打包体积: 初始 JavaScript < 200KB gzipped **理由**: 性能直接影响用户体验、转化率和 SEO。Google Core Web Vitals 是搜索排名的重要因素。快速加载减少跳出率。 ### V. 用户体验一致性 跨整个应用必须保持一致的用户体验: - 所有页面必须响应式设计(移动优先) - 使用统一的设计系统(组件库、颜色、排版、间距) - 加载状态必须提供视觉反馈(skeleton、spinner 或进度条) - 错误处理必须提供用户友好的消息和恢复操作 - 表单必须有清晰的标签、验证提示和错误消息 - 所有交互元素必须有可访问性支持(ARIA 标签、键盘导航) - 深色模式支持(如适用) - 页面转换必须平滑(使用 View Transitions 或类似技术) **理由**: 一致性降低用户学习曲线、提高信任度、改善可访问性。良好的 UX 提高参与度和用户满意度。 ### VI. 代码质量与可维护性 代码必须遵循最佳实践和编码标准: - 使用 ESLint 和 Prettier 进行代码检查和格式化 - 遵循 Airbnb 或 Standard TypeScript 风格指南 - 函数复杂度必须控制在合理范围(圈复杂度 < 10) - 文件大小限制: < 300 行代码(可读性) - 导入路径使用别名(@/components/...)而非相对路径 - 环境变量使用 .env 文件, 在 .env.example 中记录所有变量 - 关键功能必须包含 JSDoc 注释 - 禁止在生产代码中使用 console.log(使用结构化日志库如 Pino) - 依赖项必须定期更新(每月审查安全和更新) **理由**: 一致的代码风格改善团队协作、降低认知负荷。清晰的代码减少维护成本、加速新开发者上手。 ## 技术标准 ### 技术栈要求 - **框架**: Next.js 14+ (App Router) - **语言**: TypeScript 5.0+ (严格模式) - **样式**: Tailwind CSS 或 CSS Modules - **状态管理**: React Context API 或 Zustand(如需要) - **表单**: React Hook Form + Zod 验证 - **数据库**: PostgreSQL 或 MongoDB(基于项目需求) - **ORM**: Prisma 或 Mongoose - **认证**: NextAuth.js 或 Clerk - **API**: RESTful (Route Handlers) 或 tRPC - **测试**: Vitest/Jest + React Testing Library + Playwright - **部署**: Vercel(推荐)或 Docker ### 框架版本控制 - Next.js 主版本升级需要评估和迁移计划 - 依赖项版本锁定(使用 package-lock.json 或 yarn.lock) - 破坏性变更需要文档和迁移指南 ## 开发工作流程 ### 代码审查要求 所有代码必须经过同行评审: - PR 必须包含清晰的描述和链接到相关议题/规范 - 至少一位团队成员批准才能合并 - 所有 CI 检查必须通过(测试、类型检查、Lint) - PR 大小限制: < 400 行变更(大变更需要拆分) - 审查者必须检查: 类型安全、测试覆盖、性能影响、可访问性 ### 质量门禁 代码合并前必须满足: - [ ] 所有测试通过(单元、集成、E2E) - [ ] TypeScript 编译无错误 - [ ] ESLint 无警告 - [ ] 性能预算未超限 - [ ] 可访问性检查通过(如 axe-core) - [ ] 安全扫描无高危漏洞(如 Dependabot) ### 分支策略 - `main`: 生产就绪代码 - `develop`: 开发集成分支 - `feature/*`: 功能分支(从 develop 分支) - `fix/*`: Bug 修复分支(从 develop 分支) - 使用语义化提交消息(Conventional Commits) ## 治理 本章程优先于所有其他实践和规范。 ### 修正流程 1. 提出修正: 创建议题描述需要修改的原则及原因 2. 团队审查: 讨论影响、权衡和替代方案 3. 批准: 需要多数团队核心成员同意 4. 文档化: 更新章程版本号和修正日期 5. 迁移计划: 为破坏性变更提供迁移指南 ### 合规审查 - 每个 PR 必须符合章程原则 - 每次功能规划必须检查章程兼容性 - 每季度审查章程并更新(如需要) - 违反章程需要明确理由和记录(在复杂度跟踪中) ### 版本控制 - **MAJOR**: 向后不兼容的原则删除或重新定义 - **MINOR**: 新原则添加或实质性扩展 - **PATCH**: 澄清、措辞、拼写错误修复 **版本**: 1.0.0 | **批准日期**: 2025-12-25 | **最后修正**: 2025-12-25