# 系统架构设计
## 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 |