fujian_water_biz_doc/DOC_TOOLKIT_GUIDE.md

福建水务营收系统概要设计文档工具链使用指南

一、工具链概述

这是一套完整的系统概要设计文档编写、验证和导出工具链，专门为福建水务营收系统项目设计。工具链包含以下核心功能：

• 📝 文档创建：基于标准模板快速创建符合规范的设计文档
• ✅ 文档验证：自动检查文档格式、结构和内容完整性
• 📄 多格式导出：支持导出为 Word、PDF、HTML 等多种格式
• 🔗 链接检查：验证文档内部链接的有效性
• 📊 图表生成：自动生成架构图、流程图、ER图等
• 🔄 文档合并：将多个文档合并为统一的设计文档

二、快速开始

2.1 初始化工具链

首次使用时，需要初始化工具链配置：

# 方式1：使用 Make
make init

# 方式2：直接运行脚本
chmod +x scripts/doc-toolkit.sh
./scripts/doc-toolkit.sh init

2.2 安装依赖

安装必要的依赖工具：

# 安装 pandoc 和 mermaid-cli
make install-deps

# 或手动安装
brew install pandoc                    # macOS
npm install -g @mermaid-js/mermaid-cli # 图表工具

2.3 创建第一个模块文档

# 创建用户管理模块文档
make create MODULE=user_management

# 创建抄表管理模块文档
make create MODULE=meter_reading

三、完整工作流程

3.1 标准文档编写流程

flowchart TD
    A[初始化工具链] --> B[创建模块文档]
    B --> C[编写文档内容]
    C --> D[验证文档]
    D --> E{验证通过?}
    E -->|否| F[修复问题]
    F --> D
    E -->|是| G[导出文档]
    G --> H[版本控制]

3.2 详细操作步骤

步骤 1：项目初始化

# 1. 初始化配置
make init

# 2. 检查项目状态
make status

# 3. 安装依赖（如需要）
make install-deps

步骤 2：创建文档

# 创建模块设计文档
make create MODULE=模块名称

# 例如：
make create MODULE=user_management
make create MODULE=meter_reading
make create MODULE=billing_management

步骤 3：编写内容

使用任何 Markdown 编辑器（推荐 VS Code）编写文档内容：

# 在 VS Code 中打开文档
code water_biz_user_management_design.md

步骤 4：验证文档

# 验证所有文档
make validate

# 验证特定文档
make validate-file FILE=water_biz_user_management_design.md

# 检查链接有效性
make check-links

步骤 5：导出文档

# 快速构建（HTML格式）
make quick-build

# 完整构建（所有格式）
make full-build

# 单独导出特定格式
make export-word
make export-pdf
make export-html

四、工具链命令参考

4.1 Make 命令

命令	功能	示例
make help	显示帮助信息	make help
make init	初始化工具链	make init
make create MODULE=名称	创建模块文档	make create MODULE=user
make validate	验证所有文档	make validate
make validate-file FILE=文件	验证指定文档	make validate-file FILE=test.md
make export-word	导出Word文档	make export-word
make export-pdf	导出PDF文档	make export-pdf
make export-html	导出HTML文档	make export-html
make check-links	检查链接	make check-links
make merge-docs	合并文档	make merge-docs
make clean	清理临时文件	make clean
make status	查看项目状态	make status

4.2 脚本命令

# 基本语法
./scripts/doc-toolkit.sh [命令] [参数]

# 主要命令
./scripts/doc-toolkit.sh init                    # 初始化
./scripts/doc-toolkit.sh create user_management  # 创建文档
./scripts/doc-toolkit.sh validate               # 验证文档
./scripts/doc-toolkit.sh export word            # 导出Word
./scripts/doc-toolkit.sh generate-diagram architecture  # 生成架构图

4.3 图表生成命令

# 生成架构图
make generate-architecture

# 生成流程图
make generate-flow

# 生成ER图
make generate-er

# 生成时序图
make generate-sequence

五、VS Code 集成

5.1 推荐扩展

工具链已配置了以下推荐扩展：

• Markdown All in One：Markdown 编写增强
• Markdown Preview Enhanced：增强的预览功能
• Markdown Mermaid：Mermaid 图表支持
• markdownlint：Markdown 格式检查
• Code Spell Checker：拼写检查

5.2 快捷任务

在 VS Code 中按 Ctrl+Shift+P（或 Cmd+Shift+P），输入 "Tasks: Run Task"，可以看到以下任务：

• 初始化工具链
• 验证所有文档
• 导出Word文档
• 导出PDF文档
• 导出HTML文档
• 检查链接
• 快速构建
• 完整构建

5.3 配置说明

• 自动预览：编辑 Markdown 时自动显示预览
• 格式检查：实时检查 Markdown 格式问题
• 拼写检查：支持中英文拼写检查
• 代码折叠：支持章节折叠
• 目录生成：自动生成文档目录

六、文档规范

6.1 文件命名规范

water_biz_[模块名]_design.md     # 模块设计文档
water_biz_database_design.md     # 数据库设计文档
water_biz_interface_design.md    # 接口设计文档
water_biz_deployment_design.md   # 部署设计文档

6.2 不要有编号

6.3 必需章节结构

每个模块设计文档必须包含：

1. 功能概述
2. 需求分析
3. 技术架构
4. 功能模块设计
5. 数据库设计
6. 接口设计
7. 安全设计
8. 性能设计
9. 部署设计
10. 测试方案

6.4 图表规范

必须使用 Mermaid 语法：

架构图示例：

graph TD
    A[前端] --> B[后端]
    B --> C[数据库]

ER图示例：

erDiagram
    USER ||--o{ ORDER : places
    USER {
        int id
        string name
    }

七、常见问题

7.1 pandoc 安装问题

问题：pandoc 未安装

解决：

# macOS
brew install pandoc

# Ubuntu/Debian
sudo apt-get install pandoc

# Windows
# 从 https://pandoc.org/installing.html 下载安装包

7.2 中文字体问题

问题：PDF 导出中文显示异常

解决：

# macOS 安装中文字体支持
brew install --cask font-pingfang-sc

# 或修改 pandoc 命令中的字体设置
# 在 doc-toolkit.sh 中修改：
# -V CJKmainfont='PingFang SC'

7.3 权限问题

问题：Permission denied

解决：

# 给脚本添加执行权限
chmod +x scripts/doc-toolkit.sh

# 如果是 macOS，可能需要允许执行
sudo spctl --master-disable  # 临时关闭安全检查

7.4 Mermaid 渲染问题

问题：图表不能正确渲染

解决：

# 安装 mermaid-cli
npm install -g @mermaid-js/mermaid-cli

# 或使用 VS Code 扩展预览
# 安装 "Markdown Preview Enhanced" 扩展

八、高级功能

8.1 自定义模板

可以修改 templates/module_design_template.md 来自定义文档模板：

# 编辑模板文件
code templates/module_design_template.md

# 使用 {{变量名}} 作为占位符
# 例如：{{MODULE_NAME}}, {{MODULE_DESCRIPTION}}

8.2 配置文件

修改 .doc-config.json 来自定义验证规则：

{
  "validation": {
    "min_section_length": 200,
    "required_sections": [
      "功能概述",
      "技术架构"
    ]
  }
}

8.3 样式定制

修改 templates/style.css 来自定义 HTML 输出样式：

body {
    font-family: "PingFang SC", sans-serif;
    line-height: 1.6;
}

h1 {
    color: #2c3e50;
    border-bottom: 3px solid #3498db;
}

九、故障排除

9.1 调试模式

# 启用详细输出
bash -x scripts/doc-toolkit.sh validate

# 查看错误日志
make validate 2>&1 | tee validation.log

9.2 重置工具链

# 清理所有配置和临时文件
make clean
rm -rf templates/
rm -rf output/
rm .doc-config.json

# 重新初始化
make init

9.3 版本兼容性

工具	最低版本	推荐版本
pandoc	2.0+	2.19+
Node.js	14+	18+
mermaid-cli	8.0+	10.0+

十、最佳实践

10.1 文档编写建议

1. 结构清晰：遵循标准章节结构
2. 内容完整：每个章节都要有实质内容
3. 图文并茂：适当使用图表说明
4. 术语统一：使用标准的技术术语
5. 格式规范：遵循 Markdown 格式规范

10.2 版本控制建议

# 提交前验证
make validate

# 生成版本标签
git tag -a v1.0.0 -m "完成用户管理模块设计"

# 推送标签
git push origin v1.0.0

10.3 团队协作建议

1. 分工明确：按模块分配文档编写任务
2. 定期评审：定期运行验证和检查链接
3. 统一标准：所有人使用相同的工具链
4. 及时同步：定期合并和导出完整文档

---

📝 注意：本工具链专为福建水务营收系统设计，但可以适用于其他系统概要设计文档的编写工作。

🚀 开始使用：运行 make init 开始您的文档编写之旅！