254 lines
8.0 KiB
Markdown
254 lines
8.0 KiB
Markdown
# 平台文档管理功能设计方案
|
||
|
||
## 1. 需求概述
|
||
|
||
### 1.1 功能目标
|
||
- 运营管理人员通过 `txw-yygl-web` 管理平台文档（增删改查）
|
||
- 门户网站 `txw-mhzc-web` 通过 API 获取文档列表和内容，前端渲染 Markdown
|
||
- 支持 Markdown 富文本编辑
|
||
- 文档按分类管理，支持通过 URL 直接跳转至对应文档
|
||
|
||
### 1.2 关键需求点
|
||
- 运营管理端：文档 CRUD + 分类管理
|
||
- 门户前端：文档列表 + 文档详情页（支持 URL 直接访问）
|
||
- 数据存储：`txw-mhzc` MySQL 数据库
|
||
|
||
---
|
||
|
||
## 2. 系统架构
|
||
|
||
### 2.1 整体架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 运营管理端 │
|
||
│ txw-yygl-web ←→ txw-yygl-service-biz ←→ txw-mhzc MySQL │
|
||
│ (内部调用) (新建 document 库) │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 门户前端 │
|
||
│ txw-mhzc-web ←→ txw-gateway（聚合层） ←→ 同一 API │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 2.2 技术选型
|
||
- 后端框架：Spring Boot（复用现有 `txw-yygl-service-biz`）
|
||
- 前端框架：Vue 2 + TDesign（复用现有技术栈）
|
||
- Markdown 编辑器：`mavon-editor`（轻量、Vue 2 兼容）
|
||
- Markdown 渲染：`marked` + `highlight.js`
|
||
- 数据库：MySQL（`txw-mhzc` 库）
|
||
|
||
---
|
||
|
||
## 3. 数据库设计
|
||
|
||
### 3.1 文档分类表（document_category）
|
||
|
||
| 字段 | 类型 | 约束 | 说明 |
|
||
|------|------|------|------|
|
||
| id | bigint | PK, AUTO_INCREMENT | 主键 |
|
||
| name | varchar(100) | NOT NULL | 分类名称 |
|
||
| sort | int | DEFAULT 0 | 排序号，越小越靠前 |
|
||
| status | tinyint | DEFAULT 1 | 状态：0-禁用，1-启用 |
|
||
| create_time | datetime | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
|
||
| update_time | datetime | ON UPDATE CURRENT_TIMESTAMP | 更新时间 |
|
||
|
||
### 3.2 文档表（document）
|
||
|
||
| 字段 | 类型 | 约束 | 说明 |
|
||
|------|------|------|------|
|
||
| id | bigint | PK, AUTO_INCREMENT | 主键 |
|
||
| category_id | bigint | NOT NULL, FK | 所属分类ID |
|
||
| title | varchar(200) | NOT NULL | 文档标题 |
|
||
| content | text | NOT NULL | Markdown 正文内容 |
|
||
| status | tinyint | DEFAULT 0 | 状态：0-草稿，1-已发布 |
|
||
| sort | int | DEFAULT 0 | 排序号，越小越靠前 |
|
||
| create_time | datetime | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
|
||
| update_time | datetime | ON UPDATE CURRENT_TIMESTAMP | 更新时间 |
|
||
|
||
---
|
||
|
||
## 4. API 设计
|
||
|
||
### 4.1 文档分类接口
|
||
|
||
| 接口 | 方法 | 路径 | 说明 |
|
||
|------|------|------|------|
|
||
| 分类列表 | GET | /document/category/list | 获取所有启用的分类 |
|
||
| 新增分类 | POST | /document/category | 新增文档分类 |
|
||
| 编辑分类 | PUT | /document/category/{id} | 编辑分类信息 |
|
||
| 删除分类 | DELETE | /document/category/{id} | 删除分类（需检查无关联文档）|
|
||
|
||
### 4.2 文档接口
|
||
|
||
| 接口 | 方法 | 路径 | 说明 |
|
||
|------|------|------|------|
|
||
| 文档列表 | GET | /document/list | 获取文档列表（支持分类筛选、状态筛选）|
|
||
| 文档详情 | GET | /document/{id} | 获取文档详情（Markdown 内容）|
|
||
| 新增文档 | POST | /document | 新增文档 |
|
||
| 编辑文档 | PUT | /document/{id} | 编辑文档 |
|
||
| 删除文档 | DELETE | /document/{id} | 删除文档 |
|
||
|
||
### 4.3 响应数据结构
|
||
|
||
**文档列表项（不含正文）**
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"categoryId": 1,
|
||
"categoryName": "使用指南",
|
||
"title": "如何注册账号",
|
||
"status": 1,
|
||
"sort": 1,
|
||
"createTime": "2026-04-28 10:00:00",
|
||
"updateTime": "2026-04-28 10:00:00"
|
||
}
|
||
```
|
||
|
||
**文档详情（含正文）**
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"categoryId": 1,
|
||
"categoryName": "使用指南",
|
||
"title": "如何注册账号",
|
||
"content": "# 注册流程\n\n1. 点击注册按钮\n2. 填写企业信息\n...",
|
||
"status": 1,
|
||
"sort": 1,
|
||
"createTime": "2026-04-28 10:00:00",
|
||
"updateTime": "2026-04-28 10:00:00"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 前端页面设计
|
||
|
||
### 5.1 运营管理端（txw-yygl-web）
|
||
|
||
**路由：`/document/*`**
|
||
|
||
| 页面 | 路由 | 功能 |
|
||
|------|------|------|
|
||
| 文档列表 | /document/list | 分类筛选、状态筛选、搜索、新建按钮 |
|
||
| 新增/编辑文档 | /document/edit/:id? | Markdown 编辑器、表单提交 |
|
||
| 分类管理 | /document/category | 分类列表、增删改 |
|
||
|
||
**组件说明**
|
||
- `DocumentList.vue` - 文档列表页
|
||
- `DocumentEdit.vue` - 文档编辑页（含 mavon-editor）
|
||
- `CategoryManage.vue` - 分类管理页
|
||
|
||
### 5.2 门户前端（txw-mhzc-web）
|
||
|
||
**路由：`/help/*` 或 `/document/*`**
|
||
|
||
| 页面 | 路由 | 功能 |
|
||
|------|------|------|
|
||
| 文档中心首页 | /help | 分类展示 + 文档列表 |
|
||
| 文档详情页 | /help/:id | Markdown 渲染展示 |
|
||
|
||
**组件说明**
|
||
- `DocumentCenter.vue` - 文档中心首页
|
||
- `DocumentDetail.vue` - 文档详情页（含 marked 渲染）
|
||
|
||
---
|
||
|
||
## 6. 核心功能流程
|
||
|
||
### 6.1 文档创建/编辑流程
|
||
```
|
||
运营用户 → 文档列表页 → 新建/编辑 → Markdown编辑器填写内容 → 保存 → 更新数据库
|
||
```
|
||
|
||
### 6.2 文档查看流程
|
||
```
|
||
普通用户 → 文档中心首页 → 选择分类 → 查看文档列表 → 点击文档 → URL变为 /help/:id → 渲染Markdown正文
|
||
```
|
||
|
||
### 6.3 URL 直接访问流程
|
||
```
|
||
用户访问 /help/123 → 前端路由解析id → 调用API获取文档详情 → 渲染Markdown正文
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 技术实现要点
|
||
|
||
### 7.1 后端实现
|
||
- 在 `txw-yygl-service-biz` 中新建 `DocumentController`、`DocumentService`、`DocumentMapper`
|
||
- 新建 `DocumentCategoryController`、`DocumentCategoryService`、`DocumentCategoryMapper`
|
||
- 使用 MyBatis-Plus 简化 CRUD 操作
|
||
- 事务管理：新建/编辑文档在同一事务中执行
|
||
|
||
### 7.2 前端 Markdown 编辑器
|
||
- 编辑端：使用 `mavon-editor`（支持预览切换、语法高亮）
|
||
- 渲染端：使用 `marked` + `highlight.js`
|
||
|
||
### 7.3 路由配置
|
||
- yygl-web：新增文档管理路由
|
||
- mhzc-web：新增文档中心路由，支持 `/help/:id` 格式
|
||
|
||
---
|
||
|
||
## 8. 目录结构
|
||
|
||
### 8.1 后端（txw-yygl-service-biz）
|
||
|
||
```
|
||
src/main/java/com/css/txw/yygl/
|
||
├── controller/
|
||
│ ├── DocumentController.java
|
||
│ └── DocumentCategoryController.java
|
||
├── service/
|
||
│ ├── DocumentService.java
|
||
│ ├── DocumentServiceImpl.java
|
||
│ ├── DocumentCategoryService.java
|
||
│ └── DocumentCategoryServiceImpl.java
|
||
├── mapper/
|
||
│ ├── DocumentMapper.java
|
||
│ └── DocumentCategoryMapper.java
|
||
├── entity/
|
||
│ ├── Document.java
|
||
│ └── DocumentCategory.java
|
||
└── vo/
|
||
├── DocumentListVO.java
|
||
└── DocumentDetailVO.java
|
||
```
|
||
|
||
### 8.2 前端（txw-yygl-web）
|
||
|
||
```
|
||
src/pages/document/
|
||
├── list/
|
||
│ └── index.vue # 文档列表页
|
||
├── edit/
|
||
│ └── index.vue # 新增/编辑页
|
||
└── category/
|
||
└── index.vue # 分类管理页
|
||
```
|
||
|
||
### 8.3 前端（txw-mhzc-web）
|
||
|
||
```
|
||
src/pages/help/
|
||
├── index.vue # 文档中心首页
|
||
└── detail/
|
||
└── index.vue # 文档详情页
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 测试要点
|
||
|
||
### 9.1 后端测试
|
||
- 分类 CRUD：增删改查、状态切换
|
||
- 文档 CRUD：增删改查、分类关联、状态管理
|
||
- 异常场景：删除有关联文档的分类、查询不存在的文档
|
||
|
||
### 9.2 前端测试
|
||
- Markdown 编辑器：编辑、预览切换
|
||
- 文档列表：分类筛选、状态筛选、分页
|
||
- 文档详情：Markdown 渲染、URL 直接访问
|