354 lines
8.7 KiB
Markdown
354 lines
8.7 KiB
Markdown
# 开发规范
|
||
|
||
## 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<string, any>`。
|
||
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
|
||
```
|