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