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

256 lines
7.7 KiB
Markdown

# 开发要求
## 1. 环境要求
### 1.1 本地开发环境
| 项目 | 要求 |
| --- | --- |
| Node.js | 建议 20+,部署镜像可沿用当前 Node 22 |
| npm | 随 Node 安装 |
| PostgreSQL | 14+ |
| Prisma | 与后端依赖版本保持一致 |
| Docker | 用于本地联调和部署验证 |
| OSS | 阿里云 OSS 测试 bucket 或本地 mock |
### 1.2 必要环境变量
| 变量 | 说明 |
| --- | --- |
| `DATABASE_URL` | PostgreSQL 连接地址 |
| `JWT_ACCESS_SECRET` | access token 密钥 |
| `JWT_REFRESH_SECRET` | refresh token 密钥 |
| `JWT_ACCESS_EXPIRES_IN` | access token 过期时间 |
| `JWT_REFRESH_EXPIRES_IN` | refresh token 过期时间 |
| `ADMIN_INITIAL_USERNAME` | 初始化管理员账号 |
| `ADMIN_INITIAL_PASSWORD` | 初始化管理员密码 |
| `OSS_REGION` | OSS 区域 |
| `OSS_BUCKET` | OSS bucket |
| `OSS_ACCESS_KEY_ID` | OSS access key |
| `OSS_ACCESS_KEY_SECRET` | OSS secret |
| `OSS_PUBLIC_BASE_URL` | CDN 或 OSS 公开访问域名 |
| `UPLOAD_MAX_IMAGE_SIZE` | 图片大小限制 |
| `UPLOAD_MAX_VIDEO_SIZE` | 视频大小限制 |
## 2. 技术要求
| 模块 | 要求 |
| --- | --- |
| 管理端前端 | TypeScript、路由守卫、权限菜单、统一 API Client |
| 后端 | NestJS 模块化、DTO 校验、Swagger、RBAC Guard |
| 数据库 | Prisma migration、索引、外键、seed |
| 文件 | OSS 直传、上传完成登记、业务绑定 |
| 前台 | 只读取 published 内容 |
| 评选 | 分数计算可复现,结果锁定后不可随意变更 |
## 3. 质量要求
### 3.1 基础质量门槛
上线前必须满足:
1. 后端构建通过。
2. 前端构建通过。
3. Prisma schema validate 通过。
4. OpenAPI/Swagger 可正常访问。
5. 核心接口有测试或手工验收记录。
6. 没有明文密钥提交到代码。
7. 没有绕过权限的后台接口。
### 3.2 代码质量
| 项目 | 要求 |
| --- | --- |
| 类型 | 不新增明显 `any` 债务 |
| 格式 | 使用统一 formatter |
| 重复 | 业务表单、上传、权限组件应复用 |
| 错误处理 | 用户可理解,日志可追踪 |
| 可维护性 | 复杂逻辑拆到 service/helper |
### 3.3 数据质量
1. 必填字段必须前后端双重校验。
2. 发布内容必须有语言、状态、更新时间。
3. 文件记录必须包含 MIME、大小、URL、storage provider。
4. 作品编号、课程编号、赛道 slug 必须唯一。
5. 评分数据必须能追溯到轮次、评委、指标、作品。
## 4. 安全要求
### 4.1 登录与账号
1. 默认管理员首次登录后必须修改密码。
2. 管理员密码不能明文保存。
3. 连续登录失败需要限流或短暂锁定。
4. 禁用账号不能登录。
### 4.2 权限
1. 所有 `/api/admin/*` 接口默认需要鉴权。
2. 写操作必须校验具体权限码。
3. 评委账号只能访问自己的评分任务。
4. 操作日志不可由普通管理员删除。
### 4.3 文件
1. 禁止上传可执行文件。
2. SVG 如允许上传,前台展示前必须确认安全策略。
3. 文件大小必须在后端校验。
4. OSS 上传凭证必须短期有效。
5. 文件 URL 不应暴露 OSS 管理凭证。
### 4.4 内容安全
1. 富文本必须做 XSS 白名单过滤。
2. 前台渲染用户可编辑内容时默认转义。
3. 外部链接需要校验协议,只允许 `http`、`https` 和约定的本地开发地址。
4. 预览链接必须有过期时间。
## 5. 性能要求
| 场景 | 要求 |
| --- | --- |
| 后台列表 | 默认分页,单页最大 100 |
| 文件库 | 图片缩略图懒加载 |
| 作品列表 | 支持索引字段筛选,避免全表扫描 |
| 赛道页聚合接口 | 可在发布后清理缓存 |
| 上传 | 大文件直传 OSS,不经过业务服务器转发 |
| 评分汇总 | 轮次结果可预计算,不每次实时全量计算 |
目标参考:
| 指标 | 第一版目标 |
| --- | --- |
| 后台普通列表响应 | 1 秒内 |
| 前台公开接口响应 | 500ms 内,冷查询可放宽 |
| 管理端首屏加载 | 3 秒内 |
| 上传凭证生成 | 300ms 内 |
## 6. 可用性要求
1. 内容编辑页离开前提示未保存。
2. 上传中断可重试。
3. 发布失败不丢草稿。
4. 评分提交失败不丢已填分数。
5. 批量操作必须显示影响数量。
6. 删除、锁定、发布结果等操作必须二次确认。
## 7. 兼容性要求
| 端 | 要求 |
| --- | --- |
| 管理端 | PC 浏览器优先,兼容 Chrome、Edge、Safari 近两个大版本 |
| 前台 | 保持当前移动端和桌面端适配 |
| API | 保持当前公开接口尽量向后兼容 |
| 数据 | 旧 mock 数据可在数据库未配置时作为兜底 |
## 8. 日志与审计要求
必须记录:
| 操作 | 内容 |
| --- | --- |
| 登录 | 用户、时间、结果 |
| 内容发布 | 操作人、区块、前后数据 |
| 内容下架 | 操作人、原因 |
| 文件上传 | 文件、上传人、业务场景 |
| 作品删除 | 操作人、作品 ID、快照 |
| 评分提交 | 评委、作品、轮次 |
| 轮次锁定 | 操作人、轮次 |
| 结果发布 | 操作人、发布结果快照 |
日志要求:
1. 普通管理员只读。
2. 关键日志不可物理删除。
3. 日志中的敏感字段需要脱敏。
## 9. 备份与恢复要求
1. 上线前备份数据库。
2. 每次 migration 前备份生产库。
3. 文件删除第一版只做逻辑归档。
4. 内容发布保留历史版本。
5. 误发布可通过历史版本回滚。
6. 评审结果发布后,如需更正,必须记录更正原因。
## 10. 部署要求
### 10.1 构建要求
| 项目 | 命令参考 |
| --- | --- |
| 后端依赖 | `npm --prefix backend install` |
| Prisma | `npx prisma validate`、`npx prisma generate` |
| 后端构建 | `npm --prefix backend run build` |
| 前台构建 | `npm --prefix frontend run build` |
| 管理端构建 | 以后续管理端工程实际命令为准 |
### 10.2 发布顺序
1. 数据库备份。
2. 执行 migration。
3. 执行 seed。
4. 部署后端。
5. 部署管理端。
6. 部署前台。
7. 验证健康检查和 Swagger。
8. 验证登录、上传、发布、前台展示。
## 11. 验收要求
### 11.1 P0 功能验收
| 模块 | 验收项 |
| --- | --- |
| 登录权限 | 管理员可登录,不同角色权限正确 |
| 官网内容 | Hero 文案、图片可修改并发布 |
| 赛道内容 | 赛程、赛事说明、资源包可维护 |
| 素材库 | 图片、视频、文档、模型可上传和选择 |
| 课程 | 课程可新增、发布、前台展示 |
| 作品 | 作品可新增、发布、上传附件、前台展示 |
| 评选 | 可创建轮次、评委评分、汇总排名 |
| 日志 | 发布、删除、评分、结果发布有日志 |
### 11.2 P1 功能验收
| 模块 | 验收项 |
| --- | --- |
| 合作伙伴 | Logo、链接、排序可维护 |
| 大赛动态 | 通知可发布 |
| 批量导入 | 作品可批量导入 |
| 导出 | 评分结果可导出 |
| 线索 | 咨询线索可标记状态和备注 |
## 12. Definition of Done
一个功能只有满足以下条件才算完成:
1. 前端页面完成并可正常操作。
2. 后端接口完成并有 DTO 校验。
3. Swagger 已同步。
4. 数据库 migration 已提交。
5. 权限校验已接入。
6. 错误和空状态已处理。
7. 关键操作日志已记录。
8. 至少完成自测和核心路径联调。
9. 文档或说明已更新。
## 13. 上线前检查清单
| 检查项 | 状态 |
| --- | --- |
| 生产环境变量已配置 | 待检查 |
| 数据库已备份 | 待检查 |
| migration 已执行 | 待检查 |
| seed 已执行 | 待检查 |
| 超级管理员可登录 | 待检查 |
| OSS 上传可用 | 待检查 |
| 官网内容可发布 | 待检查 |
| 赛道内容可发布 | 待检查 |
| 作品和课程可展示 | 待检查 |
| 评选流程可完成 | 待检查 |
| 操作日志可查看 | 待检查 |
| Swagger 可访问 | 待检查 |
| 前台页面回归通过 | 待检查 |