# Milestone v2.0: Refactor, Filter & Async

**Status:** ✅ SHIPPED 2026-05-23
**Phases:** 10–12
**Total Plans:** 6

## Overview

v2.0 重构 src/ 为功能分层子模块，添加全字段可组合 FilterBuilder（56 个谓词方法，14 字段覆盖），并引入 tokio async 可选 feature。核心目标：在保持 API 兼容性和 ≥90% 覆盖率的前提下，完成代码组织现代化和 API 功能扩展。

## Phases

### Phase 10: Restructure

**Goal**: src/ 目录按功能分层重组完毕，库用户侧导入路径不变，所有现有测试继续通过

**Depends on**: Nothing (first phase of milestone)

**Requirements**: REFACTOR-01, REFACTOR-02, REFACTOR-03, REFACTOR-04, REFACTOR-05, REFACTOR-06, REFACTOR-07

**Plans**: 3 plans

Plans:
**Wave 1**
- [x] 10-01-PLAN.md — 建立 filter/、async_api/、parser/ 子目录骨架，git mv sqllog.rs → record.rs，最小可编译路径替换

**Wave 2** *(blocked on Wave 1 completion)*
- [x] 10-02-PLAN.md — 拆分 src/parser.rs 为 mod.rs/builder.rs/iterator.rs/encoding.rs，迁移 parse_record 依赖测试到内部 #[cfg(test)] 块，LogIterator 委托调用 filter::adapter

**Wave 3** *(blocked on Wave 2 completion)*
- [x] 10-03-PLAN.md — lib.rs 进入最终态（声明 filter 子模块、移除 parse_record 重导出），验证 examples/、rustdoc、clippy、覆盖率 ≥90%

**Completed:** 2026-05-22

**Key outcomes:**
- src/parser/{mod,builder,iterator,encoding}.rs — 解析相关代码全部迁入
- src/filter/{mod,adapter}.rs — 过滤骨架就位，adapter 函数预留
- src/async_api/mod.rs — 占位模块创建
- src/record.rs（原 sqllog.rs）+ src/error.rs — 基础结构就位
- 75 个现有测试全量通过；覆盖率 94.93%；clippy 零警告

---

### Phase 11: FilterBuilder

**Goal**: 用户可对所有 14 个 Sqllog 字段链式组合过滤条件，并通过 LogParser 迭代器直接使用

**Depends on**: Phase 10

**Requirements**: FILTER-01, FILTER-02, FILTER-03, FILTER-04, FILTER-05, FILTER-06, FILTER-07, FILTER-08, FILTER-09, FILTER-10

**Plans**: 2 plans

Plans:
**Wave 1**
- [x] 11-01-PLAN.md — 新建 src/filter/builder.rs，实现 Filter + FilterBuilder + 14 字段全部链式谓词方法（56 个公开方法）+ 完整 #[cfg(test)] 单元测试块；更新 src/filter/mod.rs 重导出

**Wave 2** *(blocked on Wave 1 completion)*
- [x] 11-02-PLAN.md — adapter.rs 扩展 apply_filter / apply_filter_keep_errors；iterator.rs 上 LogIterator 暴露对应 pub 方法；lib.rs 顶层 pub use Filter / FilterBuilder；新增 examples/filter_builder.rs 与 tests/filter_builder.rs 集成测试

**Completed:** 2026-05-23

**Key outcomes:**
- FilterBuilder 56 个公开谓词方法（14 字段全覆盖），AND 语义单次迭代
- apply_filter / apply_filter_keep_errors 两路错误处理策略
- 12 个集成测试（tests/filter_builder.rs）全通过
- 覆盖率 90.23%；clippy 零警告
- VERIFICATION.md: passed (18/18)

---

### Phase 12: AsyncAPI

**Goal**: 用户可在 tokio async 运行时中直接 await 解析日志文件，且 tokio 依赖为可选 feature

**Depends on**: Phase 11

**Requirements**: ASYNC-01, ASYNC-02, ASYNC-03, ASYNC-04

**Plans**: 1 plan

Plans:
**Wave 1**
- [x] 12-01-PLAN.md — Cargo.toml 添加 tokio optional dependency + dev-dependency + [features] async；src/async_api/mod.rs 实现 AsyncLogParser + AsyncError + 单元测试；src/lib.rs 在 #[cfg(feature = "async")] 守卫下声明并重导出 async_api

**Completed:** 2026-05-23

**Key outcomes:**
- AsyncLogParser::new(path).with_filter(filter).parse().await — 端到端可用
- spawn_blocking 封装同步 mmap 路径，返回 Vec<Sqllog<'static>>
- tokio 仅在 features=["async"] 时引入，下游零 tokio 依赖
- 覆盖率 90.65%（all-features）；clippy 零警告
- VERIFICATION.md: passed (7/7)

---

## Milestone Summary

**Key Decisions:**

- src/ 按功能分层而非文件大小分层 — 更清晰的模块边界和导航
- FilterBuilder 使用 `Predicate = Box<dyn Fn + Send + Sync>` 类型别名 — 解决 clippy::type_complexity，为 async 预留 Send+Sync
- exectime 不提供 eq，提供 gte/gt — f32 浮点精度问题，between 替代等值比较
- async 返回 `Vec<Sqllog<'static>>` — mmap 同步解析；Cow<'a> 无法跨 spawn_blocking 线程边界
- tokio 用 `dep:tokio` 而非 `tokio/rt` — Cargo 惯用写法，dev-dep 独立控制

**Issues Resolved:**

- E0761 双路径冲突（parser.rs 和 parser/ 目录同时存在）— 提前将 parser.rs 全量迁入 parser/mod.rs
- parse_record dead_code clippy 警告 — 添加 #[cfg(test)] 属性
- Filter/FilterBuilder dead_code 警告（Plan 11-01 临时标注）— Plan 11-02 lib.rs 重导出后全部清除
- 代码审查修复：Phase 11 修复 6 个问题，Phase 12 修复 5 个问题（含 ASYNC-03 dev-dep 文档、Panic 路径测试覆盖）

**Technical Debt Incurred:**

- Phase 10 未生成 VERIFICATION.md（所有 REFACTOR 需求已由 Integration Checker 独立确认）
- Nyquist VALIDATION.md 未生成（config: nyquist_validation: false）

---

*For current project status, see .planning/ROADMAP.md*
