feat:系统框架
This commit is contained in:
commit
c1f1b39e81
25 files changed
+7515
No files matched your search
@@ -0,0 +1,203 @@
|
||||
# 系统架构设计
|
||||
|
||||
## 1. 架构目标
|
||||
|
||||
1. 复用当前 `mlkj-website/backend` 的 NestJS、Swagger、Prisma、PostgreSQL 基础。
|
||||
2. 管理端前端独立开发,和官网前台分开构建、分开路由。
|
||||
3. 内容管理、文件上传、作品管理、评选管理在后端保持模块化。
|
||||
4. 前台只读取已发布内容;后台可读取草稿、预览和历史版本。
|
||||
5. 所有文件上传到 OSS,数据库只保存元数据和业务绑定关系。
|
||||
|
||||
## 2. 总体架构
|
||||
|
||||
```mermaid
|
||||
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 官网首页
|
||||
|
||||
```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 <token>`。
|
||||
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 |
|
||||
Reference in new issue
Block a user