107 行
3.2 KiB
Markdown
107 行
3.2 KiB
Markdown
# 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路由规范
|
||
|
||
```typescript
|
||
// 公开接口使用 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
|