187 lines
3.7 KiB
Markdown
187 lines
3.7 KiB
Markdown
# 🚀 福建水务营收系统文档工具链 - 快速入门
|
||
|
||
## 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)
|
||
|
||
---
|
||
|
||
💡 **提示**：将本页面加入书签，随时查看常用命令！ |