294 lines
6.9 KiB
Markdown
294 lines
6.9 KiB
Markdown
# 福建水务营收系统概要设计文档
|
||
|
||
|
||
|
||
|
||
|
||
## 📋 项目概述
|
||
|
||
本项目是福建水务营收系统的概要设计文档，包含完整的系统架构设计、模块设计、数据库设计等内容。项目采用了专业的文档工具链，支持文档的创建、验证、导出等全流程操作。
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 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> |