xiaoyu/txw
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
daeebcd1d1
txw/docs/superpowers/specs/2026-04-28-平台文档管理功能设计.md

8.0 KiB
Raw Blame History

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

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 响应数据结构

文档列表项（不含正文）

{
  "id": 1,
  "categoryId": 1,
  "categoryName": "使用指南",
  "title": "如何注册账号",
  "status": 1,
  "sort": 1,
  "createTime": "2026-04-28 10:00:00",
  "updateTime": "2026-04-28 10:00:00"
}

文档详情（含正文）

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