开发规范

核心原则

• ⭐ TDD 优先：先写测试，再写代码
• 🎨 UI 组件：必须使用 shadcn/ui
• 📦 包管理：使用 pnpm workspace
• 🔒 类型安全：TypeScript 严格模式

后端开发规范

技术栈

• Web 框架: Hono（专为边缘环境优化）
• 运行时: Cloudflare Workers
• ORM: Prisma 7（使用 Prisma Accelerate 或 Adapter）
• 验证: Zod（schema 验证）
• 认证: JWT + bcryptjs

目录结构

apps/server/src/
├── config/          # 配置模块
├── db/              # Prisma client
├── lib/             # 工具函数
├── middlewares/     # Hono 中间件
├── routes/v1/       # API 路由
├── services/        # 业务逻辑层
└── __tests__/       # 测试文件（与源码结构对应）

代码组织

• 分层: Routes → Services → Database
• 路由层: 只处理请求/响应，调用 Service
• 服务层: 业务逻辑，不直接处理 HTTP

API 设计

• RESTful，版本前缀 /api/v1/
• 统一响应格式：success() 包装器
• 错误处理：AppError + 统一错误中间件
• 类型安全：Hono RPC 客户端自动类型推断

前端开发规范

技术栈

• UI 框架: React 19 + Vite
• 路由: React Router DOM v7
• 状态管理: Zustand（全局）+ TanStack Query（服务端）
• UI 组件: shadcn/ui（必须使用，禁止其他 UI 库）
• 样式: Tailwind CSS（布局优先，少用颜色类）
• 表单: react-hook-form + zod

目录结构

apps/web/src/
├── components/      # React 组件（auth/, layouts/, ui/）
├── hooks/queries/   # React Query hooks
├── lib/             # 工具函数（api, api-error）
├── pages/           # 页面组件
├── routes/          # 路由配置
└── stores/          # Zustand stores

UI 组件

• 必须使用 shadcn/ui：pnpm dlx shadcn@latest add [component-name]
• 组件位置：components/ui/
• 禁止：Material-UI、Ant Design 等

路由守卫

• ProtectedRoute：保护需要登录的路由
• PublicRoute：已登录用户访问登录页时重定向

API 调用

• 使用 Hono RPC 客户端（hc），自动类型推断
• 位置：lib/api.ts
• 自动添加 Authorization header
• API hooks：封装在 hooks/queries/ 中

类型安全规范 ⚠️ 严格遵循

TypeScript 严格模式

• 禁止使用 any 类型：必须使用明确的类型定义
• 如果类型推断失败，应该：
  1. 检查类型定义是否正确
  2. 使用 unknown 进行类型守卫
  3. 定义明确的接口或类型别名
  4. 使用泛型提高类型复用性

类型定义原则

• 优先使用类型推断，减少显式类型注解
• 使用 interface 定义对象类型
• 使用 type 定义联合类型、工具类型等
• 避免使用类型断言（as），除非确实必要且类型安全

示例

// ❌ 错误：使用 any
function process(data: any) { ... }

// ✅ 正确：使用明确的类型
function process<T>(data: T) { ... }
// 或
function process(data: unknown) {
  if (isValidData(data)) { ... }
}

Git 提交规范

格式

类型(模块): 描述

类型: feat | fix | docs | refactor | test | chore | perf | ci

模块: auth | user | api | ui | config | deploy | deps | init

示例:

feat(auth): 添加用户登录功能
fix(api): 修复 CORS 错误
docs(readme): 更新部署文档
chore(deps): 更新依赖版本
test(auth): 添加登录测试用例

包管理规范

包管理器

• 使用 pnpm（workspace 模式）
• 安装：pnpm add [package] 或 pnpm add -D [package]
• 工作区：使用 --filter 指定工作区

禁止使用的包

• UI 库: Material-UI、Ant Design 等（使用 shadcn/ui）
• CSS 框架: Bootstrap、Bulma 等（使用 Tailwind）
• 状态管理: Redux（使用 Zustand + TanStack Query）

注意事项

1. 不要提交敏感信息（环境变量、密钥）
2. 不要提交构建产物（dist/, .wrangler/）
3. 遵循 TDD 流程：先写测试，再写代码
4. 使用 shadcn/ui，不要使用其他 UI 库
5. 保持代码简洁，遵循单一职责原则
6. 严格类型安全：禁止使用 any，必须使用明确的类型定义