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

7.7 KiB

开发要求

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 可访问 待检查
前台页面回归通过 待检查