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

## 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)

---

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