# 开发规范 ## 1. 工程规范 ### 1.1 推荐目录结构 如果继续在 `mlkj-website` 内开发,建议: ```text mlkj-website/ backend/ src/modules/auth/ src/modules/admin-users/ src/modules/content/ src/modules/media/ src/modules/evaluation/ frontend/ ... admin/ src/ api/ assets/ components/ layouts/ pages/ routes/ stores/ utils/ ``` 如果管理端独立工程,可将 `admin/` 放到 `mlkj-website-admin/app/`,当前 `docs/` 保持为设计文档目录。 ### 1.2 命名规范 | 类型 | 规范 | 示例 | | --- | --- | --- | | 文件夹 | kebab-case | `content-sections` | | TS 文件 | kebab-case | `evaluation-round.service.ts` | | 类名 | PascalCase | `EvaluationRoundService` | | 变量/函数 | camelCase | `createEvaluationRound` | | 常量 | UPPER_SNAKE_CASE | `TOKEN_KEY` | | 数据库表 | snake_case 复数 | `evaluation_rounds` | | API 路径 | kebab-case 或资源复数 | `/admin/evaluation/rounds` | | 权限码 | `module:action` | `work:publish` | ## 2. TypeScript 规范 1. 后续新增代码必须使用 TypeScript。 2. 开启严格类型检查,避免 `any` 扩散。 3. API 入参和出参必须有类型定义。 4. 复杂 JSON 字段必须定义接口或 schema,不能只写 `Record`。 5. 业务状态使用枚举或字面量联合类型,不使用散落字符串。 示例: ```ts export const publishStatuses = ['draft', 'published', 'disabled', 'archived'] as const export type PublishStatus = (typeof publishStatuses)[number] ``` ## 3. 前端开发规范 ### 3.1 页面组织 | 类型 | 规范 | | --- | --- | | 页面组件 | 只负责页面编排和数据请求 | | 表单组件 | 独立封装,接收初始值和提交回调 | | 列表组件 | 表格列、筛选条件、分页状态清晰 | | 文件选择器 | 全局复用,不在每个业务页面重复实现 | | 权限组件 | 通过权限码控制按钮显示 | ### 3.2 API 请求 1. 所有请求集中在 `src/api`。 2. 不在页面组件中拼接复杂 URL。 3. 统一处理错误提示、登录过期、403。 4. 分页参数统一使用 `page`、`pageSize`。 5. 时间统一使用 ISO 字符串,前端只负责展示格式化。 ### 3.3 表单规范 | 场景 | 要求 | | --- | --- | | 必填字段 | 前端和后端都校验 | | 长文本 | 显示字数限制 | | 图片选择 | 展示预览、尺寸、文件大小 | | 发布操作 | 二次确认 | | 删除操作 | 二次确认,优先逻辑删除或归档 | | 评分表单 | 保存草稿和提交分开 | ### 3.4 状态与权限 1. 菜单按后端返回的权限码过滤。 2. 按钮级权限也要控制。 3. 前端权限只用于体验,后端必须再次校验。 4. 路由守卫必须处理:未登录、无权限、token 过期、用户被禁用。 ### 3.5 UI 规范 1. 后台界面以信息密度和效率为主。 2. 表格页必须提供关键词搜索、筛选、分页。 3. 重要状态使用统一 badge:草稿、已发布、下架、归档、评审中、已锁定。 4. 上传、发布、评分等长操作必须有 loading 状态。 5. 错误提示要说明原因和下一步,不只显示「失败」。 ## 4. 后端开发规范 ### 4.1 模块结构 每个业务模块建议保持: ```text module-name/ module-name.controller.ts module-name.service.ts module-name.dto.ts module-name.module.ts ``` 复杂模块可增加: ```text module-name/ policies/ helpers/ serializers/ ``` ### 4.2 Controller 规范 1. Controller 只处理 HTTP 入参、权限装饰器和返回结果。 2. 不在 Controller 写复杂业务逻辑。 3. 每个接口都加 Swagger 装饰器。 4. 后台接口统一在 `/admin` 下。 5. 公开接口不得返回草稿、禁用、归档内容。 ### 4.3 Service 规范 1. Service 负责业务流程和事务边界。 2. 复杂写操作使用 Prisma transaction。 3. 发布、删除、锁定、评分提交必须写操作日志。 4. 删除优先逻辑删除或归档,除非明确是子资源硬删除。 5. 抛错使用 NestJS 标准异常,如 `BadRequestException`、`NotFoundException`、`ForbiddenException`。 ### 4.4 DTO 规范 1. 请求 DTO 必须使用 `class-validator`。 2. 数字字段使用 `class-transformer` 转换。 3. DTO 字段必须写 Swagger 示例。 4. 状态字段必须用 `IsIn` 校验。 5. 长文本必须限制长度。 ### 4.5 响应规范 继续沿用当前 `ApiResult`: ```json { "code": 0, "message": "ok", "data": {} } ``` 分页响应: ```json { "code": 0, "message": "ok", "data": { "list": [], "page": 1, "pageSize": 20, "total": 0 } } ``` ## 5. 数据库规范 ### 5.1 Prisma 规范 1. 表名使用 `@@map("snake_case_plural")`。 2. 字段名在 Prisma 中使用 camelCase,数据库中用 snake_case。 3. 每张业务表必须有 `createdAt`、`updatedAt`,日志和关联表可按需只有 `createdAt`。 4. 常用筛选字段必须建索引。 5. 外键删除策略要明确,不能使用默认行为糊过去。 ### 5.2 迁移规范 1. 每次 schema 改动必须生成 migration。 2. migration 名称描述业务,如 `add_evaluation_tables`。 3. 生产环境迁移前必须备份。 4. 不允许直接手改生产数据库结构。 5. JSON 字段结构变更必须给出兼容策略。 ### 5.3 JSON 字段规范 | 场景 | 要求 | | --- | --- | | 内容区块 | 保存完整结构,字段命名稳定 | | 设计参数 | 使用对象数组,不塞不可解析字符串 | | SEO | `title`、`description`、`keywords`、`ogImage` | | 版本快照 | 保留发布时完整内容 | ## 6. API 规范 ### 6.1 REST 约定 | 操作 | 方法 | | --- | --- | | 查询列表 | `GET /resources` | | 查询详情 | `GET /resources/:id` | | 新建 | `POST /resources` | | 更新 | `PATCH /resources/:id` | | 删除/归档 | `DELETE /resources/:id` | | 状态变更 | `PATCH /resources/:id/status` | | 动作 | `POST /resources/:id/action` | ### 6.2 查询参数 | 参数 | 说明 | | --- | --- | | `page` | 页码,从 1 开始 | | `pageSize` | 每页数量,最大 100 | | `keyword` | 关键词 | | `status` | 发布状态 | | `lang` | 语言 | | `sort` | 排序字段,必要时支持 | ### 6.3 时间与 ID 1. API 中 BigInt ID 统一返回字符串。 2. 时间统一返回 ISO 8601。 3. 前端传时间也使用 ISO 8601。 ## 7. 文件上传规范 ### 7.1 文件类型 | 类型 | 扩展名 | | --- | --- | | 图片 | `jpg`、`jpeg`、`png`、`webp`、`svg` | | 视频 | `mp4`、`mov`、`webm` | | 模型 | `glb`、`gltf`、`stl`、`obj`、`zip` | | 文档 | `pdf`、`docx`、`xlsx` | | 压缩包 | `zip` | ### 7.2 限制建议 | 类型 | 第一版限制 | | --- | --- | | 图片 | 单文件不超过 10MB | | 视频 | 单文件不超过 500MB | | 模型 | 单文件不超过 200MB | | 文档 | 单文件不超过 50MB | | ZIP | 单文件不超过 500MB | 实际限制以 OSS 和服务器配置为准。 ### 7.3 OSS Key 规范 ```text mlkj-website/{scene}/{usage}/{yyyy}/{mm}/{hash}.{ext} ``` 示例: ```text mlkj-website/works/covers/2026/06/7f3a9c.png ``` ## 8. 权限和安全规范 1. 后台接口默认需要登录,只有登录和公开接口例外。 2. 密码必须使用 bcrypt 或 argon2 哈希。 3. JWT secret 不得提交到代码仓库。 4. OSS 密钥不得暴露给前端,前端只拿临时上传凭证。 5. 富文本或 HTML 内容必须做白名单过滤。 6. 评委只能访问分配给自己的评分任务。 7. 评审轮次锁定后,评分不可修改。 8. 所有导出接口也要校验权限。 ## 9. 测试规范 ### 9.1 后端测试 必须覆盖: 1. 登录成功和失败。 2. 权限不足返回 403。 3. 内容草稿不影响前台。 4. 发布后前台可读取。 5. 文件类型和大小校验。 6. 评分计算权重。 7. 评委越权访问被拒绝。 ### 9.2 前端测试 重点覆盖: 1. 登录和路由守卫。 2. 内容编辑保存和发布。 3. 文件上传失败重试。 4. 作品和课程表单校验。 5. 评委评分表单。 ### 9.3 手工回归 每次上线前至少回归: 1. 官网首页。 2. 赛道页。 3. 作品列表和详情。 4. 课程列表和详情。 5. 后台登录、上传、发布。 6. 评选完整流程。 ## 10. 文档规范 1. 新增接口必须同步 Swagger。 2. 新增环境变量必须同步 `.env.example`。 3. 新增数据库表必须同步数据库设计文档。 4. 重要业务流程变更必须同步 PRD 或设计文档。 5. 上线步骤必须记录在部署文档。 ## 11. 代码提交规范 如果项目使用 Git,建议提交信息采用: ```text type(scope): summary ``` 类型: | type | 说明 | | --- | --- | | `feat` | 新功能 | | `fix` | 修复 | | `docs` | 文档 | | `refactor` | 重构 | | `test` | 测试 | | `chore` | 工程杂项 | | `style` | 格式调整 | 示例: ```text feat(evaluation): add scoring assignment API ```