# 系统架构设计 ## 1. 架构目标 1. 复用当前 `mlkj-website/backend` 的 NestJS、Swagger、Prisma、PostgreSQL 基础。 2. 管理端前端独立开发,和官网前台分开构建、分开路由。 3. 内容管理、文件上传、作品管理、评选管理在后端保持模块化。 4. 前台只读取已发布内容;后台可读取草稿、预览和历史版本。 5. 所有文件上传到 OSS,数据库只保存元数据和业务绑定关系。 ## 2. 总体架构 ```mermaid flowchart TD BrowserAdmin["管理端浏览器"] --> AdminFE["Admin Frontend
Vite + React/Vue + TS"] BrowserSite["官网访问者"] --> SiteFE["现有官网前台
HTML + JS"] AdminFE --> AdminAPI["NestJS Admin API
/api/admin/*"] SiteFE --> PublicAPI["NestJS Public API
/api/site /api/competition /api/works"] AdminAPI --> Auth["Auth + RBAC"] AdminAPI --> Content["Content CMS Module"] AdminAPI --> Media["Media Upload Module"] AdminAPI --> Work["Works Module"] AdminAPI --> Eval["Evaluation Module"] AdminAPI --> Log["Operation Log"] PublicAPI --> Content PublicAPI --> Work PublicAPI --> Course["Courses Module"] Content --> DB[("PostgreSQL")] Work --> DB Eval --> DB Course --> DB Media --> DB Media --> OSS[("Aliyun OSS")] SiteFE --> CDN["CDN/OSS 公开资源"] OSS --> CDN ``` ## 3. 推荐技术选型 | 层 | 推荐 | 说明 | | --- | --- | --- | | 管理端前端 | Vite + TypeScript + React 或 Vue | 当前前台已有 Vite,管理端可独立工程 | | UI 组件 | Ant Design / Arco Design / Naive UI | 管理后台表格、表单、上传、权限页成熟 | | 状态管理 | TanStack Query + 轻量 store | 列表、详情、缓存、刷新更顺手 | | 后端 | 继续使用 NestJS | 当前已有模块和 Swagger 基础 | | ORM | Prisma | 当前已使用 | | 数据库 | PostgreSQL | 当前 schema 已按 PostgreSQL 设计 | | 文件存储 | 阿里云 OSS | 图片、视频、模型、PDF、ZIP | | API 文档 | Swagger/OpenAPI | 后端已有 `@nestjs/swagger` | | 鉴权 | JWT + RBAC | 替换当前 env 简版登录 | ## 4. 后端模块划分 | 模块 | 主要职责 | | --- | --- | | `auth` | 登录、刷新 token、当前用户、密码修改 | | `admin-users` | 管理员、角色、权限 | | `content` | 官网和赛道页内容区块、草稿、发布、预览 | | `site` | 前台官网配置和首页聚合读取 | | `competition` | 赛道基础信息、赛程、资源、合作伙伴 | | `media` | OSS 直传凭证、文件记录、文件绑定 | | `courses` | 宣讲回放和培训视频 | | `works` | 作品、图片、模型、附件、投票 | | `evaluation` | 评审轮次、指标、评委分配、评分、结果 | | `inquiries` | 合作咨询线索 | | `operation-log` | 关键操作审计 | ## 5. 前台数据读取模式 ### 5.1 官网首页 ```mermaid sequenceDiagram participant FE as 官网首页 participant API as Public API participant DB as PostgreSQL FE->>API: GET /api/site/config API->>DB: 查询 published 配置 API-->>FE: 站点配置 FE->>API: GET /api/site/home API->>DB: 查询 published 首页区块 API-->>FE: 首页区块数组 ``` ### 5.2 赛道页 ```mermaid sequenceDiagram participant FE as 赛道页 participant API as Public API participant DB as PostgreSQL FE->>API: GET /api/competition API->>DB: 查询赛道基础信息、区块、赛程、资源、课程、作品 API-->>FE: 聚合后的赛道页数据 ``` ## 6. 内容版本与发布 推荐使用 `content_revisions` 记录草稿和发布版本。业务表保留当前展示字段,版本表保存完整 JSON 快照。 ```mermaid flowchart LR A["编辑表单"] --> B["content_revisions: draft"] B --> C["预览 API 读取 draft"] B --> D["发布"] D --> E["业务表更新 published 字段"] D --> F["content_revisions: published"] E --> G["前台 API 读取 published"] ``` 好处: 1. 前台查询仍可保持高性能。 2. 后台能保留历史版本和回滚依据。 3. 不需要把所有前台页面一次性改成通用 CMS 渲染。 ## 7. 文件上传架构 第一版建议使用 OSS Browser Direct Upload。 ```mermaid flowchart TD A["管理端选择文件"] --> B["后端生成上传凭证"] B --> C["管理端直传 OSS"] C --> D["后端登记 files"] D --> E["绑定业务对象"] ``` 建议 OSS 路径: ```text mlkj-website/ site/images/ competition/images/ competition/resources/ courses/covers/ courses/videos/ works/covers/ works/images/ works/models/ works/documents/ ``` ## 8. 鉴权与权限 1. 登录接口返回 `accessToken` 和 `refreshToken`。 2. 后台接口统一使用 `Authorization: Bearer `。 3. JWT 中保存用户 ID、角色、权限码摘要。 4. 后端每个写接口校验权限码。 5. 管理端菜单也按权限码过滤,但以后端校验为准。 ## 9. 缓存策略 | 数据 | 策略 | | --- | --- | | 前台站点配置 | 可缓存 5 分钟,发布后清理 | | 前台赛道页聚合 | 可缓存 1 分钟,发布后清理 | | 作品列表 | 按查询条件短缓存,投票后清理对应作品 | | 后台列表 | 不做强缓存,使用前端请求缓存即可 | | OSS 文件 | 由 CDN 控制,文件 key 使用 hash 避免覆盖 | ## 10. 部署建议 ```mermaid flowchart TD A["Nginx"] --> B["官网前台静态文件"] A --> C["管理端静态文件 /admin"] A --> D["NestJS API /api"] D --> E[("PostgreSQL RDS")] D --> F[("Redis 可选")] D --> G[("Aliyun OSS")] ``` 第一版可以不引入 Redis;当预览 token、短缓存、限流压力上来后再加入。 ## 11. 安全要求 | 方向 | 要求 | | --- | --- | | 登录 | 密码 bcrypt/argon2 哈希,失败次数限制 | | Token | 短期 access token,长期 refresh token 可撤销 | | 文件上传 | 限制 MIME、扩展名、大小,禁止可执行文件 | | OSS | 管理端上传用临时凭证,避免暴露永久密钥 | | XSS | 富文本白名单清洗,前台渲染转义 | | 操作日志 | 发布、下架、删除、评分锁定、结果发布必须记录 | | 评审数据 | 评委只能访问分配给自己的作品 | ## 12. 和现有项目的衔接 | 当前能力 | 后续动作 | | --- | --- | | `admin.html` 简版后台 | 可保留用于联调,正式后台建议独立前端替换 | | `AdminController` 已有作品/课程/文件接口 | 保留并扩展 DTO、权限、上传、图片附件接口 | | `site_configs/home_sections` | 可继续承载官网首页数据,补版本和发布流程 | | `competition_*` 表 | 扩展赛道页区块、资源类型、开放时间 | | `work_votes` | 继续承载公众投票,不与评委评分混用 | | `AdminUser/AdminRole` | 接入真实登录和 RBAC |