# 详细开发计划 ## 1. 开发目标 建设一个可正式运营的 PC 管理端,用于管理模灵科技公司官网和「智·造新时尚」赛道页内容,覆盖官网文案、图片素材、赛道资源、视频课程、作品管理、作品评选和咨询线索。 ## 2. 开发原则 1. 先完成 P0 闭环,再补 P1/P2 能力。 2. 保持前台视觉不大改,优先把静态内容切到 API。 3. 管理端和前台解耦,后台 API 作为唯一数据源。 4. 所有发布到前台的内容都必须有草稿、预览、发布、下架能力。 5. 所有高风险操作必须记录操作日志。 ## 3. 里程碑总览 | 阶段 | 名称 | 预计周期 | 目标 | | --- | --- | --- | --- | | M0 | 项目准备 | 1-2 天 | 明确工程结构、环境、任务拆分 | | M1 | 后台基础工程 | 4-6 天 | 登录、权限、布局、控制台、API 基础 | | M2 | 素材与内容管理 | 7-10 天 | 文件上传、官网内容、赛道内容、草稿发布 | | M3 | 作品与课程管理 | 7-10 天 | 作品、图片、模型、附件、课程视频完整 CRUD | | M4 | 作品评选 | 10-14 天 | 评审轮次、评委、指标、评分、排名、结果 | | M5 | 前台数据接入 | 5-8 天 | 官网和赛道页读取真实发布数据 | | M6 | 测试上线 | 5-7 天 | 联调、测试、部署、数据初始化 | ## 4. M0 项目准备 ### 4.1 工作内容 | 类型 | 任务 | | --- | --- | | 工程 | 确认管理端前端放在 `mlkj-website/admin`、`frontend-admin` 或独立仓库 | | 环境 | 准备 Node.js、PostgreSQL、OSS 测试 bucket、环境变量 | | 任务 | 按模块拆分 issue:auth、content、media、works、courses、evaluation | | 数据 | 确认当前静态文案、图片、作品、课程需要迁移的范围 | | 规范 | 确认代码规范、接口规范、分支规范、发布流程 | ### 4.2 交付物 | 交付物 | 说明 | | --- | --- | | 工程目录结构 | 管理端前端和后端模块位置确定 | | `.env.example` | 补齐数据库、JWT、OSS、CDN、管理员初始账号 | | 任务拆分表 | 每个阶段的任务、负责人、依赖、验收 | | 初始化数据清单 | 需要从 HTML/JSON 迁移到数据库的内容 | ### 4.3 验收标准 1. 本地前台、后端、数据库可启动。 2. Swagger 可访问。 3. Prisma schema 可 validate。 4. OSS 测试凭证可生成或已确定 mock 方案。 ## 5. M1 后台基础工程 ### 5.1 后端任务 | 编号 | 任务 | 说明 | | --- | --- | --- | | BE-M1-01 | 接入真实管理员登录 | 使用 `admin_users`,密码哈希,不再只依赖 `.env` 密码 | | BE-M1-02 | JWT 鉴权 | access token + refresh token | | BE-M1-03 | RBAC 权限 | 接入 `admin_roles.permissions` | | BE-M1-04 | 管理端 Guard | 统一校验登录和权限码 | | BE-M1-05 | 控制台接口 | 返回作品、课程、文件、线索、待评数据 | | BE-M1-06 | 操作日志基础 | 写入登录、发布、删除、状态变更 | | BE-M1-07 | Swagger 整理 | 所有后台接口有 tag、summary、DTO | ### 5.2 前端任务 | 编号 | 任务 | 说明 | | --- | --- | --- | | FE-M1-01 | 管理端脚手架 | Vite + TypeScript + 路由 + UI 组件库 | | FE-M1-02 | 登录页 | 账号密码登录、错误提示、token 保存 | | FE-M1-03 | 路由守卫 | 未登录跳登录、无权限跳 403 | | FE-M1-04 | 基础布局 | 左侧菜单、顶部栏、用户菜单、内容区 | | FE-M1-05 | 控制台 | KPI、待办、快捷入口、最近操作 | | FE-M1-06 | API Client | 统一请求、错误拦截、token 刷新 | ### 5.3 数据库任务 | 编号 | 任务 | | --- | --- | | DB-M1-01 | 为 `admin_users` 添加初始超级管理员 seed | | DB-M1-02 | 建立默认角色和权限 seed | | DB-M1-03 | 如需要,新增 `admin_sessions` 或 refresh token 表 | ### 5.4 验收标准 1. 管理员可登录、退出、刷新页面后保持会话。 2. 不同角色看到不同菜单。 3. 未授权访问后台接口返回 401 或 403。 4. 控制台数据可正常展示。 ## 6. M2 素材与内容管理 ### 6.1 后端任务 | 编号 | 任务 | 说明 | | --- | --- | --- | | BE-M2-01 | 文件上传凭证 | `POST /admin/uploads/policy` | | BE-M2-02 | 上传完成登记 | `POST /admin/uploads/complete` 写入 `files` | | BE-M2-03 | 文件列表与筛选 | 支持场景、类型、关键词、分页 | | BE-M2-04 | 文件绑定 | 新增 `file_bindings` | | BE-M2-05 | 内容页面表 | 新增 `content_pages`、`content_sections`、`content_revisions` | | BE-M2-06 | 官网内容接口 | 站点配置、首页区块草稿/发布 | | BE-M2-07 | 赛道内容接口 | 基础信息、介绍、奖项、要求、须知、资源 | | BE-M2-08 | 预览接口 | 支持读取草稿内容 | ### 6.2 前端任务 | 编号 | 任务 | 说明 | | --- | --- | --- | | FE-M2-01 | 文件库列表 | 缩略图、文件信息、筛选、复制 URL | | FE-M2-02 | 上传组件 | 拖拽上传、进度、失败重试 | | FE-M2-03 | 文件选择器 | 在表单中复用,支持单选/多选 | | FE-M2-04 | 官网内容表单 | Hero、业务版图、产品矩阵、案例、咨询 | | FE-M2-05 | 赛道内容表单 | Hero、介绍、赛程、赛事说明、资源、伙伴 | | FE-M2-06 | 草稿发布操作 | 保存草稿、预览、发布、下架 | ### 6.3 数据库任务 | 编号 | 任务 | | --- | --- | | DB-M2-01 | 迁移 `files` 扩展字段 | | DB-M2-02 | 新增 `file_bindings` | | DB-M2-03 | 新增内容版本相关表 | | DB-M2-04 | 初始化官网和赛道页默认区块数据 | ### 6.4 验收标准 1. 上传图片后可在文件库看到,并可绑定到官网 Hero。 2. 修改官网 Hero 文案,发布后前台接口返回新内容。 3. 修改赛道页赛程和资源,发布后前台接口返回新内容。 4. 草稿内容未发布前不影响前台。 ## 7. M3 作品与课程管理 ### 7.1 后端任务 | 编号 | 任务 | 说明 | | --- | --- | --- | | BE-M3-01 | 扩展课程 DTO | 支持封面文件、视频文件、外部链接、主讲人 | | BE-M3-02 | 课程 CRUD | 列表、详情、新增、编辑、上下架 | | BE-M3-03 | 扩展作品 DTO | 支持材料状态、评审状态、精选、附件 | | BE-M3-04 | 作品 CRUD | 列表、详情、新增、编辑、删除 | | BE-M3-05 | 作品图片接口 | 添加、排序、删除图片 | | BE-M3-06 | 作品附件接口 | 模型、PDF、ZIP、说明书 | | BE-M3-07 | 批量导入预留 | CSV/XLSX 可 P1 实现 | ### 7.2 前端任务 | 编号 | 任务 | 说明 | | --- | --- | --- | | FE-M3-01 | 课程列表 | 类型、状态、关键词筛选 | | FE-M3-02 | 课程编辑 | 封面、视频、外链、详情、发布状态 | | FE-M3-03 | 作品列表 | 搜索、筛选、批量操作、状态标识 | | FE-M3-04 | 作品编辑 | 基础信息、AIGC、提示词、设计参数 | | FE-M3-05 | 作品素材 | 封面、图集、模型、附件 | | FE-M3-06 | 作品详情预览 | 后台查看前台展示效果 | ### 7.3 数据库任务 | 编号 | 任务 | | --- | --- | | DB-M3-01 | 扩展 `courses` 文件关联字段 | | DB-M3-02 | 扩展 `works` 材料状态、评审状态、精选字段 | | DB-M3-03 | 为作品列表常用筛选添加索引 | ### 7.4 验收标准 1. 新建课程并发布后,赛道页在线学习和课程详情页可读取。 2. 新建作品并发布后,作品列表和详情页可读取。 3. 作品封面、图集、模型、附件均能上传和展示。 4. 下架作品不在前台列表展示。 ## 8. M4 作品评选 ### 8.1 后端任务 | 编号 | 任务 | 说明 | | --- | --- | --- | | BE-M4-01 | 评委资料 | `judge_profiles` | | BE-M4-02 | 评审轮次 | 初评、复评、决赛 | | BE-M4-03 | 评分指标 | 指标、满分、权重、排序 | | BE-M4-04 | 评分任务 | 作品分配给评委 | | BE-M4-05 | 评委评分 | 暂存、提交、锁定 | | BE-M4-06 | 结果计算 | 专家分、公众分、最终分、排名 | | BE-M4-07 | 结果发布 | 写入 `evaluation_results` 并同步作品获奖状态 | | BE-M4-08 | 导出预留 | 评分表导出可 P1 实现 | ### 8.2 前端任务 | 编号 | 任务 | 说明 | | --- | --- | --- | | FE-M4-01 | 轮次管理 | 创建、编辑、开启、关闭、锁定 | | FE-M4-02 | 指标配置 | 动态增删指标,权重校验 | | FE-M4-03 | 评委管理 | 评委账号和资料 | | FE-M4-04 | 作品分配 | 手动选择、批量分配 | | FE-M4-05 | 评分进度 | 按评委、作品、状态查看 | | FE-M4-06 | 评委端评分页 | 作品详情、附件、评分表单 | | FE-M4-07 | 结果汇总页 | 排名、分数、获奖等级、发布 | ### 8.3 数据库任务 | 编号 | 任务 | | --- | --- | | DB-M4-01 | 新增评选相关 6 张表 | | DB-M4-02 | 添加唯一约束防止重复分配 | | DB-M4-03 | 添加评分汇总查询索引 | ### 8.4 验收标准 1. 可创建评审轮次和评分指标。 2. 可把作品分配给评委。 3. 评委只能看到自己的任务。 4. 评委可提交评分,提交后系统能汇总排名。 5. 评审管理员可发布获奖结果。 ## 9. M5 前台数据接入 ### 9.1 工作内容 | 页面 | 改造内容 | | --- | --- | | 官网首页 | `site/config`、`site/home` 接口替换静态文案 | | 赛道页 | `competition` 聚合接口替换静态区块 | | 作品详情 | `works/:id` 接口补齐图片、附件、AIGC、模型 | | 课程详情 | `courses/:id` 接口补齐视频和详情 | | 投票 | 保留 `works/:id/vote`,加入错误提示和防重复 | ### 9.2 验收标准 1. 前台页面没有明显视觉回退。 2. API 失败时有 mock 或空状态兜底。 3. 已发布内容可展示,草稿内容不可展示。 4. 页面主要图片、视频、附件链接可访问。 ## 10. M6 测试上线 ### 10.1 测试范围 | 类型 | 内容 | | --- | --- | | 单元测试 | 权限、评分计算、内容发布、文件校验 | | 接口测试 | 登录、内容、文件、作品、课程、评选 | | 前端测试 | 登录、路由守卫、表单、上传、发布 | | 回归测试 | 官网首页、赛道页、作品详情、课程详情 | | 安全测试 | 未登录、越权、文件类型、XSS | ### 10.2 上线步骤 1. 备份数据库。 2. 执行 Prisma migration。 3. 初始化角色、权限、超级管理员。 4. 初始化官网和赛道页内容区块。 5. 配置 OSS、CDN、JWT、管理员密码。 6. 部署后端 API。 7. 部署管理端静态文件。 8. 部署前台静态文件。 9. 验证 Swagger、登录、上传、发布、前台展示。 ### 10.3 上线验收 | 项目 | 标准 | | --- | --- | | 登录 | 超级管理员和普通运营账号可登录 | | 内容发布 | 官网和赛道页各至少发布一个区块 | | 文件上传 | 图片、视频、PDF、ZIP 至少各验证一种 | | 作品 | 新增作品并前台展示 | | 课程 | 新增课程并前台播放或跳转 | | 评选 | 创建轮次、提交评分、生成排名 | | 日志 | 关键操作有日志 | ## 11. 任务依赖 ```mermaid flowchart TD M0["M0 项目准备"] --> M1["M1 后台基础工程"] M1 --> M2["M2 素材与内容管理"] M1 --> M3["M3 作品与课程管理"] M2 --> M5["M5 前台数据接入"] M3 --> M4["M4 作品评选"] M3 --> M5 M4 --> M6["M6 测试上线"] M5 --> M6 ``` ## 12. 优先级建议 第一轮上线必须完成: 1. 登录、权限、控制台。 2. 文件上传和文件库。 3. 官网首页关键文案和图片管理。 4. 赛道页基础信息、赛程、赛事说明、资源包。 5. 课程视频管理。 6. 作品管理和前台展示。 7. 基础评选流程:轮次、指标、评委、评分、排名。 第二轮迭代: 1. 内容审批流。 2. 批量导入作品。 3. 评分表导出。 4. 文件清理任务。 5. 视频点播 VOD。 6. 更完整的数据看板。