fujian_water_biz_doc/DOC_TOOLKIT_GUIDE.md

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

## 一、工具链概述

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

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

## 二、快速开始

### 2.1 初始化工具链

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

```bash
# 方式1：使用 Make
make init

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

### 2.2 安装依赖

安装必要的依赖工具：

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

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

### 2.3 创建第一个模块文档

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

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

## 三、完整工作流程

### 3.1 标准文档编写流程

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

### 3.2 详细操作步骤

#### 步骤 1：项目初始化
```bash
# 1. 初始化配置
make init

# 2. 检查项目状态
make status

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

#### 步骤 2：创建文档
```bash
# 创建模块设计文档
make create MODULE=模块名称

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

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

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

#### 步骤 4：验证文档
```bash
# 验证所有文档
make validate

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

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

#### 步骤 5：导出文档
```bash
# 快速构建（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 脚本命令

```bash
# 基本语法
./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 图表生成命令

```bash
# 生成架构图
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 文件命名规范

```text
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 语法：

**架构图示例**：
```mermaid
graph TD
    A[前端] --> B[后端]
    B --> C[数据库]
```

**ER图示例**：
```mermaid
erDiagram
    USER ||--o{ ORDER : places
    USER {
        int id
        string name
    }
```

## 七、常见问题

### 7.1 pandoc 安装问题

**问题**：`pandoc 未安装`

**解决**：
```bash
# macOS
brew install pandoc

# Ubuntu/Debian
sudo apt-get install pandoc

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

### 7.2 中文字体问题

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

**解决**：
```bash
# macOS 安装中文字体支持
brew install --cask font-pingfang-sc

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

### 7.3 权限问题

**问题**：`Permission denied`

**解决**：
```bash
# 给脚本添加执行权限
chmod +x scripts/doc-toolkit.sh

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

### 7.4 Mermaid 渲染问题

**问题**：图表不能正确渲染

**解决**：
```bash
# 安装 mermaid-cli
npm install -g @mermaid-js/mermaid-cli

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

## 八、高级功能

### 8.1 自定义模板

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

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

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

### 8.2 配置文件

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

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

### 8.3 样式定制

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

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

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

## 九、故障排除

### 9.1 调试模式

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

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

### 9.2 重置工具链

```bash
# 清理所有配置和临时文件
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 版本控制建议

```bash
# 提交前验证
make validate

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

# 推送标签
git push origin v1.0.0
```

### 10.3 团队协作建议

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

---

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

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