Files
mlkj-website-admin/docs/10-development-standards.md
2026-06-29 19:27:33 +08:00

354 lines
8.7 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 开发规范
## 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
```