8.7 KiB
8.7 KiB
开发规范
1. 工程规范
1.1 推荐目录结构
如果继续在 mlkj-website 内开发,建议:
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 规范
- 后续新增代码必须使用 TypeScript。
- 开启严格类型检查,避免
any扩散。 - API 入参和出参必须有类型定义。
- 复杂 JSON 字段必须定义接口或 schema,不能只写
Record<string, any>。 - 业务状态使用枚举或字面量联合类型,不使用散落字符串。
示例:
export const publishStatuses = ['draft', 'published', 'disabled', 'archived'] as const
export type PublishStatus = (typeof publishStatuses)[number]
3. 前端开发规范
3.1 页面组织
| 类型 | 规范 |
|---|---|
| 页面组件 | 只负责页面编排和数据请求 |
| 表单组件 | 独立封装,接收初始值和提交回调 |
| 列表组件 | 表格列、筛选条件、分页状态清晰 |
| 文件选择器 | 全局复用,不在每个业务页面重复实现 |
| 权限组件 | 通过权限码控制按钮显示 |
3.2 API 请求
- 所有请求集中在
src/api。 - 不在页面组件中拼接复杂 URL。
- 统一处理错误提示、登录过期、403。
- 分页参数统一使用
page、pageSize。 - 时间统一使用 ISO 字符串,前端只负责展示格式化。
3.3 表单规范
| 场景 | 要求 |
|---|---|
| 必填字段 | 前端和后端都校验 |
| 长文本 | 显示字数限制 |
| 图片选择 | 展示预览、尺寸、文件大小 |
| 发布操作 | 二次确认 |
| 删除操作 | 二次确认,优先逻辑删除或归档 |
| 评分表单 | 保存草稿和提交分开 |
3.4 状态与权限
- 菜单按后端返回的权限码过滤。
- 按钮级权限也要控制。
- 前端权限只用于体验,后端必须再次校验。
- 路由守卫必须处理:未登录、无权限、token 过期、用户被禁用。
3.5 UI 规范
- 后台界面以信息密度和效率为主。
- 表格页必须提供关键词搜索、筛选、分页。
- 重要状态使用统一 badge:草稿、已发布、下架、归档、评审中、已锁定。
- 上传、发布、评分等长操作必须有 loading 状态。
- 错误提示要说明原因和下一步,不只显示「失败」。
4. 后端开发规范
4.1 模块结构
每个业务模块建议保持:
module-name/
module-name.controller.ts
module-name.service.ts
module-name.dto.ts
module-name.module.ts
复杂模块可增加:
module-name/
policies/
helpers/
serializers/
4.2 Controller 规范
- Controller 只处理 HTTP 入参、权限装饰器和返回结果。
- 不在 Controller 写复杂业务逻辑。
- 每个接口都加 Swagger 装饰器。
- 后台接口统一在
/admin下。 - 公开接口不得返回草稿、禁用、归档内容。
4.3 Service 规范
- Service 负责业务流程和事务边界。
- 复杂写操作使用 Prisma transaction。
- 发布、删除、锁定、评分提交必须写操作日志。
- 删除优先逻辑删除或归档,除非明确是子资源硬删除。
- 抛错使用 NestJS 标准异常,如
BadRequestException、NotFoundException、ForbiddenException。
4.4 DTO 规范
- 请求 DTO 必须使用
class-validator。 - 数字字段使用
class-transformer转换。 - DTO 字段必须写 Swagger 示例。
- 状态字段必须用
IsIn校验。 - 长文本必须限制长度。
4.5 响应规范
继续沿用当前 ApiResult:
{
"code": 0,
"message": "ok",
"data": {}
}
分页响应:
{
"code": 0,
"message": "ok",
"data": {
"list": [],
"page": 1,
"pageSize": 20,
"total": 0
}
}
5. 数据库规范
5.1 Prisma 规范
- 表名使用
@@map("snake_case_plural")。 - 字段名在 Prisma 中使用 camelCase,数据库中用 snake_case。
- 每张业务表必须有
createdAt、updatedAt,日志和关联表可按需只有createdAt。 - 常用筛选字段必须建索引。
- 外键删除策略要明确,不能使用默认行为糊过去。
5.2 迁移规范
- 每次 schema 改动必须生成 migration。
- migration 名称描述业务,如
add_evaluation_tables。 - 生产环境迁移前必须备份。
- 不允许直接手改生产数据库结构。
- 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
- API 中 BigInt ID 统一返回字符串。
- 时间统一返回 ISO 8601。
- 前端传时间也使用 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 规范
mlkj-website/{scene}/{usage}/{yyyy}/{mm}/{hash}.{ext}
示例:
mlkj-website/works/covers/2026/06/7f3a9c.png
8. 权限和安全规范
- 后台接口默认需要登录,只有登录和公开接口例外。
- 密码必须使用 bcrypt 或 argon2 哈希。
- JWT secret 不得提交到代码仓库。
- OSS 密钥不得暴露给前端,前端只拿临时上传凭证。
- 富文本或 HTML 内容必须做白名单过滤。
- 评委只能访问分配给自己的评分任务。
- 评审轮次锁定后,评分不可修改。
- 所有导出接口也要校验权限。
9. 测试规范
9.1 后端测试
必须覆盖:
- 登录成功和失败。
- 权限不足返回 403。
- 内容草稿不影响前台。
- 发布后前台可读取。
- 文件类型和大小校验。
- 评分计算权重。
- 评委越权访问被拒绝。
9.2 前端测试
重点覆盖:
- 登录和路由守卫。
- 内容编辑保存和发布。
- 文件上传失败重试。
- 作品和课程表单校验。
- 评委评分表单。
9.3 手工回归
每次上线前至少回归:
- 官网首页。
- 赛道页。
- 作品列表和详情。
- 课程列表和详情。
- 后台登录、上传、发布。
- 评选完整流程。
10. 文档规范
- 新增接口必须同步 Swagger。
- 新增环境变量必须同步
.env.example。 - 新增数据库表必须同步数据库设计文档。
- 重要业务流程变更必须同步 PRD 或设计文档。
- 上线步骤必须记录在部署文档。
11. 代码提交规范
如果项目使用 Git,建议提交信息采用:
type(scope): summary
类型:
| type | 说明 |
|---|---|
feat |
新功能 |
fix |
修复 |
docs |
文档 |
refactor |
重构 |
test |
测试 |
chore |
工程杂项 |
style |
格式调整 |
示例:
feat(evaluation): add scoring assignment API