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

![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)
![Status](https://img.shields.io/badge/status-active-green.svg)
![License](https://img.shields.io/badge/license-MIT-blue.svg)

## 📋 项目概述

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

## 🚀 快速开始

### 1. 初始化工具链

```bash
make init
```

### 2. 创建模块文档

```bash
make create MODULE=user_management
```

### 3. 验证文档

```bash
make validate
```

### 4. 导出文档

```bash
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` |

### 图表生成

```bash
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                   # 快速入门
```

## 🎯 技术架构

### 系统架构

```mermaid
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

## 📋 文档规范

### 标题编号规范

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

### 必需章节结构

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

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

### 图表规范

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

```markdown
```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](LICENSE) 文件。

---

## 🔗 相关链接

- 📖 [完整使用指南](DOC_TOOLKIT_GUIDE.md)
- 🚀 [快速入门](QUICK_START.md)
- 📋 [Cursor Rules](.cursorrules)
- 🎯 [设计计划](water_biz_design_plan.md)

---

<p align="center">
  <strong>🚀 开始使用：</strong>
  <code>make init</code> → 
  <code>make create MODULE=你的模块名</code> → 
  <code>make validate</code> → 
  <code>make export-word</code>
</p>

<p align="center">
  <em>✨ 让文档编写变得简单高效！</em>
</p>