# 平台文档管理功能设计方案

## 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 直接访问