---
phase: 08-documentation
plan: 03
type: execute
wave: 1
depends_on: []
files_modified:
  - examples/filter_slow_queries.rs
  - examples/batch_export.rs
autonomous: true
requirements:
  - DOC-03
must_haves:
  truths:
    - "examples/filter_slow_queries.rs 可通过 cargo run --example filter_slow_queries -- <file> 运行"
    - "examples/batch_export.rs 可通过 cargo run --example batch_export -- <file> 运行"
    - "两个示例文件均使用 Phase 7 新 API（LogParserBuilder、filter_by_exec_time、exec_time 等）"
    - "batch_export 输出 CSV 格式到 stdout"
  artifacts:
    - path: "examples/filter_slow_queries.rs"
      provides: "过滤慢查询的独立可运行示例"
      min_lines: 35
    - path: "examples/batch_export.rs"
      provides: "批量导出为 CSV 的独立可运行示例"
      min_lines: 35
  key_links:
    - from: "examples/filter_slow_queries.rs"
      to: "cargo run --example filter_slow_queries"
      via: "Cargo.toml [[example]] 自动发现"
    - from: "examples/batch_export.rs"
      to: "cargo run --example batch_export"
      via: "Cargo.toml [[example]] 自动发现"
---

<objective>
在 `examples/` 目录下创建 2 个独立可运行的二进制示例，演示使用 `dm-database-parser-sqllog` 库的典型场景。

Purpose: 满足 DOC-03 要求 — `examples/` 目录包含至少 2 个独立可运行示例。
Output: `examples/filter_slow_queries.rs` 和 `examples/batch_export.rs`。
</objective>

<execution_context>
@$HOME/.claude/get-shit-done/workflows/execute-plan.md
@$HOME/.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/REQUIREMENTS.md
@.planning/phases/08-documentation/08-CONTEXT.md
@CLAUDE.md
@src/parser.rs
@src/sqllog.rs
@src/lib.rs
@Cargo.toml

<interfaces>
<!-- 示例需要使用的主要 API（Phase 7 提供） -->

```rust
// Phase 7 API（from CONTEXT.md）：
let parser = LogParserBuilder::new(path).build()?;
for result in parser.iter().filter_by_exec_time(100) {
    let sqllog = result?;
    println!("time: {}, exec_time: {:?}", sqllog.ts, sqllog.exec_time()?);
}
```
</interfaces>
</context>

<tasks>

<task type="auto">
  <name>Task 1: 创建 examples/filter_slow_queries.rs</name>
  <files>examples/filter_slow_queries.rs</files>
  <read_first>src/parser.rs, src/sqllog.rs, src/lib.rs</read_first>
  <action>
    创建 `examples/` 目录（如果不存在），然后创建 `examples/filter_slow_queries.rs`：

    - 从 `std::env::args()` 获取第一个命令行参数作为文件路径（D-06），若缺少参数打印用法说明并退出。
    - 使用 `LogParserBuilder::new(path).build()?` 构建解析器（Phase 7 API）。
    - 使用 `parser.iter().filter_by_exec_time(100)` 过滤执行时间 ≥100ms 的记录（Phase 7 API）。
    - 遍历结果，对每条记录打印 `ts` 字段 + `exec_time()?` + `body()`。
    - 使用 `anyhow::Result` 或 `Box<dyn std::error::Error>` 作主函数错误返回。
    - 文件头添加 `//! filter_slow_queries — 过滤执行时间 ≥ 100ms 的慢查询` 中文 doc 注释。
    - 代码风格参考 CLAUDE.md 要求：完整变量名、函数 <40 行。
    - 遵循 D-02：代码变量名和注释用英文。

    示例结构：
    ```rust
    fn main() -> Result<(), Box<dyn std::error::Error>> {
        let path = std::env::args().nth(1).context("...")?;
        let parser = dm_database_parser_sqllog::LogParserBuilder::new(path).build()?;
        for result in parser.iter().filter_by_exec_time(100) {
            let sqllog = result?;
            println!("...", sqllog.ts, sqllog.exec_time()?.unwrap_or(0), sqllog.body());
        }
        Ok(())
    }
    ```

    注意事项：
    - 依赖文件不存在时正常报错（不 panic）。
    - 如需 `anyhow` 或 `eyre`，在 Cargo.toml 中添加为 dev-dependency（本任务不修改 Cargo.toml，仅使用 `Box<dyn Error>` 避免依赖）。
    - 使用 `eprintln!` 输出错误信息。
  </action>
  <acceptance_criteria>
    - `examples/filter_slow_queries.rs` 文件存在且可编译：
      `cargo check --example filter_slow_queries 2>&1` 成功
    - 文件包含 `fn main()` 和 CLI 参数处理
    - 使用 `LogParserBuilder`、`filter_by_exec_time`、`exec_time`
  </acceptance_criteria>
  <verify>
    <automated>
      cargo check --example filter_slow_queries 2>&1 | tail -3
    </automated>
  </verify>
  <done>cargo check --example filter_slow_queries 通过</done>
</task>

<task type="auto">
  <name>Task 2: 创建 examples/batch_export.rs</name>
  <files>examples/batch_export.rs</files>
  <read_first>src/parser.rs, src/sqllog.rs, src/lib.rs</read_first>
  <action>
    创建 `examples/batch_export.rs` — 读取所有记录，将 `timestamp + username + sql + exec_time` 导出为 CSV 写到 stdout（per D-05, D-06 和 Specifics 第 84 行）：

    - 从 `std::env::args()` 获取文件路径，若缺少参数打印用法说明。
    - 使用 `LogParserBuilder::new(path).build()?` 构建解析器。
    - 使用 `parser.iter()` 遍历所有记录。
    - 对每条成功的记录，以 CSV 格式输出 `ts`, `parse_meta().username`, `body()`, `exec_time()?`。
    - CSV 第一行为 header：`timestamp,username,sql,exec_time_ms`。
    - 字段值使用引号包裹（避免 SQL 中的逗号破坏 CSV 格式），特殊字符仅做基本转义（`"` → `""`）。
    - 文件头添加 `//! batch_export — 将 SQL 日志导出为 CSV 格式到 stdout` 中文 doc 注释。
    - 代码风格：不做不必要的数据收集（按行处理即可），保持低内存占用。

    ```rust
    fn main() -> Result<(), Box<dyn std::error::Error>> {
        let path = std::env::args().nth(1).context("...")?;
        let parser = dm_database_parser_sqllog::LogParserBuilder::new(path).build()?;
        println!("timestamp,username,sql,exec_time_ms");
        for result in parser.iter() {
            let sqllog = result?;
            // CSV 转义 + 输出
        }
        Ok(())
    }
    ```

    注意事项：
    - 使用 `Box<dyn std::error::Error>` — 不需要额外依赖。
    - CSV 不需要使用 csv crate — 基本字符串拼接即可。
    - D-02：代码变量名和注释用英文。
  </action>
  <acceptance_criteria>
    - `examples/batch_export.rs` 文件存在且可编译：
      `cargo check --example batch_export 2>&1` 成功
    - 文件包含 `fn main()` 和 CLI 参数处理
    - 输出 CSV 格式（第一行为 header，后续每行一条记录）
  </acceptance_criteria>
  <verify>
    <automated>
      cargo check --example batch_export 2>&1 | tail -3
    </automated>
  </verify>
  <done>cargo check --example batch_export 通过</done>
</task>

<task type="auto">
  <name>Task 3: 验证两个示例编译通过</name>
  <files>examples/filter_slow_queries.rs, examples/batch_export.rs</files>
  <read_first>examples/filter_slow_queries.rs, examples/batch_export.rs</read_first>
  <action>
    确认两个示例均可编译通过：

    1. 运⾏ `cargo check --example filter_slow_queries` — 应成功编译，无 warning。
    2. 运⾏ `cargo check --example batch_export` — 应成功编译，无 warning。
    3. 运⾏ `cargo test --doc` — 验证 lib.rs 的 3 个示例代码块也通过编译（Plan 02 的任务已覆盖，此处做最终验证）。

    如果编译失败，根据编译错误修复示例代码（如 API 名称与 Phase 7 实现不一致）。
  </action>
  <acceptance_criteria>
    `cargo check --example filter_slow_queries` 成功
    `cargo check --example batch_export` 成功
  </acceptance_criteria>
  <verify>
    <automated>
      cargo check --example filter_slow_queries 2>&1 && cargo check --example batch_export 2>&1
    </automated>
  </verify>
  <done>两个示例均可编译，cargo test --doc 通过</done>
</task>

</tasks>

<verification>

```bash
# 验证示例可编译
cargo check --example filter_slow_queries 2>&1 | tail -5
cargo check --example batch_export 2>&1 | tail -5

# 验证 doc 测试（Plan 02 的示例、Plan 03 不直接修改 lib.rs 但需确保无破坏）
cargo test --doc 2>&1 | tail -5
```

</verification>

<success_criteria>
1. `cargo check --example filter_slow_queries` 通过
2. `cargo check --example batch_export` 通过
3. 两个示例均支持 CLI 参数指定文件路径（D-06）
4. `cargo test --doc` 通过
</success_criteria>
