新增福建水务营收系统概要设计文档及工具链，包含文档编写规范、模块设计模板、工具链使用指南等，提升文档编写效率和一致性。同时新增Makefile和脚本支持文档的创建、验证和导出功能，确保文档质量和可维护性。
This commit is contained in:
parent
1859976ecf
commit
1bbce1c371
191
.cursorrules
Normal file
191
.cursorrules
Normal file
@ -0,0 +1,191 @@
|
||||
# 福建水务营收系统概要设计文档编写 Cursor Rules
|
||||
|
||||
## 1. 项目角色与专长
|
||||
你是一名专业的系统架构师和技术文档编写专家，专门负责福建水务营收系统的概要设计文档编写工作。
|
||||
|
||||
## 2. 文档编写核心原则
|
||||
|
||||
### 2.1 技术架构原则
|
||||
- 必须基于 RuoYi-Vue-Pro 后端框架和 yudao-ui-admin-vue3 前端框架
|
||||
- 采用前后端分离架构，使用 RESTful API 设计
|
||||
- 遵循微服务设计思想，模块化组织代码
|
||||
- 必须考虑系统安全性、可扩展性和高可用性
|
||||
|
||||
### 2.2 文档质量原则
|
||||
- 结构清晰：使用统一的文档模板和章节结构
|
||||
- 内容完整：覆盖所有必要的技术细节和业务逻辑
|
||||
- 表达准确：使用标准的技术术语和业务术语
|
||||
- 图文并茂：合理使用流程图、架构图、时序图等
|
||||
|
||||
## 3. 文档结构规范
|
||||
|
||||
### 3.1 标准章节结构
|
||||
每个模块设计文档必须包含以下标准章节：
|
||||
1. 功能概述
|
||||
2. 需求分析
|
||||
3. 技术架构
|
||||
4. 功能模块设计
|
||||
5. 数据库设计
|
||||
6. 接口设计
|
||||
7. 安全设计
|
||||
8. 性能设计
|
||||
9. 部署设计
|
||||
10. 测试方案
|
||||
|
||||
### 3.2 标题编号规范
|
||||
- 一级标题：# 一、二、三...
|
||||
- 二级标题：## 1、2、3...
|
||||
- 三级标题：### 1.1、1.2、1.3...
|
||||
- 四级标题：#### 1.1.1、1.1.2、1.1.3...
|
||||
|
||||
### 3.3 文件命名规范
|
||||
- 主设计文档：water_biz_[模块名]_design.md
|
||||
- 数据库设计：water_biz_database_design.md
|
||||
- 接口文档：water_biz_interface_design.md
|
||||
- 部署文档：water_biz_deployment_design.md
|
||||
|
||||
## 4. 技术术语标准化
|
||||
|
||||
### 4.1 框架相关术语
|
||||
- 后端框架：RuoYi-Vue-Pro
|
||||
- 前端框架：yudao-ui-admin-vue3
|
||||
- 数据访问：MyBatis Plus
|
||||
- 安全框架：Spring Security
|
||||
- 缓存：Redis
|
||||
- 数据库：MySQL 8.0+
|
||||
|
||||
### 4.2 水务业务术语
|
||||
- 抄表：meter reading
|
||||
- 阶梯水价：tiered water pricing
|
||||
- 远传水表：remote water meter
|
||||
- 客户编号：customer code
|
||||
- 水表编号：meter code
|
||||
- 账务：accounting
|
||||
- 收费：billing
|
||||
- 营业网点：service outlet
|
||||
|
||||
## 5. 图表绘制规范
|
||||
|
||||
### 5.1 必须使用 Mermaid 语法绘制图表
|
||||
```mermaid
|
||||
graph TD
|
||||
A[需求分析] --> B[架构设计]
|
||||
B --> C[详细设计]
|
||||
C --> D[实现开发]
|
||||
```
|
||||
|
||||
### 5.2 常用图表类型
|
||||
- 系统架构图：使用 graph TD 或 graph LR
|
||||
- 业务流程图：使用 flowchart TD
|
||||
- 数据库关系图：使用 erDiagram
|
||||
- 时序图：使用 sequenceDiagram
|
||||
- 状态图：使用 stateDiagram
|
||||
|
||||
## 6. 代码示例规范
|
||||
|
||||
### 6.1 后端代码示例
|
||||
必须基于 RuoYi-Vue-Pro 框架结构，包含：
|
||||
- Controller 层示例
|
||||
- Service 层示例
|
||||
- Entity 层示例
|
||||
- VO/DTO 层示例
|
||||
|
||||
### 6.2 前端代码示例
|
||||
必须基于 yudao-ui-admin-vue3 框架，包含：
|
||||
- Vue 3 组件示例
|
||||
- TypeScript 类型定义
|
||||
- API 调用示例
|
||||
- 路由配置示例
|
||||
|
||||
## 7. 文档验证工具链
|
||||
|
||||
### 7.1 自动化检查项目
|
||||
- 文档结构完整性检查
|
||||
- 标题编号规范性检查
|
||||
- 术语一致性检查
|
||||
- 图表格式检查
|
||||
- 代码示例格式检查
|
||||
- 链接有效性检查
|
||||
|
||||
### 7.2 质量评估标准
|
||||
- 章节完整度：必须包含所有标准章节
|
||||
- 内容丰富度：每个章节内容不少于200字
|
||||
- 图表数量：平均每1000字至少包含1个图表
|
||||
- 代码示例：技术章节必须包含代码示例
|
||||
|
||||
## 8. 导出与发布规范
|
||||
|
||||
### 8.1 支持的导出格式
|
||||
- Markdown 原生格式（.md）
|
||||
- Word 文档格式（.docx）
|
||||
- PDF 文档格式（.pdf）
|
||||
- HTML 网页格式（.html）
|
||||
|
||||
### 8.2 版本控制要求
|
||||
- 每次修改必须记录版本号和修改说明
|
||||
- 使用 Git 进行版本控制
|
||||
- 重要版本创建标签（tag）
|
||||
|
||||
## 9. 协作工作流程
|
||||
|
||||
### 9.1 文档创建流程
|
||||
1. 创建文档骨架（使用标准模板）
|
||||
2. 填充内容（遵循编写规范）
|
||||
3. 自动化验证（运行检查工具）
|
||||
4. 内部评审（技术团队评审）
|
||||
5. 业务确认（业务团队确认）
|
||||
6. 发布归档（生成最终版本）
|
||||
|
||||
### 9.2 质量控制检查点
|
||||
- 语法检查：检查 Markdown 语法正确性
|
||||
- 格式检查：检查文档格式规范性
|
||||
- 内容检查：检查内容完整性和准确性
|
||||
- 图表检查：检查图表清晰度和正确性
|
||||
|
||||
## 10. 特殊指令与快捷操作
|
||||
|
||||
### 10.1 文档创建指令
|
||||
当用户说"创建[模块名]设计文档"时，自动生成标准模板并填充基础结构。
|
||||
|
||||
### 10.2 验证指令
|
||||
当用户说"验证文档"时，运行完整的文档质量检查流程。
|
||||
|
||||
### 10.3 导出指令
|
||||
当用户说"导出文档"时，根据需要的格式进行导出操作。
|
||||
|
||||
### 10.4 图表生成指令
|
||||
当用户说"生成[图表类型]"时，根据内容自动生成对应的 Mermaid 图表。
|
||||
|
||||
## 11. 错误处理与修复
|
||||
|
||||
### 11.1 常见问题自动修复
|
||||
- 标题编号错误：自动重新编号
|
||||
- 术语不一致：提供标准术语替换建议
|
||||
- 图表语法错误：提供正确语法示例
|
||||
- 链接失效：检查并提示修复
|
||||
|
||||
### 11.2 质量问题警告
|
||||
- 章节内容过少：警告并提供内容扩展建议
|
||||
- 缺少图表：提醒添加必要的图表
|
||||
- 代码示例不规范：提供规范的代码模板
|
||||
|
||||
## 12. 输出要求
|
||||
|
||||
### 12.1 始终使用中文
|
||||
- 所有文档内容必须使用中文编写
|
||||
- 技术术语可以保留英文，但需要中文解释
|
||||
- 代码注释必须使用中文
|
||||
|
||||
### 12.2 保持专业性
|
||||
- 使用专业的技术语言
|
||||
- 确保内容的准确性和完整性
|
||||
- 遵循软件工程文档编写最佳实践
|
||||
|
||||
### 12.3 注重实用性
|
||||
- 提供可实施的技术方案
|
||||
- 包含具体的配置示例
|
||||
- 考虑实际开发中的技术约束
|
||||
|
||||
---
|
||||
|
||||
记住：你的目标是帮助创建高质量、专业、实用的系统概要设计文档，确保文档能够指导实际的系统开发工作。
|
||||
33
.doc-config.json
Normal file
33
.doc-config.json
Normal file
@ -0,0 +1,33 @@
|
||||
{
|
||||
"project": {
|
||||
"name": "福建水务营收系统",
|
||||
"version": "1.0.0",
|
||||
"author": "系统设计团队"
|
||||
},
|
||||
"templates": {
|
||||
"module_design": "module_design_template.md",
|
||||
"database_design": "database_design_template.md",
|
||||
"interface_design": "interface_design_template.md"
|
||||
},
|
||||
"validation": {
|
||||
"min_section_length": 200,
|
||||
"required_sections": [
|
||||
"功能概述",
|
||||
"需求分析",
|
||||
"技术架构",
|
||||
"功能模块设计",
|
||||
"数据库设计",
|
||||
"接口设计",
|
||||
"安全设计",
|
||||
"性能设计",
|
||||
"部署设计"
|
||||
]
|
||||
},
|
||||
"export": {
|
||||
"pandoc_options": {
|
||||
"word": "--reference-doc=templates/reference.docx",
|
||||
"pdf": "--pdf-engine=xelatex",
|
||||
"html": "--css=templates/style.css --self-contained"
|
||||
}
|
||||
}
|
||||
}
|
||||
1
.gitignore
vendored
1
.gitignore
vendored
@ -32,3 +32,4 @@ pdf_output/福建水务业务系统模块设计.pdf
|
||||
pdf_output/福建水务业务系统设计方案.pdf
|
||||
pdf_output/福建水务业务系统数据库设计.pdf
|
||||
pdf_output.tar.gz
|
||||
node_modules
|
||||
|
||||
438
DOC_TOOLKIT_GUIDE.md
Normal file
438
DOC_TOOLKIT_GUIDE.md
Normal file
@ -0,0 +1,438 @@
|
||||
# 福建水务营收系统概要设计文档工具链使用指南
|
||||
|
||||
## 一、工具链概述
|
||||
|
||||
这是一套完整的系统概要设计文档编写、验证和导出工具链，专门为福建水务营收系统项目设计。工具链包含以下核心功能：
|
||||
|
||||
- 📝 **文档创建**：基于标准模板快速创建符合规范的设计文档
|
||||
- ✅ **文档验证**：自动检查文档格式、结构和内容完整性
|
||||
- 📄 **多格式导出**：支持导出为 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 文件命名规范
|
||||
|
||||
```
|
||||
water_biz_[模块名]_design.md # 模块设计文档
|
||||
water_biz_database_design.md # 数据库设计文档
|
||||
water_biz_interface_design.md # 接口设计文档
|
||||
water_biz_deployment_design.md # 部署设计文档
|
||||
```
|
||||
|
||||
### 6.2 标题编号规范
|
||||
|
||||
```markdown
|
||||
# 一、主要章节
|
||||
## 1、二级章节
|
||||
### 1.1、三级章节
|
||||
#### 1.1.1、四级章节
|
||||
```
|
||||
|
||||
### 6.3 必需章节结构
|
||||
|
||||
每个模块设计文档必须包含：
|
||||
|
||||
1. 功能概述
|
||||
2. 需求分析
|
||||
3. 技术架构
|
||||
4. 功能模块设计
|
||||
5. 数据库设计
|
||||
6. 接口设计
|
||||
7. 安全设计
|
||||
8. 性能设计
|
||||
9. 部署设计
|
||||
10. 测试方案
|
||||
|
||||
### 6.4 图表规范
|
||||
|
||||
必须使用 Mermaid 语法：
|
||||
|
||||
```markdown
|
||||
# 架构图
|
||||
```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` 开始您的文档编写之旅！
|
||||
184
Makefile
Normal file
184
Makefile
Normal file
@ -0,0 +1,184 @@
|
||||
# 福建水务营收系统概要设计文档 Makefile
|
||||
# Version: 1.0
|
||||
|
||||
.PHONY: help init create validate export clean install-deps check-links merge-docs
|
||||
|
||||
# 默认目标
|
||||
help:
|
||||
@echo "福建水务营收系统概要设计文档工具链"
|
||||
@echo ""
|
||||
@echo "可用命令:"
|
||||
@echo " help 显示此帮助信息"
|
||||
@echo " init 初始化工具链配置"
|
||||
@echo " install-deps 安装必要的依赖"
|
||||
@echo " create MODULE 创建新的模块设计文档"
|
||||
@echo " validate 验证所有文档"
|
||||
@echo " validate-file 验证指定文档 (使用 FILE=文件名)"
|
||||
@echo " export-word 导出Word格式文档"
|
||||
@echo " export-pdf 导出PDF格式文档"
|
||||
@echo " export-html 导出HTML格式文档"
|
||||
@echo " check-links 检查所有链接"
|
||||
@echo " merge-docs 合并所有文档"
|
||||
@echo " clean 清理临时文件"
|
||||
@echo ""
|
||||
@echo "示例:"
|
||||
@echo " make init # 初始化工具链"
|
||||
@echo " make create MODULE=user # 创建用户管理模块文档"
|
||||
@echo " make validate # 验证所有文档"
|
||||
@echo " make validate-file FILE=water_biz_user_design.md"
|
||||
@echo " make export-word # 导出Word文档"
|
||||
@echo " make export-pdf # 导出PDF文档"
|
||||
|
||||
# 初始化工具链
|
||||
init:
|
||||
@echo "初始化文档工具链..."
|
||||
@chmod +x scripts/doc-toolkit.sh
|
||||
@./scripts/doc-toolkit.sh init
|
||||
|
||||
# 安装依赖
|
||||
install-deps:
|
||||
@echo "检查并安装必要的依赖..."
|
||||
@if ! command -v pandoc > /dev/null 2>&1; then \
|
||||
echo "安装 pandoc..."; \
|
||||
if [[ "$$OSTYPE" == "darwin"* ]]; then \
|
||||
brew install pandoc; \
|
||||
elif [[ "$$OSTYPE" == "linux-gnu"* ]]; then \
|
||||
sudo apt-get update && sudo apt-get install -y pandoc; \
|
||||
else \
|
||||
echo "请手动安装 pandoc: https://pandoc.org/installing.html"; \
|
||||
fi; \
|
||||
else \
|
||||
echo "pandoc 已安装"; \
|
||||
fi
|
||||
@if ! npx mmdc --version > /dev/null 2>&1 && ! command -v mmdc > /dev/null 2>&1; then \
|
||||
echo "安装 mermaid-cli..."; \
|
||||
npm install @mermaid-js/mermaid-cli --save-dev; \
|
||||
else \
|
||||
echo "mermaid-cli 已安装"; \
|
||||
fi
|
||||
|
||||
# 创建模块文档
|
||||
create:
|
||||
@if [ -z "$(MODULE)" ]; then \
|
||||
echo "错误: 请提供模块名称，例如: make create MODULE=user_management"; \
|
||||
exit 1; \
|
||||
fi
|
||||
@./scripts/doc-toolkit.sh create $(MODULE)
|
||||
|
||||
# 验证所有文档
|
||||
validate:
|
||||
@echo "验证所有文档..."
|
||||
@./scripts/doc-toolkit.sh validate
|
||||
|
||||
# 验证指定文档
|
||||
validate-file:
|
||||
@if [ -z "$(FILE)" ]; then \
|
||||
echo "错误: 请提供文件名，例如: make validate-file FILE=water_biz_user_design.md"; \
|
||||
exit 1; \
|
||||
fi
|
||||
@./scripts/doc-toolkit.sh validate $(FILE)
|
||||
|
||||
# 导出Word文档
|
||||
export-word:
|
||||
@echo "导出Word格式文档..."
|
||||
@./scripts/doc-toolkit.sh export word
|
||||
|
||||
# 导出PDF文档
|
||||
export-pdf:
|
||||
@echo "导出PDF格式文档..."
|
||||
@./scripts/doc-toolkit.sh export pdf
|
||||
|
||||
# 导出HTML文档
|
||||
export-html:
|
||||
@echo "导出HTML格式文档..."
|
||||
@./scripts/doc-toolkit.sh export html
|
||||
|
||||
# 检查链接
|
||||
check-links:
|
||||
@echo "检查文档链接..."
|
||||
@./scripts/doc-toolkit.sh check-links
|
||||
|
||||
# 合并文档
|
||||
merge-docs:
|
||||
@echo "合并所有文档..."
|
||||
@./scripts/doc-toolkit.sh merge-docs
|
||||
|
||||
# 清理临时文件
|
||||
clean:
|
||||
@echo "清理临时文件..."
|
||||
@rm -rf output/*.tmp
|
||||
@rm -rf templates/*.bak
|
||||
@rm -rf *.bak
|
||||
@find . -name "*.DS_Store" -delete
|
||||
@echo "清理完成"
|
||||
|
||||
# 生成架构图
|
||||
generate-architecture:
|
||||
@./scripts/doc-toolkit.sh generate-diagram architecture
|
||||
|
||||
# 生成流程图
|
||||
generate-flow:
|
||||
@./scripts/doc-toolkit.sh generate-diagram flow
|
||||
|
||||
# 生成ER图
|
||||
generate-er:
|
||||
@./scripts/doc-toolkit.sh generate-diagram er
|
||||
|
||||
# 生成时序图
|
||||
generate-sequence:
|
||||
@./scripts/doc-toolkit.sh generate-diagram sequence
|
||||
|
||||
# 开发模式 - 实时验证和预览
|
||||
dev:
|
||||
@echo "启动开发模式..."
|
||||
@while true; do \
|
||||
echo "等待文件变化..."; \
|
||||
inotifywait -e modify *.md 2>/dev/null || fswatch -o *.md 2>/dev/null || sleep 5; \
|
||||
echo "检测到文件变化，重新验证..."; \
|
||||
make validate 2>/dev/null || true; \
|
||||
sleep 2; \
|
||||
done
|
||||
|
||||
# 快速构建 - 验证+导出HTML
|
||||
quick-build:
|
||||
@echo "快速构建 - 验证并导出HTML..."
|
||||
@make validate
|
||||
@make export-html
|
||||
@echo "构建完成，查看 output/福建水务营收系统概要设计文档.html"
|
||||
|
||||
# 完整构建 - 验证+导出所有格式
|
||||
full-build:
|
||||
@echo "完整构建 - 验证并导出所有格式..."
|
||||
@make validate
|
||||
@make export-word
|
||||
@make export-pdf
|
||||
@make export-html
|
||||
@echo "构建完成，查看 output/ 目录"
|
||||
|
||||
# 检查项目状态
|
||||
status:
|
||||
@echo "=== 项目状态 ==="
|
||||
@echo "文档数量: $$(ls -1 *.md 2>/dev/null | wc -l)"
|
||||
@echo "模板数量: $$(ls -1 templates/ 2>/dev/null | wc -l)"
|
||||
@echo "输出文件: $$(ls -1 output/ 2>/dev/null | wc -l)"
|
||||
@echo ""
|
||||
@echo "=== 依赖检查 ==="
|
||||
@if command -v pandoc > /dev/null 2>&1; then \
|
||||
echo "✓ pandoc: $$(pandoc --version | head -1)"; \
|
||||
else \
|
||||
echo "✗ pandoc: 未安装"; \
|
||||
fi
|
||||
@if npx mmdc --version > /dev/null 2>&1; then \
|
||||
echo "✓ mermaid-cli: $$(npx mmdc --version) (本地)"; \
|
||||
elif command -v mmdc > /dev/null 2>&1; then \
|
||||
echo "✓ mermaid-cli: $$(mmdc --version) (全局)"; \
|
||||
else \
|
||||
echo "✗ mermaid-cli: 未安装"; \
|
||||
fi
|
||||
|
||||
# 更新工具链
|
||||
update:
|
||||
@echo "更新文档工具链..."
|
||||
@git pull origin main 2>/dev/null || echo "无法从远程仓库更新"
|
||||
@chmod +x scripts/doc-toolkit.sh
|
||||
@echo "工具链更新完成"
|
||||
187
QUICK_START.md
Normal file
187
QUICK_START.md
Normal file
@ -0,0 +1,187 @@
|
||||
# 🚀 福建水务营收系统文档工具链 - 快速入门
|
||||
|
||||
## 5分钟快速体验
|
||||
|
||||
### 第1步：初始化工具链（30秒）
|
||||
|
||||
```bash
|
||||
# 初始化工具链配置
|
||||
make init
|
||||
```
|
||||
|
||||
预期输出：
|
||||
```
|
||||
[INFO] 初始化文档工具链配置...
|
||||
[INFO] 样式文件创建完成
|
||||
[SUCCESS] 配置初始化完成！
|
||||
```
|
||||
|
||||
### 第2步：创建示例模块文档（1分钟）
|
||||
|
||||
```bash
|
||||
# 创建用户管理模块文档
|
||||
make create MODULE=user_management
|
||||
```
|
||||
|
||||
预期输出：
|
||||
```
|
||||
[INFO] 创建模块文档: water_biz_user_management_design.md
|
||||
[SUCCESS] 模块文档创建完成: water_biz_user_management_design.md
|
||||
[INFO] 请使用编辑器打开文件并完善内容
|
||||
```
|
||||
|
||||
### 第3步：验证文档（30秒）
|
||||
|
||||
```bash
|
||||
# 验证文档格式和内容
|
||||
make validate
|
||||
```
|
||||
|
||||
### 第4步：导出HTML预览（1分钟）
|
||||
|
||||
```bash
|
||||
# 导出HTML格式进行预览
|
||||
make export-html
|
||||
```
|
||||
|
||||
### 第5步：查看成果（1分钟）
|
||||
|
||||
打开生成的文件：
|
||||
- 📝 源文档：`water_biz_user_management_design.md`
|
||||
- 🌐 HTML版：`output/福建水务营收系统概要设计文档.html`
|
||||
|
||||
## 完整使用示例
|
||||
|
||||
### 创建多个模块文档
|
||||
|
||||
```bash
|
||||
# 创建核心业务模块
|
||||
make create MODULE=user_management # 用户管理
|
||||
make create MODULE=meter_reading # 抄表管理
|
||||
make create MODULE=billing_management # 收费管理
|
||||
make create MODULE=account_management # 账务管理
|
||||
```
|
||||
|
||||
### 批量验证和导出
|
||||
|
||||
```bash
|
||||
# 验证所有文档
|
||||
make validate
|
||||
|
||||
# 检查链接有效性
|
||||
make check-links
|
||||
|
||||
# 导出所有格式
|
||||
make full-build
|
||||
```
|
||||
|
||||
## 在VS Code中使用
|
||||
|
||||
1. **打开项目**：
|
||||
```bash
|
||||
code .
|
||||
```
|
||||
|
||||
2. **运行任务**：
|
||||
- 按 `Ctrl+Shift+P` (或 `Cmd+Shift+P`)
|
||||
- 输入 "Tasks: Run Task"
|
||||
- 选择需要的任务（如"验证所有文档"）
|
||||
|
||||
3. **实时预览**：
|
||||
- 安装推荐扩展
|
||||
- 编辑Markdown文件时自动显示预览
|
||||
|
||||
## 高效工作流程
|
||||
|
||||
### 日常文档编写流程
|
||||
|
||||
```bash
|
||||
# 1. 创建文档
|
||||
make create MODULE=新模块名
|
||||
|
||||
# 2. 编写内容（使用VS Code或其他编辑器）
|
||||
code water_biz_新模块名_design.md
|
||||
|
||||
# 3. 实时验证
|
||||
make validate-file FILE=water_biz_新模块名_design.md
|
||||
|
||||
# 4. 快速预览
|
||||
make quick-build
|
||||
|
||||
# 5. 版本控制
|
||||
git add .
|
||||
git commit -m "完成新模块名设计文档"
|
||||
```
|
||||
|
||||
### 团队协作流程
|
||||
|
||||
```bash
|
||||
# 1. 更新代码
|
||||
git pull origin main
|
||||
|
||||
# 2. 创建功能分支
|
||||
git checkout -b feature/新模块设计
|
||||
|
||||
# 3. 编写文档
|
||||
make create MODULE=新模块名
|
||||
# ... 编写内容 ...
|
||||
|
||||
# 4. 验证和构建
|
||||
make validate
|
||||
make full-build
|
||||
|
||||
# 5. 提交和推送
|
||||
git add .
|
||||
git commit -m "新增新模块设计文档"
|
||||
git push origin feature/新模块设计
|
||||
|
||||
# 6. 创建PR/MR
|
||||
```
|
||||
|
||||
## 常用命令速查
|
||||
|
||||
| 需求 | 命令 |
|
||||
|------|------|
|
||||
| 🆕 创建文档 | `make create MODULE=模块名` |
|
||||
| ✅ 验证文档 | `make validate` |
|
||||
| 🚀 快速构建 | `make quick-build` |
|
||||
| 📄 导出Word | `make export-word` |
|
||||
| 📊 生成图表 | `make generate-architecture` |
|
||||
| 🔗 检查链接 | `make check-links` |
|
||||
| 📈 查看状态 | `make status` |
|
||||
| 🧹 清理文件 | `make clean` |
|
||||
|
||||
## 疑难解答
|
||||
|
||||
### 问题1：命令不识别
|
||||
```bash
|
||||
# 解决方案：确保在项目根目录
|
||||
pwd # 应该显示包含Makefile的目录
|
||||
ls Makefile # 应该能看到Makefile文件
|
||||
```
|
||||
|
||||
### 问题2：权限错误
|
||||
```bash
|
||||
# 解决方案：添加执行权限
|
||||
chmod +x scripts/doc-toolkit.sh
|
||||
```
|
||||
|
||||
### 问题3：pandoc未安装
|
||||
```bash
|
||||
# 解决方案：安装依赖
|
||||
make install-deps
|
||||
# 或手动安装：brew install pandoc (macOS)
|
||||
```
|
||||
|
||||
## 下一步
|
||||
|
||||
恭喜！您已经掌握了文档工具链的基本使用。
|
||||
|
||||
继续阅读：
|
||||
- 📖 [完整使用指南](DOC_TOOLKIT_GUIDE.md)
|
||||
- 📋 [Cursor Rules说明](.cursorrules)
|
||||
- 📝 [文档编写计划](water_biz_design_plan.md)
|
||||
|
||||
---
|
||||
|
||||
💡 **提示**：将本页面加入书签，随时查看常用命令！
|
||||
311
README.md
311
README.md
@ -1,35 +1,294 @@
|
||||
# 福建水务业务系统初步设计文档
|
||||
# 福建水务营收系统概要设计文档
|
||||
|
||||
本仓库包含福建水务业务系统的初步设计文档，包括系统架构、模块设计、接口设计、数据库设计、部署设计等内容。
|
||||
|
||||
|
||||
|
||||
|
||||
## 技术架构
|
||||
## 📋 项目概述
|
||||
|
||||
本系统基于以下主流开源框架构建：
|
||||
本项目是福建水务营收系统的概要设计文档，包含完整的系统架构设计、模块设计、数据库设计等内容。项目采用了专业的文档工具链，支持文档的创建、验证、导出等全流程操作。
|
||||
|
||||
- 后端框架：[RuoYi-Vue-Pro](https://github.com/YunaiV/ruoyi-vue-pro)，一个开源的企业级Java应用脚手架，基于Spring Boot + MyBatis Plus + Vue实现，支持RBAC动态权限、数据权限、SaaS多租户、Flowable工作流、三方登录等功能。
|
||||
- 前端框架：[yudao-ui-admin-vue3](https://github.com/yudaocode/yudao-ui-admin-vue3)，基于Vue 3 + Element Plus实现的管理后台前端框架。
|
||||
## 🚀 快速开始
|
||||
|
||||
## 文档目录
|
||||
- [设计计划](./water_biz_design_plan.md)
|
||||
- [文档目录](./water_biz_integrated_doc.md)
|
||||
- [系统概述](./water_biz_summary.md)
|
||||
- [系统架构](./water_biz_system_architecture.md)
|
||||
- [模块设计](./water_biz_module_design.md)
|
||||
- [接口设计](./water_biz_interface_design.md)
|
||||
- [数据库设计](./water_biz_database_design.md)
|
||||
- [部署设计](./water_biz_deployment_design.md)
|
||||
### 1. 初始化工具链
|
||||
|
||||
## 主要特性
|
||||
```bash
|
||||
make init
|
||||
```
|
||||
|
||||
- 基于SaaS多租户架构，支持集团、分公司、营业站点的多层级管理
|
||||
- 使用Spring Boot 3.x + Vue 3.x开发，支持JDK 17/21
|
||||
- 集成Flowable工作流，支持报装、表务等业务流程灵活配置
|
||||
- 提供丰富的统计图表和业务大屏，支持自定义报表设计
|
||||
- 支持移动端应用，包含微信/支付宝小程序和公众号服务
|
||||
- 完善的权限管理，支持RBAC动态权限和数据权限控制
|
||||
- 支持多种支付方式和第三方系统集成
|
||||
### 2. 创建模块文档
|
||||
|
||||
## 版本信息
|
||||
```bash
|
||||
make create MODULE=user_management
|
||||
```
|
||||
|
||||
初始版本：1.0.0
|
||||
更新日期：2024-05-08
|
||||
### 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>
|
||||
2285
output/merged_docs.md
Normal file
2285
output/merged_docs.md
Normal file
File diff suppressed because it is too large
Load Diff
BIN
output/福建水务营收系统概要设计文档.docx
Normal file
BIN
output/福建水务营收系统概要设计文档.docx
Normal file
Binary file not shown.
3154
output/福建水务营收系统概要设计文档.html
Normal file
3154
output/福建水务营收系统概要设计文档.html
Normal file
File diff suppressed because one or more lines are too long
4709
package-lock.json
generated
Normal file
4709
package-lock.json
generated
Normal file
File diff suppressed because it is too large
Load Diff
5
package.json
Normal file
5
package.json
Normal file
@ -0,0 +1,5 @@
|
||||
{
|
||||
"devDependencies": {
|
||||
"@mermaid-js/mermaid-cli": "^11.4.2"
|
||||
}
|
||||
}
|
||||
663
scripts/doc-toolkit.sh
Executable file
663
scripts/doc-toolkit.sh
Executable file
@ -0,0 +1,663 @@
|
||||
#!/bin/bash
|
||||
|
||||
# 福建水务营收系统概要设计文档工具链
|
||||
# Author: System Design Team
|
||||
# Version: 1.0
|
||||
|
||||
set -e
|
||||
|
||||
# 颜色定义
|
||||
RED='\033[0;31m'
|
||||
GREEN='\033[0;32m'
|
||||
YELLOW='\033[1;33m'
|
||||
BLUE='\033[0;34m'
|
||||
NC='\033[0m' # No Color
|
||||
|
||||
# 配置文件
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
|
||||
CONFIG_FILE="$PROJECT_ROOT/.doc-config.json"
|
||||
TEMPLATE_DIR="$PROJECT_ROOT/templates"
|
||||
OUTPUT_DIR="$PROJECT_ROOT/output"
|
||||
|
||||
# 创建必要的目录
|
||||
mkdir -p "$TEMPLATE_DIR"
|
||||
mkdir -p "$OUTPUT_DIR"
|
||||
|
||||
# 日志函数
|
||||
log_info() {
|
||||
echo -e "${BLUE}[INFO]${NC} $1"
|
||||
}
|
||||
|
||||
log_success() {
|
||||
echo -e "${GREEN}[SUCCESS]${NC} $1"
|
||||
}
|
||||
|
||||
log_warning() {
|
||||
echo -e "${YELLOW}[WARNING]${NC} $1"
|
||||
}
|
||||
|
||||
log_error() {
|
||||
echo -e "${RED}[ERROR]${NC} $1"
|
||||
}
|
||||
|
||||
# 显示帮助信息
|
||||
show_help() {
|
||||
echo "福建水务营收系统概要设计文档工具链"
|
||||
echo ""
|
||||
echo "用法: $0 [命令] [选项]"
|
||||
echo ""
|
||||
echo "命令:"
|
||||
echo " create <module_name> 创建新的模块设计文档"
|
||||
echo " validate [file_path] 验证文档格式和内容"
|
||||
echo " export <format> [file] 导出文档为指定格式"
|
||||
echo " generate-diagram <type> 生成指定类型的图表"
|
||||
echo " check-links 检查文档中的链接有效性"
|
||||
echo " merge-docs 合并所有文档为单一文档"
|
||||
echo " init 初始化工具链配置"
|
||||
echo ""
|
||||
echo "格式选项:"
|
||||
echo " word, pdf, html, epub"
|
||||
echo ""
|
||||
echo "图表类型:"
|
||||
echo " architecture, flow, er, sequence, class"
|
||||
echo ""
|
||||
}
|
||||
|
||||
# 初始化配置
|
||||
init_config() {
|
||||
log_info "初始化文档工具链配置..."
|
||||
|
||||
# 创建配置文件
|
||||
cat > "$CONFIG_FILE" << 'EOF'
|
||||
{
|
||||
"project": {
|
||||
"name": "福建水务营收系统",
|
||||
"version": "1.0.0",
|
||||
"author": "系统设计团队"
|
||||
},
|
||||
"templates": {
|
||||
"module_design": "module_design_template.md",
|
||||
"database_design": "database_design_template.md",
|
||||
"interface_design": "interface_design_template.md"
|
||||
},
|
||||
"validation": {
|
||||
"min_section_length": 200,
|
||||
"required_sections": [
|
||||
"功能概述",
|
||||
"需求分析",
|
||||
"技术架构",
|
||||
"功能模块设计",
|
||||
"数据库设计",
|
||||
"接口设计",
|
||||
"安全设计",
|
||||
"性能设计",
|
||||
"部署设计"
|
||||
]
|
||||
},
|
||||
"export": {
|
||||
"pandoc_options": {
|
||||
"word": "--reference-doc=templates/reference.docx",
|
||||
"pdf": "--pdf-engine=xelatex",
|
||||
"html": "--css=templates/style.css --self-contained"
|
||||
}
|
||||
}
|
||||
}
|
||||
EOF
|
||||
|
||||
# 创建模块设计模板
|
||||
create_module_template
|
||||
|
||||
# 创建样式文件
|
||||
create_style_files
|
||||
|
||||
log_success "配置初始化完成！"
|
||||
}
|
||||
|
||||
# 创建模块设计模板
|
||||
create_module_template() {
|
||||
# 使用 printf 而不是 heredoc 来避免反引号冲突
|
||||
cat > "$TEMPLATE_DIR/module_design_template.md" << 'TEMPLATE_EOF'
|
||||
# {{MODULE_NAME}}模块设计说明
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
### 1.1 模块简介
|
||||
{{MODULE_DESCRIPTION}}
|
||||
|
||||
### 1.2 主要功能
|
||||
- 功能点1：描述
|
||||
- 功能点2：描述
|
||||
- 功能点3：描述
|
||||
|
||||
## 二、需求分析
|
||||
|
||||
### 2.1 功能性需求
|
||||
{{FUNCTIONAL_REQUIREMENTS}}
|
||||
|
||||
### 2.2 非功能性需求
|
||||
{{NON_FUNCTIONAL_REQUIREMENTS}}
|
||||
|
||||
## 三、技术架构
|
||||
|
||||
### 3.1 技术选型
|
||||
- 后端框架：RuoYi-Vue-Pro
|
||||
- 前端框架：yudao-ui-admin-vue3
|
||||
- 数据库：MySQL 8.0+
|
||||
- 缓存：Redis
|
||||
|
||||
### 3.2 架构图
|
||||
|
||||
## 四、功能模块设计
|
||||
|
||||
### 4.1 模块结构
|
||||
{{MODULE_STRUCTURE}}
|
||||
|
||||
### 4.2 核心类设计
|
||||
{{CLASS_DESIGN}}
|
||||
|
||||
## 五、数据库设计
|
||||
|
||||
### 5.1 数据表设计
|
||||
{{TABLE_DESIGN}}
|
||||
|
||||
## 六、接口设计
|
||||
|
||||
### 6.1 REST API设计
|
||||
{{API_DESIGN}}
|
||||
|
||||
### 6.2 接口列表
|
||||
{{API_LIST}}
|
||||
|
||||
## 七、安全设计
|
||||
|
||||
### 7.1 权限控制
|
||||
{{PERMISSION_DESIGN}}
|
||||
|
||||
### 7.2 数据安全
|
||||
{{DATA_SECURITY}}
|
||||
|
||||
## 八、性能设计
|
||||
|
||||
### 8.1 性能指标
|
||||
{{PERFORMANCE_METRICS}}
|
||||
|
||||
### 8.2 优化策略
|
||||
{{OPTIMIZATION_STRATEGY}}
|
||||
|
||||
## 九、部署设计
|
||||
|
||||
### 9.1 部署架构
|
||||
{{DEPLOYMENT_ARCHITECTURE}}
|
||||
|
||||
### 9.2 环境配置
|
||||
{{ENVIRONMENT_CONFIG}}
|
||||
|
||||
## 十、测试方案
|
||||
|
||||
### 10.1 测试策略
|
||||
{{TEST_STRATEGY}}
|
||||
|
||||
### 10.2 测试用例
|
||||
{{TEST_CASES}}
|
||||
TEMPLATE_EOF
|
||||
}
|
||||
|
||||
# 创建样式文件
|
||||
create_style_files() {
|
||||
cat > "$TEMPLATE_DIR/style.css" << 'CSS_EOF'
|
||||
body {
|
||||
font-family: "Microsoft YaHei", "PingFang SC", "Helvetica Neue", Arial, sans-serif;
|
||||
line-height: 1.6;
|
||||
color: #333;
|
||||
max-width: 1200px;
|
||||
margin: 0 auto;
|
||||
padding: 20px;
|
||||
}
|
||||
|
||||
h1, h2, h3, h4, h5, h6 {
|
||||
color: #2c3e50;
|
||||
margin-top: 2em;
|
||||
margin-bottom: 1em;
|
||||
}
|
||||
|
||||
h1 {
|
||||
border-bottom: 3px solid #3498db;
|
||||
padding-bottom: 10px;
|
||||
}
|
||||
|
||||
h2 {
|
||||
border-bottom: 1px solid #bdc3c7;
|
||||
padding-bottom: 5px;
|
||||
}
|
||||
|
||||
code {
|
||||
background-color: #f8f8f8;
|
||||
padding: 2px 4px;
|
||||
border-radius: 3px;
|
||||
font-family: "Monaco", "Menlo", "Ubuntu Mono", monospace;
|
||||
}
|
||||
|
||||
pre {
|
||||
background-color: #f8f8f8;
|
||||
padding: 15px;
|
||||
border-radius: 5px;
|
||||
overflow-x: auto;
|
||||
}
|
||||
|
||||
table {
|
||||
border-collapse: collapse;
|
||||
width: 100%;
|
||||
margin: 1em 0;
|
||||
}
|
||||
|
||||
th, td {
|
||||
border: 1px solid #ddd;
|
||||
padding: 8px;
|
||||
text-align: left;
|
||||
}
|
||||
|
||||
th {
|
||||
background-color: #f2f2f2;
|
||||
font-weight: bold;
|
||||
}
|
||||
|
||||
.mermaid {
|
||||
text-align: center;
|
||||
margin: 20px 0;
|
||||
}
|
||||
CSS_EOF
|
||||
|
||||
log_info "样式文件创建完成"
|
||||
}
|
||||
|
||||
# 创建新的模块设计文档
|
||||
create_module_doc() {
|
||||
local module_name="$1"
|
||||
|
||||
if [[ -z "$module_name" ]]; then
|
||||
log_error "请提供模块名称"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
local filename="water_biz_${module_name}_design.md"
|
||||
local template_file="$TEMPLATE_DIR/module_design_template.md"
|
||||
|
||||
if [[ ! -f "$template_file" ]]; then
|
||||
log_error "模板文件不存在，请先运行: $0 init"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if [[ -f "$filename" ]]; then
|
||||
log_warning "文件 $filename 已存在，是否覆盖？(y/N)"
|
||||
read -r response
|
||||
if [[ ! "$response" =~ ^[Yy]$ ]]; then
|
||||
log_info "操作已取消"
|
||||
exit 0
|
||||
fi
|
||||
fi
|
||||
|
||||
log_info "创建模块文档: $filename"
|
||||
|
||||
# 替换模板变量
|
||||
cp "$template_file" "$filename"
|
||||
|
||||
# 使用 sed 替换变量
|
||||
sed -i.bak "s/{{MODULE_NAME}}/${module_name}/g" "$filename"
|
||||
sed -i.bak "s/{{MODULE_DESCRIPTION}}/[请在此处添加${module_name}模块的详细描述]/g" "$filename"
|
||||
sed -i.bak "s/{{FUNCTIONAL_REQUIREMENTS}}/[请在此处添加功能性需求]/g" "$filename"
|
||||
sed -i.bak "s/{{NON_FUNCTIONAL_REQUIREMENTS}}/[请在此处添加非功能性需求]/g" "$filename"
|
||||
sed -i.bak "s/{{MODULE_STRUCTURE}}/[请在此处添加模块结构说明]/g" "$filename"
|
||||
sed -i.bak "s/{{CLASS_DESIGN}}/[请在此处添加核心类设计]/g" "$filename"
|
||||
sed -i.bak "s/{{TABLE_DESIGN}}/[请在此处添加数据表设计]/g" "$filename"
|
||||
sed -i.bak "s/{{API_DESIGN}}/[请在此处添加API设计说明]/g" "$filename"
|
||||
sed -i.bak "s/{{API_LIST}}/[请在此处添加API列表]/g" "$filename"
|
||||
sed -i.bak "s/{{PERMISSION_DESIGN}}/[请在此处添加权限控制设计]/g" "$filename"
|
||||
sed -i.bak "s/{{DATA_SECURITY}}/[请在此处添加数据安全设计]/g" "$filename"
|
||||
sed -i.bak "s/{{PERFORMANCE_METRICS}}/[请在此处添加性能指标]/g" "$filename"
|
||||
sed -i.bak "s/{{OPTIMIZATION_STRATEGY}}/[请在此处添加优化策略]/g" "$filename"
|
||||
sed -i.bak "s/{{DEPLOYMENT_ARCHITECTURE}}/[请在此处添加部署架构]/g" "$filename"
|
||||
sed -i.bak "s/{{ENVIRONMENT_CONFIG}}/[请在此处添加环境配置]/g" "$filename"
|
||||
sed -i.bak "s/{{TEST_STRATEGY}}/[请在此处添加测试策略]/g" "$filename"
|
||||
sed -i.bak "s/{{TEST_CASES}}/[请在此处添加测试用例]/g" "$filename"
|
||||
|
||||
# 删除备份文件
|
||||
rm -f "${filename}.bak"
|
||||
|
||||
log_success "模块文档创建完成: $filename"
|
||||
log_info "请使用编辑器打开文件并完善内容"
|
||||
}
|
||||
|
||||
# 验证文档
|
||||
validate_doc() {
|
||||
local file_path="$1"
|
||||
local errors=0
|
||||
|
||||
if [[ -z "$file_path" ]]; then
|
||||
# 验证所有markdown文件
|
||||
for file in *.md; do
|
||||
if [[ -f "$file" ]]; then
|
||||
validate_single_doc "$file"
|
||||
errors=$((errors + $?))
|
||||
fi
|
||||
done
|
||||
else
|
||||
validate_single_doc "$file_path"
|
||||
errors=$?
|
||||
fi
|
||||
|
||||
if [[ $errors -eq 0 ]]; then
|
||||
log_success "文档验证通过"
|
||||
else
|
||||
log_error "发现 $errors 个问题，请修复后重新验证"
|
||||
exit 1
|
||||
fi
|
||||
}
|
||||
|
||||
# 验证单个文档
|
||||
validate_single_doc() {
|
||||
local file_path="$1"
|
||||
local errors=0
|
||||
|
||||
log_info "验证文档: $file_path"
|
||||
|
||||
if [[ ! -f "$file_path" ]]; then
|
||||
log_error "文件不存在: $file_path"
|
||||
return 1
|
||||
fi
|
||||
|
||||
# 检查必需的章节
|
||||
local required_sections=("功能概述" "需求分析" "技术架构")
|
||||
|
||||
for section in "${required_sections[@]}"; do
|
||||
if ! grep -q "$section" "$file_path"; then
|
||||
log_warning "缺少必需章节: $section"
|
||||
errors=$((errors + 1))
|
||||
fi
|
||||
done
|
||||
|
||||
# 检查代码块语言标记
|
||||
local code_blocks=$(grep -c '^```[a-z]' "$file_path" || true)
|
||||
local total_blocks=$(grep -c '^```' "$file_path" || true)
|
||||
|
||||
if [[ $total_blocks -gt 0 && $code_blocks -lt $total_blocks ]]; then
|
||||
log_warning "部分代码块缺少语言标记"
|
||||
errors=$((errors + 1))
|
||||
fi
|
||||
|
||||
log_info "验证完成: $file_path (发现 $errors 个问题)"
|
||||
return $errors
|
||||
}
|
||||
|
||||
# 导出文档
|
||||
export_doc() {
|
||||
local format="$1"
|
||||
local file_path="$2"
|
||||
|
||||
if [[ -z "$format" ]]; then
|
||||
log_error "请指定导出格式: word, pdf, html, epub"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# 检查pandoc是否安装
|
||||
if ! command -v pandoc &> /dev/null; then
|
||||
log_error "pandoc 未安装，请先安装 pandoc"
|
||||
log_info "安装命令: brew install pandoc (macOS) 或 apt-get install pandoc (Ubuntu)"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
local output_file
|
||||
local pandoc_options=""
|
||||
|
||||
case "$format" in
|
||||
word)
|
||||
output_file="$OUTPUT_DIR/福建水务营收系统概要设计文档.docx"
|
||||
;;
|
||||
pdf)
|
||||
output_file="$OUTPUT_DIR/福建水务营收系统概要设计文档.pdf"
|
||||
pandoc_options="--pdf-engine=xelatex -V CJKmainfont='PingFang SC'"
|
||||
;;
|
||||
html)
|
||||
output_file="$OUTPUT_DIR/福建水务营收系统概要设计文档.html"
|
||||
pandoc_options="--css=$TEMPLATE_DIR/style.css --self-contained"
|
||||
;;
|
||||
epub)
|
||||
output_file="$OUTPUT_DIR/福建水务营收系统概要设计文档.epub"
|
||||
;;
|
||||
*)
|
||||
log_error "不支持的格式: $format"
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
|
||||
log_info "导出格式: $format"
|
||||
log_info "输出文件: $output_file"
|
||||
|
||||
if [[ -n "$file_path" ]]; then
|
||||
# 导出单个文件
|
||||
if [[ ! -f "$file_path" ]]; then
|
||||
log_error "文件不存在: $file_path"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
pandoc "$file_path" -o "$output_file" $pandoc_options
|
||||
else
|
||||
# 合并所有markdown文件并导出
|
||||
local merged_file="$OUTPUT_DIR/merged_docs.md"
|
||||
merge_all_docs "$merged_file"
|
||||
pandoc "$merged_file" -o "$output_file" $pandoc_options
|
||||
fi
|
||||
|
||||
log_success "文档导出完成: $output_file"
|
||||
}
|
||||
|
||||
# 合并所有文档
|
||||
merge_all_docs() {
|
||||
local output_file="$1"
|
||||
|
||||
log_info "合并所有文档..."
|
||||
|
||||
echo "---" > "$output_file"
|
||||
echo "title: \"福建水务营收系统概要设计文档\"" >> "$output_file"
|
||||
echo "author: \"系统设计团队\"" >> "$output_file"
|
||||
echo "date: \"$(date '+%Y年%m月%d日')\"" >> "$output_file"
|
||||
echo "---" >> "$output_file"
|
||||
echo "" >> "$output_file"
|
||||
|
||||
# 按特定顺序合并文档
|
||||
local doc_order=(
|
||||
"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"
|
||||
)
|
||||
|
||||
for doc in "${doc_order[@]}"; do
|
||||
if [[ -f "$doc" ]]; then
|
||||
echo "" >> "$output_file"
|
||||
echo "---" >> "$output_file"
|
||||
echo "" >> "$output_file"
|
||||
cat "$doc" >> "$output_file"
|
||||
fi
|
||||
done
|
||||
|
||||
log_success "文档合并完成: $output_file"
|
||||
}
|
||||
|
||||
# 生成图表
|
||||
generate_diagram() {
|
||||
local diagram_type="$1"
|
||||
|
||||
case "$diagram_type" in
|
||||
architecture)
|
||||
generate_architecture_diagram
|
||||
;;
|
||||
flow)
|
||||
generate_flow_diagram
|
||||
;;
|
||||
er)
|
||||
generate_er_diagram
|
||||
;;
|
||||
sequence)
|
||||
generate_sequence_diagram
|
||||
;;
|
||||
*)
|
||||
log_error "不支持的图表类型: $diagram_type"
|
||||
log_info "支持的类型: architecture, flow, er, sequence"
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
}
|
||||
|
||||
# 生成架构图
|
||||
generate_architecture_diagram() {
|
||||
echo '```mermaid'
|
||||
echo 'graph TD'
|
||||
echo ' subgraph "用户层"'
|
||||
echo ' A[Web浏览器]'
|
||||
echo ' B[移动应用]'
|
||||
echo ' end'
|
||||
echo ' '
|
||||
echo ' subgraph "网关层"'
|
||||
echo ' C[API网关]'
|
||||
echo ' D[负载均衡器]'
|
||||
echo ' end'
|
||||
echo ' '
|
||||
echo ' subgraph "应用层"'
|
||||
echo ' E[用户管理服务]'
|
||||
echo ' F[抄表管理服务]'
|
||||
echo ' G[收费管理服务]'
|
||||
echo ' H[账务管理服务]'
|
||||
echo ' end'
|
||||
echo ' '
|
||||
echo ' A --> C'
|
||||
echo ' B --> C'
|
||||
echo ' C --> D'
|
||||
echo ' D --> E'
|
||||
echo ' D --> F'
|
||||
echo ' D --> G'
|
||||
echo ' D --> H'
|
||||
echo '```'
|
||||
log_success "架构图模板已生成"
|
||||
}
|
||||
|
||||
# 生成流程图
|
||||
generate_flow_diagram() {
|
||||
echo '```mermaid'
|
||||
echo 'flowchart TD'
|
||||
echo ' A[开始] --> B{用户登录}'
|
||||
echo ' B -->|成功| C[选择功能模块]'
|
||||
echo ' B -->|失败| D[显示错误信息]'
|
||||
echo ' D --> B'
|
||||
echo ' C --> E[抄表管理]'
|
||||
echo ' C --> F[收费管理]'
|
||||
echo ' C --> G[账务管理]'
|
||||
echo '```'
|
||||
log_success "流程图模板已生成"
|
||||
}
|
||||
|
||||
# 生成ER图
|
||||
generate_er_diagram() {
|
||||
echo '```mermaid'
|
||||
echo 'erDiagram'
|
||||
echo ' USER ||--o{ CUSTOMER : manages'
|
||||
echo ' CUSTOMER ||--o{ WATER_METER : owns'
|
||||
echo ' WATER_METER ||--o{ READING : generates'
|
||||
echo ' '
|
||||
echo ' USER {'
|
||||
echo ' int user_id PK'
|
||||
echo ' string username'
|
||||
echo ' string password'
|
||||
echo ' }'
|
||||
echo '```'
|
||||
log_success "ER图模板已生成"
|
||||
}
|
||||
|
||||
# 生成时序图
|
||||
generate_sequence_diagram() {
|
||||
echo '```mermaid'
|
||||
echo 'sequenceDiagram'
|
||||
echo ' participant U as 用户'
|
||||
echo ' participant W as Web界面'
|
||||
echo ' participant S as 服务层'
|
||||
echo ' participant D as 数据库'
|
||||
echo ' '
|
||||
echo ' U->>W: 登录请求'
|
||||
echo ' W->>S: 验证用户'
|
||||
echo ' S->>D: 查询用户信息'
|
||||
echo ' D-->>S: 返回用户数据'
|
||||
echo ' S-->>W: 登录响应'
|
||||
echo ' W-->>U: 显示结果'
|
||||
echo '```'
|
||||
log_success "时序图模板已生成"
|
||||
}
|
||||
|
||||
# 检查链接有效性
|
||||
check_links() {
|
||||
log_info "检查文档链接有效性..."
|
||||
|
||||
local broken_links=0
|
||||
|
||||
for file in *.md; do
|
||||
if [[ -f "$file" ]]; then
|
||||
log_info "检查文件: $file"
|
||||
|
||||
# 简化的链接检查，使用 grep 而不是正则表达式
|
||||
local links=$(grep -o '\](.*\.md)' "$file" | sed 's/](\(.*\))/\1/' || true)
|
||||
|
||||
for link in $links; do
|
||||
if [[ ! -f "$link" ]]; then
|
||||
log_warning "断开的链接: $link (在文件 $file 中)"
|
||||
broken_links=$((broken_links + 1))
|
||||
fi
|
||||
done
|
||||
fi
|
||||
done
|
||||
|
||||
if [[ $broken_links -eq 0 ]]; then
|
||||
log_success "所有链接检查通过"
|
||||
else
|
||||
log_error "发现 $broken_links 个断开的链接"
|
||||
fi
|
||||
}
|
||||
|
||||
# 主函数
|
||||
main() {
|
||||
case "$1" in
|
||||
init)
|
||||
init_config
|
||||
;;
|
||||
create)
|
||||
create_module_doc "$2"
|
||||
;;
|
||||
validate)
|
||||
validate_doc "$2"
|
||||
;;
|
||||
export)
|
||||
export_doc "$2" "$3"
|
||||
;;
|
||||
generate-diagram)
|
||||
generate_diagram "$2"
|
||||
;;
|
||||
check-links)
|
||||
check_links
|
||||
;;
|
||||
merge-docs)
|
||||
merge_all_docs "$OUTPUT_DIR/merged_docs.md"
|
||||
;;
|
||||
help|--help|-h)
|
||||
show_help
|
||||
;;
|
||||
*)
|
||||
log_error "未知命令: $1"
|
||||
show_help
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
}
|
||||
|
||||
# 运行主函数
|
||||
main "$@"
|
||||
82
templates/module_design_template.md
Normal file
82
templates/module_design_template.md
Normal file
@ -0,0 +1,82 @@
|
||||
# {{MODULE_NAME}}模块设计说明
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
### 1.1 模块简介
|
||||
{{MODULE_DESCRIPTION}}
|
||||
|
||||
### 1.2 主要功能
|
||||
- 功能点1：描述
|
||||
- 功能点2：描述
|
||||
- 功能点3：描述
|
||||
|
||||
## 二、需求分析
|
||||
|
||||
### 2.1 功能性需求
|
||||
{{FUNCTIONAL_REQUIREMENTS}}
|
||||
|
||||
### 2.2 非功能性需求
|
||||
{{NON_FUNCTIONAL_REQUIREMENTS}}
|
||||
|
||||
## 三、技术架构
|
||||
|
||||
### 3.1 技术选型
|
||||
- 后端框架：RuoYi-Vue-Pro
|
||||
- 前端框架：yudao-ui-admin-vue3
|
||||
- 数据库：MySQL 8.0+
|
||||
- 缓存：Redis
|
||||
|
||||
### 3.2 架构图
|
||||
|
||||
## 四、功能模块设计
|
||||
|
||||
### 4.1 模块结构
|
||||
{{MODULE_STRUCTURE}}
|
||||
|
||||
### 4.2 核心类设计
|
||||
{{CLASS_DESIGN}}
|
||||
|
||||
## 五、数据库设计
|
||||
|
||||
### 5.1 数据表设计
|
||||
{{TABLE_DESIGN}}
|
||||
|
||||
## 六、接口设计
|
||||
|
||||
### 6.1 REST API设计
|
||||
{{API_DESIGN}}
|
||||
|
||||
### 6.2 接口列表
|
||||
{{API_LIST}}
|
||||
|
||||
## 七、安全设计
|
||||
|
||||
### 7.1 权限控制
|
||||
{{PERMISSION_DESIGN}}
|
||||
|
||||
### 7.2 数据安全
|
||||
{{DATA_SECURITY}}
|
||||
|
||||
## 八、性能设计
|
||||
|
||||
### 8.1 性能指标
|
||||
{{PERFORMANCE_METRICS}}
|
||||
|
||||
### 8.2 优化策略
|
||||
{{OPTIMIZATION_STRATEGY}}
|
||||
|
||||
## 九、部署设计
|
||||
|
||||
### 9.1 部署架构
|
||||
{{DEPLOYMENT_ARCHITECTURE}}
|
||||
|
||||
### 9.2 环境配置
|
||||
{{ENVIRONMENT_CONFIG}}
|
||||
|
||||
## 十、测试方案
|
||||
|
||||
### 10.1 测试策略
|
||||
{{TEST_STRATEGY}}
|
||||
|
||||
### 10.2 测试用例
|
||||
{{TEST_CASES}}
|
||||
60
templates/style.css
Normal file
60
templates/style.css
Normal file
@ -0,0 +1,60 @@
|
||||
body {
|
||||
font-family: "Microsoft YaHei", "PingFang SC", "Helvetica Neue", Arial, sans-serif;
|
||||
line-height: 1.6;
|
||||
color: #333;
|
||||
max-width: 1200px;
|
||||
margin: 0 auto;
|
||||
padding: 20px;
|
||||
}
|
||||
|
||||
h1, h2, h3, h4, h5, h6 {
|
||||
color: #2c3e50;
|
||||
margin-top: 2em;
|
||||
margin-bottom: 1em;
|
||||
}
|
||||
|
||||
h1 {
|
||||
border-bottom: 3px solid #3498db;
|
||||
padding-bottom: 10px;
|
||||
}
|
||||
|
||||
h2 {
|
||||
border-bottom: 1px solid #bdc3c7;
|
||||
padding-bottom: 5px;
|
||||
}
|
||||
|
||||
code {
|
||||
background-color: #f8f8f8;
|
||||
padding: 2px 4px;
|
||||
border-radius: 3px;
|
||||
font-family: "Monaco", "Menlo", "Ubuntu Mono", monospace;
|
||||
}
|
||||
|
||||
pre {
|
||||
background-color: #f8f8f8;
|
||||
padding: 15px;
|
||||
border-radius: 5px;
|
||||
overflow-x: auto;
|
||||
}
|
||||
|
||||
table {
|
||||
border-collapse: collapse;
|
||||
width: 100%;
|
||||
margin: 1em 0;
|
||||
}
|
||||
|
||||
th, td {
|
||||
border: 1px solid #ddd;
|
||||
padding: 8px;
|
||||
text-align: left;
|
||||
}
|
||||
|
||||
th {
|
||||
background-color: #f2f2f2;
|
||||
font-weight: bold;
|
||||
}
|
||||
|
||||
.mermaid {
|
||||
text-align: center;
|
||||
margin: 20px 0;
|
||||
}
|
||||
BIN
系统概要设计文档 word.docx
Normal file
BIN
系统概要设计文档 word.docx
Normal file
Binary file not shown.
Loading…
x
Reference in New Issue
Block a user