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

9.0 KiB

Raw Permalink Blame History

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

一、工具链概述

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

📝 文档创建：基于标准模板快速创建符合规范的设计文档
✅ 文档验证：自动检查文档格式、结构和内容完整性
📄 多格式导出：支持导出为 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 必需章节结构

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

功能概述
需求分析
技术架构
功能模块设计
数据库设计
接口设计
安全设计
性能设计
部署设计
测试方案

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 文档编写建议

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

10.2 版本控制建议

# 提交前验证
make validate

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

# 推送标签
git push origin v1.0.0

10.3 团队协作建议

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

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

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

9.0 KiB Raw Permalink Blame History Unescape Escape