6.6 KiB
6.6 KiB
系统架构设计
1. 架构目标
- 复用当前
mlkj-website/backend的 NestJS、Swagger、Prisma、PostgreSQL 基础。 - 管理端前端独立开发,和官网前台分开构建、分开路由。
- 内容管理、文件上传、作品管理、评选管理在后端保持模块化。
- 前台只读取已发布内容;后台可读取草稿、预览和历史版本。
- 所有文件上传到 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"]
好处:
- 前台查询仍可保持高性能。
- 后台能保留历史版本和回滚依据。
- 不需要把所有前台页面一次性改成通用 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. 鉴权与权限
- 登录接口返回
accessToken和refreshToken。 - 后台接口统一使用
Authorization: Bearer <token>。 - JWT 中保存用户 ID、角色、权限码摘要。
- 后端每个写接口校验权限码。
- 管理端菜单也按权限码过滤,但以后端校验为准。
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 |