福建水务营收系统概要设计文档

📋 项目概述

本项目是福建水务营收系统的概要设计文档，包含完整的系统架构设计、模块设计、数据库设计等内容。项目采用了专业的文档工具链，支持文档的创建、验证、导出等全流程操作。

🚀 快速开始

1. 初始化工具链

make init

2. 创建模块文档

make create MODULE=user_management

3. 验证文档

make validate

4. 导出文档

make export-word    # 导出Word文档
make export-html    # 导出HTML文档

🛠️ 工具链功能

核心功能

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

支持的命令

命令	功能	示例
make init	初始化工具链	make init
make create MODULE=名称	创建模块文档	make create MODULE=user
make validate	验证所有文档	make validate
make export-word	导出Word文档	make export-word
make export-pdf	导出PDF文档	make export-pdf
make check-links	检查链接	make check-links
make status	查看项目状态	make status

图表生成

make generate-architecture  # 生成架构图
make generate-flow         # 生成流程图
make generate-er           # 生成ER图
make generate-sequence     # 生成时序图

📚 文档结构

01_doc_preliminary_design/
├── 📄 主要设计文档
│   ├── water_biz_design_plan.md          # 设计计划
│   ├── water_biz_summary.md              # 项目总结
│   ├── water_biz_system_architecture.md  # 系统架构
│   ├── water_biz_module_design.md        # 模块设计
│   ├── water_biz_database_design.md      # 数据库设计
│   ├── water_biz_interface_design.md     # 接口设计
│   └── water_biz_deployment_design.md    # 部署设计
├── 🛠️ 工具链文件
│   ├── scripts/doc-toolkit.sh            # 核心工具脚本
│   ├── Makefile                          # Make命令配置
│   ├── .cursorrules                      # Cursor规则配置
│   └── templates/                        # 文档模板
├── 🔧 配置文件
│   ├── .vscode/                          # VS Code配置
│   ├── .doc-config.json                  # 工具链配置
│   └── .gitignore                        # Git忽略文件
└── 📖 说明文档
    ├── README.md                         # 项目说明
    ├── DOC_TOOLKIT_GUIDE.md             # 完整使用指南
    └── QUICK_START.md                   # 快速入门

🎯 技术架构

系统架构

graph TD
    subgraph "用户层"
        A[Web浏览器]
        B[移动应用]
    end
    
    subgraph "网关层"
        C[API网关]
        D[负载均衡器]
    end
    
    subgraph "应用层"
        E[用户管理服务]
        F[抄表管理服务]
        G[收费管理服务]
        H[账务管理服务]
    end
    
    subgraph "数据层"
        I[MySQL主库]
        J[Redis缓存]
    end
    
    A --> C
    B --> C
    C --> D
    D --> E
    D --> F
    D --> G
    D --> H
    E --> I
    F --> I
    G --> I
    H --> I
    E --> J
    F --> J

技术栈

• 后端框架：RuoYi-Vue-Pro
• 前端框架：yudao-ui-admin-vue3
• 数据库：MySQL 8.0+
• 缓存：Redis
• 文档工具：Pandoc + Mermaid
• 开发工具：VS Code + Cursor

📋 文档规范

标题编号规范

# 一、主要章节
## 1、二级章节
### 1.1、三级章节
#### 1.1.1、四级章节

必需章节结构

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

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

图表规范

所有图表必须使用 Mermaid 语法：

```mermaid
graph TD
    A[开始] --> B[结束]

## 🔧 环境要求

### 必需依赖

- **pandoc** >= 2.0：文档转换工具
- **make**：构建工具
- **bash** >= 4.0：Shell环境
- **git**：版本控制

### 可选依赖

- **mermaid-cli**：图表渲染（用于PDF导出）
- **node.js** >= 14：运行mermaid-cli
- **LaTeX**：PDF生成引擎

### 安装依赖

```bash
# macOS
brew install pandoc make
npm install -g @mermaid-js/mermaid-cli

# Ubuntu/Debian
sudo apt-get install pandoc make
npm install -g @mermaid-js/mermaid-cli

# 或使用工具链自动安装
make install-deps

🎨 VS Code 集成

推荐扩展

项目已配置以下推荐扩展：

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

快捷任务

在 VS Code 中按 Ctrl+Shift+P → "Tasks: Run Task"：

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

📈 使用统计

• 📝 文档数量：13+
• 🔧 工具链命令：15+
• 📊 支持图表类型：4种
• 📄 导出格式：4种
• ⚡ 平均验证时间：< 5秒

🤝 贡献指南

文档编写流程

1. 创建文档：make create MODULE=模块名
2. 编写内容：使用标准模板和规范
3. 验证文档：make validate
4. 提交代码：遵循Git规范

质量标准

• ✅ 通过所有验证检查
• ✅ 包含所有必需章节
• ✅ 图表清晰美观
• ✅ 代码示例完整
• ✅ 术语使用统一

📞 联系方式

• 项目负责人：系统设计团队
• 技术支持：请提交 Issue
• 文档反馈：请提交 Pull Request

📄 许可证

本项目采用 MIT 许可证，详见 LICENSE 文件。

---

🔗 相关链接

• 📖 完整使用指南
• 🚀 快速入门
• 📋 Cursor Rules
• 🎯 设计计划

---

🚀 开始使用： make init → make create MODULE=你的模块名 → make validate → make export-word

✨ 让文档编写变得简单高效！