tennis-training-hub/docs/CODING_STANDARDS.md

Tennis Training Hub - 代码规范文档

项目约定

技术栈版本

技术	版本	用途
React	19	UI框架
TypeScript	5.9	类型安全
Tailwind CSS	4	样式系统
tRPC	11	端到端类型安全API
Drizzle ORM	0.44	数据库ORM
Vitest	2.1	测试框架
Express	4	HTTP服务器

文件命名规范

类型	规范	示例
React页面	PascalCase	Dashboard.tsx, LiveCamera.tsx
React组件	PascalCase	DashboardLayout.tsx
工具函数	camelCase	db.ts, storage.ts
测试文件	*.test.ts	features.test.ts
数据库迁移	自动生成	0001_public_prowler.sql
文档	UPPER_CASE.md	API.md, DATABASE.md

代码风格

TypeScript/React：

• 使用函数组件和Hooks，不使用类组件
• 使用 const 优先，必要时使用 let，禁止 var
• 使用箭头函数作为回调
• 使用模板字符串而非字符串拼接
• 使用可选链 ?. 和空值合并 ??
• 导出组件使用 export default function ComponentName()
• 类型定义使用 type 而非 interface（除非需要继承）

CSS/Tailwind：

• 优先使用Tailwind工具类
• 颜色使用OKLCH格式（Tailwind 4要求）
• 响应式设计使用移动优先策略（sm:, md:, lg:）
• 语义化颜色变量定义在 index.css 的 :root 中
• 避免内联样式，除非动态计算值

数据库：

• 字段使用camelCase命名
• 主键统一使用 id: int().autoincrement().primaryKey()
• 时间字段使用 timestamp 类型
• JSON字段用于存储结构化但不需要索引的数据
• 所有表包含 createdAt 字段

tRPC路由规范

// 公开接口使用 publicProcedure
publicProcedure.query(...)

// 需要认证的接口使用 protectedProcedure
protectedProcedure.query(...)
protectedProcedure.mutation(...)

// 输入验证使用 Zod
.input(z.object({
  field: z.string().min(1).max(64),
  optional: z.number().optional(),
}))

测试规范

• 每个API路由至少有一个认证测试
• 输入验证测试覆盖边界值
• 使用 createMockContext() 创建测试上下文
• 数据库操作在测试中允许抛出连接错误，但输入验证不应失败
• 测试文件放在 server/ 目录下

Git提交规范

前缀	用途	示例
feat:	新功能	feat: 添加排行榜功能
fix:	修复	fix: 修复打卡连续天数计算
docs:	文档	docs: 更新API文档
test:	测试	test: 添加徽章系统测试
refactor:	重构	refactor: 优化评分计算逻辑
style:	样式	style: 调整移动端布局

安全规范

• 所有LLM调用必须在服务端执行
• 文件上传通过服务端中转到S3
• 用户输入使用Zod严格验证
• Session使用HttpOnly Cookie
• 敏感操作使用 protectedProcedure

性能规范

• MediaPipe推理在浏览器端执行，不占用服务器资源
• 视频文件存储在S3，不存入数据库
• 使用tRPC的React Query缓存减少重复请求
• 大列表查询使用 limit 参数分页
• 图片和媒体资源使用CDN URL