Files
mlkj-website-admin/docs/04-system-architecture.md
T
2026-06-29 19:27:33 +08:00

6.6 KiB

系统架构设计

1. 架构目标

  1. 复用当前 mlkj-website/backend 的 NestJS、Swagger、Prisma、PostgreSQL 基础。
  2. 管理端前端独立开发,和官网前台分开构建、分开路由。
  3. 内容管理、文件上传、作品管理、评选管理在后端保持模块化。
  4. 前台只读取已发布内容;后台可读取草稿、预览和历史版本。
  5. 所有文件上传到 OSS,数据库只保存元数据和业务绑定关系。

2. 总体架构

flowchart TD
  BrowserAdmin["管理端浏览器"] --> AdminFE["Admin Frontend<br/>Vite + React/Vue + TS"]
  BrowserSite["官网访问者"] --> SiteFE["现有官网前台<br/>HTML + JS"]

  AdminFE --> AdminAPI["NestJS Admin API<br/>/api/admin/*"]
  SiteFE --> PublicAPI["NestJS Public API<br/>/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 官网首页

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 赛道页

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 快照。

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。

flowchart TD
  A["管理端选择文件"] --> B["后端生成上传凭证"]
  B --> C["管理端直传 OSS"]
  C --> D["后端登记 files"]
  D --> E["绑定业务对象"]

建议 OSS 路径:

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 <token>。
  3. JWT 中保存用户 ID、角色、权限码摘要。
  4. 后端每个写接口校验权限码。
  5. 管理端菜单也按权限码过滤,但以后端校验为准。

9. 缓存策略

数据 策略
前台站点配置 可缓存 5 分钟,发布后清理
前台赛道页聚合 可缓存 1 分钟,发布后清理
作品列表 按查询条件短缓存,投票后清理对应作品
后台列表 不做强缓存,使用前端请求缓存即可
OSS 文件 由 CDN 控制,文件 key 使用 hash 避免覆盖

10. 部署建议

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