# Data Pipeline 分步执行使用指南

## 问题背景

在之前的版本中，分步执行脚本存在以下问题：
1. 缺少 `--task-id` 参数，无法自动定位到正确的任务目录
2. 需要手动指定完整的文件路径，容易出错
3. 与完整执行方式的行为不一致

## 解决方案

现在所有分步执行脚本都支持 `--task-id` 参数，当提供该参数时：
- 自动构建正确的输出目录路径（基础目录/task_id）
- 自动查找相关的输入文件
- 保持与完整执行方式的一致性
- 向后兼容原有的使用方式

## 使用方法

### 方式1：使用 task_id 参数（推荐）

```bash
# 步骤1：生成DDL和MD文件
python -m data_pipeline.ddl_generation.ddl_md_generator \
  --task-id manual_20250720_130541 \
  --db-connection "postgresql://user:pass@localhost:5432/dbname" \
  --table-list tables.txt \
  --business-context "高速公路服务区管理系统"

# 步骤2：生成Question-SQL对
python -m data_pipeline.qa_generation.qs_generator \
  --task-id manual_20250720_130541 \
  --table-list tables.txt \
  --business-context "高速公路服务区管理系统"

# 步骤3：验证和修正SQL
python -m data_pipeline.validators.sql_validate_cli \
  --task-id manual_20250720_130541 \
  --db-connection "postgresql://user:pass@localhost:5432/dbname"

# 步骤4：训练数据加载
python -m data_pipeline.trainer.run_training \
  --task-id manual_20250720_130541
```

### 方式2：手动指定路径（向后兼容）

```bash
# 步骤1：生成DDL和MD文件
python -m data_pipeline.ddl_generation.ddl_md_generator \
  --db-connection "postgresql://user:pass@localhost:5432/dbname" \
  --table-list tables.txt \
  --business-context "高速公路服务区管理系统" \
  --output-dir ./data_pipeline/training_data/manual_20250720_130541

# 步骤2：生成Question-SQL对
python -m data_pipeline.qa_generation.qs_generator \
  --output-dir ./data_pipeline/training_data/manual_20250720_130541 \
  --table-list tables.txt \
  --business-context "高速公路服务区管理系统"

# 步骤3：验证和修正SQL
python -m data_pipeline.validators.sql_validate_cli \
  --db-connection "postgresql://user:pass@localhost:5432/dbname" \
  --input-file ./data_pipeline/training_data/manual_20250720_130541/highway_db_20250720_pair.json

# 步骤4：训练数据加载
python -m data_pipeline.trainer.run_training \
  --data_path ./data_pipeline/training_data/manual_20250720_130541
```

## 参数说明

### 共同参数

- `--task-id`：任务ID，当提供时会自动构建输出目录路径
- `--verbose`：启用详细日志输出
- `--log-file`：指定日志文件路径

### DDL生成器 (ddl_md_generator.py)

**新增参数：**
- `--task-id`：任务ID，指定后将自动构建输出目录路径

**必需参数：**
- `--db-connection`：数据库连接字符串
- `--table-list`：表清单文件路径
- `--business-context`：业务上下文描述

**可选参数：**
- `--output-dir`：输出目录路径（当未指定task-id时必需）
- `--pipeline`：处理链类型（full/ddl_only/analysis_only）

### QA生成器 (qs_generator.py)

**新增参数：**
- `--task-id`：任务ID，指定后将自动构建输出目录路径

**必需参数：**
- `--table-list`：表清单文件路径
- `--business-context`：业务上下文描述

**可选参数：**
- `--output-dir`：输出目录路径（当未指定task-id时必需）
- `--db-name`：数据库名称

### SQL验证器 (sql_validate_cli.py)

**新增参数：**
- `--task-id`：任务ID，指定后将自动在任务目录中查找Question-SQL文件

**必需参数：**
- `--db-connection`：数据库连接字符串

**可选参数：**
- `--input-file`：输入JSON文件路径（当未指定task-id时必需）
- `--output-dir`：验证报告输出目录
- `--disable-llm-repair`：禁用LLM修复功能
- `--modify-original-file`：修改原始JSON文件

### 训练器 (run_training.py)

**新增参数：**
- `--task-id`：任务ID，指定后将自动构建训练数据目录路径

**可选参数：**
- `--data_path`：训练数据目录路径（当未指定task-id时使用）
- `--backup-vector-tables`：备份vector表数据
- `--truncate-vector-tables`：清空vector表数据

## 自动路径解析逻辑

当使用 `--task-id` 参数时，系统会：

1. **读取配置**：从 `data_pipeline.config.SCHEMA_TOOLS_CONFIG` 读取基础目录
2. **处理相对路径**：如果基础目录是相对路径，会相对于项目根目录解析
3. **构建任务目录**：基础目录 + task_id
4. **自动查找文件**：在任务目录中查找相关文件

例如：
- 配置基础目录：`./data_pipeline/training_data/`
- task_id：`manual_20250720_130541`
- 最终路径：`/项目根目录/data_pipeline/training_data/manual_20250720_130541`

## 文件查找规则

### DDL生成器
- 输出目录：`{基础目录}/{task_id}/`

### QA生成器
- 输入目录：`{基础目录}/{task_id}/`（查找.md和.ddl文件）
- 输出文件：`{基础目录}/{task_id}/{db_name}_pair.json`

### SQL验证器
- 输入文件：自动查找 `{基础目录}/{task_id}/*_pair.json`（选择最新的）
- 输出目录：`{基础目录}/{task_id}/`

### 训练器
- 训练数据目录：`{基础目录}/{task_id}/`

## 错误处理

### 常见错误及解决方法

1. **任务目录不存在**
   ```
   错误: 输出目录不存在: /path/to/task_dir
   ```
   解决：确保先执行DDL生成步骤，或手动创建任务目录

2. **找不到Question-SQL文件**
   ```
   错误: 在任务目录中未找到Question-SQL文件 (*_pair.json)
   ```
   解决：确保先执行QA生成步骤

3. **表清单文件不存在**
   ```
   错误: 表清单文件不存在: tables.txt
   ```
   解决：检查表清单文件路径，确保文件存在

## 最佳实践

1. **使用完整的task_id**：推荐使用 `manual_YYYYMMDD_HHMMSS` 格式
2. **按顺序执行**：确保按照 DDL生成 → QA生成 → SQL验证 → 训练加载 的顺序执行
3. **检查输出**：每个步骤完成后检查输出目录中的文件
4. **使用详细日志**：添加 `--verbose` 参数获取更多信息
5. **备份重要数据**：在训练前使用 `--backup-vector-tables` 备份现有数据

## 与完整执行方式的对比

| 特性 | 完整执行 | 分步执行（使用task-id） |
|------|----------|------------------------|
| 路径管理 | 自动创建task目录 | 需手动创建或从DDL步骤开始 |
| 参数传递 | 自动传递task_id | 需手动指定task_id |
| 错误处理 | 统一错误处理 | 每步独立处理 |
| 灵活性 | 较低 | 较高 |
| 适用场景 | 标准流程 | 调试、测试、部分重跑 |

## 示例：完整的分步执行流程

```bash
# 设置变量
TASK_ID="manual_$(date +%Y%m%d_%H%M%S)"
DB_CONN="postgresql://user:pass@localhost:5432/highway_db"
TABLE_LIST="tables.txt"
BUSINESS_CONTEXT="高速公路服务区管理系统"

echo "开始分步执行，任务ID: $TASK_ID"

# 步骤1：DDL和MD生成
echo "步骤1: 生成DDL和MD文件..."
python -m data_pipeline.ddl_generation.ddl_md_generator \
  --task-id "$TASK_ID" \
  --db-connection "$DB_CONN" \
  --table-list "$TABLE_LIST" \
  --business-context "$BUSINESS_CONTEXT" \
  --verbose

# 步骤2：Question-SQL生成
echo "步骤2: 生成Question-SQL对..."
python -m data_pipeline.qa_generation.qs_generator \
  --task-id "$TASK_ID" \
  --table-list "$TABLE_LIST" \
  --business-context "$BUSINESS_CONTEXT" \
  --verbose

# 步骤3：SQL验证
echo "步骤3: 验证SQL..."
python -m data_pipeline.validators.sql_validate_cli \
  --task-id "$TASK_ID" \
  --db-connection "$DB_CONN" \
  --verbose

# 步骤4：训练数据加载
echo "步骤4: 加载训练数据..."
python -m data_pipeline.trainer.run_training \
  --task-id "$TASK_ID" \
  --verbose

echo "分步执行完成！"
```

## 总结

通过添加 `--task-id` 参数，现在的分步执行方式：
- ✅ 解决了路径管理问题
- ✅ 保持了与完整执行的一致性
- ✅ 提供了更好的用户体验
- ✅ 保持了向后兼容性

推荐在调试、测试或需要重跑特定步骤时使用分步执行方式。