feat:系统框架

This commit is contained in:
wlx committed 2026-06-29 19:27:33 +08:00
commit c1f1b39e81
25 files changed
+7515

No files matched your search

+353
View File
@@ -0,0 +1,353 @@
# 开发规范
## 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
```