fujian_water_biz_doc/QUICK_START.md

🚀 福建水务营收系统文档工具链 - 快速入门

5分钟快速体验

第1步：初始化工具链（30秒）

# 初始化工具链配置
make init

预期输出：

[INFO] 初始化文档工具链配置...
[INFO] 样式文件创建完成
[SUCCESS] 配置初始化完成！

第2步：创建示例模块文档（1分钟）

# 创建用户管理模块文档
make create MODULE=user_management

预期输出：

[INFO] 创建模块文档: water_biz_user_management_design.md
[SUCCESS] 模块文档创建完成: water_biz_user_management_design.md
[INFO] 请使用编辑器打开文件并完善内容

第3步：验证文档（30秒）

# 验证文档格式和内容
make validate

第4步：导出HTML预览（1分钟）

# 导出HTML格式进行预览
make export-html

第5步：查看成果（1分钟）

打开生成的文件：

• 📝 源文档：water_biz_user_management_design.md
• 🌐 HTML版：output/福建水务营收系统概要设计文档.html

完整使用示例

创建多个模块文档

# 创建核心业务模块
make create MODULE=user_management      # 用户管理
make create MODULE=meter_reading        # 抄表管理  
make create MODULE=billing_management   # 收费管理
make create MODULE=account_management   # 账务管理

批量验证和导出

# 验证所有文档
make validate

# 检查链接有效性
make check-links

# 导出所有格式
make full-build

在VS Code中使用

1. 打开项目：

   code .
   

2. 运行任务：

   • 按 Ctrl+Shift+P (或 Cmd+Shift+P)
   • 输入 "Tasks: Run Task"
   • 选择需要的任务（如"验证所有文档"）

3. 实时预览：

   • 安装推荐扩展
   • 编辑Markdown文件时自动显示预览

高效工作流程

日常文档编写流程

# 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 "完成新模块名设计文档"

团队协作流程

# 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：命令不识别

# 解决方案：确保在项目根目录
pwd  # 应该显示包含Makefile的目录
ls Makefile  # 应该能看到Makefile文件

问题2：权限错误

# 解决方案：添加执行权限
chmod +x scripts/doc-toolkit.sh

问题3：pandoc未安装

# 解决方案：安装依赖
make install-deps
# 或手动安装：brew install pandoc (macOS)

下一步

恭喜！您已经掌握了文档工具链的基本使用。

继续阅读：

• 📖 完整使用指南
• 📋 Cursor Rules说明
• 📝 文档编写计划

---

💡 提示：将本页面加入书签，随时查看常用命令！