html-split

一个用于上传 docx、提取并清洗 OOXML、展示 XML 结构与知识图谱的前后端项目。

当前项目已经支持：

• 上传 docx 文件
• 从 Word 文档中提取主文档 XML
• 对 XML 进行清洗与段落文本合并
• 将标题识别为 h1 - h6
• 在前端展示 XML 原文
• 在前端展示基于 XML 的知识图谱
• 在前端通过 XPath 展示标题层级大纲

技术栈

后端

• Java 17
• Spring Boot 3.3.5
• Apache POI
• docx4j
• Maven

前端

• Vue 3
• Vite
• Vue Flow

项目结构

html-split/
├── backend/                    # Spring Boot 后端
│   ├── pom.xml
│   └── src/main/java/com/htmlsplit/backend
├── frontend/                   # Vue 3 + Vite 前端
│   ├── package.json
│   └── src/
├── package.json                # 根目录联调脚本
└── README.md

核心能力

1. XML 提取与清洗

后端会从上传的 docx 中提取 OOXML 主文档内容，并进行清洗，包括：

• 去除命名空间输出噪音
• 删除技术性属性
• 合并段落中的碎片化文本节点
• 跳过图片、图形、对象等非正文元素
• 根据 outlineLvl / pStyle 将标题段落转换为 h1 - h6

2. 知识图谱展示

前端会基于清洗后的 XML 构建结构图谱，展示：

• 文档根节点
• XML 结构节点
• 标题/段落节点
• 属性与文本片段节点

3. 标题层级大纲

前端新增标题大纲面板，使用 XPath 从清洗后的 XML 中提取：

• //h1
• //h2
• //h3
• //h4
• //h5
• //h6

并按文档顺序展示层级结构。

运行要求

请确保本地已安装：

• Node.js 18+
• npm
• Java 17
• Maven 3.9+

本地启动

方式一：根目录同时启动前后端

在项目根目录执行：

npm install
npm --workspace frontend install
npm run dev

启动后：

• 前端地址：http://localhost:5173
• 后端地址：http://localhost:3001

方式二：分别启动

启动后端

mvn -f backend/pom.xml spring-boot:run

启动前端

npm --workspace frontend install
npm --workspace frontend run dev

构建

前端构建

npm --workspace frontend run build

后端编译

mvn -f backend/pom.xml compile

接口说明

健康检查

GET /api/health

返回示例：

{
  "status": "ok"
}

上传并提取 XML

POST /api/files/upload
Content-Type: multipart/form-data

表单字段：

• file: docx 文件

返回字段示例：

{
  "message": "上传并转换成功",
  "originalFileName": "demo.docx",
  "storedFileName": "uuid.docx",
  "filePath": "backend/uploads/uuid.docx",
  "size": 12345,
  "xmlPartName": "word/document.xml",
  "xmlContent": "<document>...</document>"
}

前端页面说明

当前页面主要包含三个区域：

• 知识图谱：展示 XML 结构关系
• 标题大纲：展示 h1 - h6 层级列表
• XML 展示：展示清洗后的 XML 文本

当前限制

• 当前上传入口仅支持 docx
• 图谱为前端本地根据 XML 生成，不依赖后端图数据库
• 图谱目前仍保留一定节点数量与层级限制，用于保证可视化可读性

后续可扩展方向

• 图谱节点与 XML 文本位置联动
• 标题点击后定位 XML 或图谱节点
• 更完整的 XML 树模式与折叠展开
• 基于 XPath 的更多结构化提取能力

Git 提交规范

当前建议提交格式：

feat(模块描述):实现了什么功能

示例：

feat(document-outline):实现xml标题提取、层级大纲展示与图谱标题识别