tangweijie/fujian_water_biz_doc

Fork 0

tangweijie 80df1029b8 refactor(repo): relocate guides api spec and shared assets

2026-03-10 14:32:22 +08:00

5.3 KiB

Raw Permalink Blame History

福建水务营收系统文档导出解决方案

问题描述

在文档转换过程中遇到以下问题：

三级标题样式未渲染：### 标题 格式在转换后样式显示不正确
多文件图表混乱：不同文档的Mermaid图表在转换时位置错乱
转换过程卡住：处理大量图表时工具会卡住不动

解决方案

🎯 核心解决思路

先合并文档，再统一处理图表和格式转换

传统方式是分别处理每个文档，然后合并，这样会导致图表编号混乱和样式不一致。新方案是：

先将所有文档合并为一个完整文档
统一调整标题层级和样式
统一处理所有图表
一次性导出所有格式

🛠️ 技术实现

1. 快速统一导出工具（推荐）

脚本：scripts/quick_unified_export.sh

特点：

✅ 稳定快速，不会卡住
✅ 完美解决三级标题样式问题
✅ 图表保持原始Mermaid代码
✅ 支持HTML中自动渲染图表

使用方法：

# 导出所有格式
make quick-export

# 导出特定格式
make quick-export-docx    # Word文档
make quick-export-pdf     # PDF文档  
make quick-export-html    # HTML文档

2. 完整统一导出工具（高级）

脚本：scripts/unified_export.sh

特点：

✅ 图表转换为PNG图片
✅ 保留原始Mermaid代码
⚠️ 处理大文档时可能卡住

使用方法：

# 导出所有格式（图表转换为图片）
make unified-export

# 导出特定格式
make unified-export-docx
make unified-export-pdf
make unified-export-html

📊 解决效果对比

问题	原始方式	新解决方案	效果
三级标题样式	❌ 样式缺失	✅ 带背景色和边框	完美解决
图表位置混乱	❌ 编号错乱	✅ 统一编号	完美解决
转换卡住	❌ 经常卡住	✅ 稳定快速	完美解决
文档结构	❌ 分散混乱	✅ 统一清晰	大幅改善

🎨 样式优化

三级标题样式修复

CSS样式：

h3 {
    font-size: 14pt;
    font-weight: bold;
    color: #365f91;
    margin-top: 14pt;
    margin-bottom: 8pt;
    background-color: #f8f9fa;
    padding: 6pt 12pt;
    border-left: 4pt solid #365f91;
    page-break-after: avoid;
}

效果：三级标题现在有灰色背景和蓝色左边框，清晰易识别

图表样式优化

Mermaid样式：

.mermaid {
    text-align: center;
    margin: 12pt 0;
    border: 1pt solid #e1e1e1;
    border-radius: 4pt;
    padding: 12pt;
    background-color: #fafafa;
}

📁 输出文件

使用新工具导出的文件：

output/
├── 福建水务营收系统概要设计文档_完整版.docx    # Word文档 (148KB)
├── 福建水务营收系统概要设计文档_完整版.html    # HTML文档 (814KB)
├── 福建水务营收系统概要设计文档_完整版.pdf     # PDF文档 (需要wkhtmltopdf)
├── merged_documents_quick.md                    # 合并的Markdown源文件
└── document_style.css                           # 样式文件

🚀 使用指南

步骤1：选择导出方式

推荐使用快速版本（稳定可靠）：

# 导出所有格式
make quick-export

# 或者只导出Word文档
make quick-export-docx

步骤2：查看输出结果

Word文档：直接打开查看，三级标题有清晰样式
HTML文档：在浏览器中打开，Mermaid图表自动渲染
PDF文档：需要安装wkhtmltopdf工具

步骤3：验证效果

检查以下内容：

✅ 三级标题是否有背景色和边框
✅ 图表是否按正确顺序显示
✅ 文档结构是否清晰
✅ 内容是否完整

🔧 故障排除

问题1：转换卡住

解决：使用快速版本 make quick-export

问题2：图表不显示

Word/PDF：图表以代码形式显示，这是正常的
HTML：确保网络连接正常（需要加载Mermaid.js）

问题3：中文字体问题

解决：系统已配置中文字体支持

macOS：PingFang SC
Windows：Microsoft YaHei
Linux：SimSun

问题4：PDF导出失败

解决：安装wkhtmltopdf

# macOS
brew install wkhtmltopdf

# Ubuntu/Debian
sudo apt-get install wkhtmltopdf

📋 命令速查表

命令	功能	推荐度
`make quick-export`	快速导出所有格式	⭐⭐⭐⭐⭐
`make quick-export-docx`	快速导出Word	⭐⭐⭐⭐⭐
`make quick-export-html`	快速导出HTML	⭐⭐⭐⭐⭐
`make unified-export`	完整导出（图片版）	⭐⭐⭐
`make export-word`	原始Word导出	⭐⭐

💡 最佳实践

首选快速版本：make quick-export-docx 用于日常导出
HTML预览：使用 make quick-export-html 预览效果
批量导出：使用 make quick-export 一次导出所有格式
版本控制：导出的文件可以提交到Git进行版本管理

🎉 总结

通过创建统一的文档导出工具，我们完美解决了：

✅ 三级标题样式渲染问题
✅ 多文件图表位置混乱问题
✅ 转换过程卡住的问题
✅ 文档格式不统一的问题

新工具具有稳定、快速、易用的特点，能够产生高质量的文档输出，满足项目交付要求。

5.3 KiB Raw Permalink Blame History Unescape Escape