tidyflow 的 CLI 模块边界

模块分工

tidyflow 按职责分为四个模块：

• cli.py：接收命令行参数，组织用户可见的输出。
• cleaner.py：读取 CSV、Excel、JSON，并执行清洗动作。
• diagnoser.py：扫描缺失值、重复行、列名、空白文本和类型问题。
• reporter.py：把清洗前后的差异整理成质量报告。

cli.py 不处理 pandas 的细节，Diagnoser 也不保存文件。模块之间通过清晰的调用关系协作，因此可以分别测试。

Cleaner 是核心状态机

Cleaner 保存原始 DataFrame 和当前 DataFrame 两份状态。每次清洗只修改当前数据，同时记录已执行的操作：

Cleaner("data.csv").remove_duplicates().fill_missing().to_snake_case().clean()

最后由 clean() 返回 CleanResult，再通过它调用 save()、report() 和 to_gif()。调用方先完成清洗，之后再选择保存、生成报告或导出动图。

Diagnoser 不直接修改数据

Diagnoser 只检查数据并给出建议，不修改 DataFrame。发现的问题分为 warning、error、critical 三类。

分类取决于问题的范围：

• 少量缺失值可以是 warning。
• 缺失比例较高可以升为 error。
• 超过一半为空的列可以标为 critical。

CLI 只做编排

cli.py 不保存清洗规则，它负责把命令行参数交给核心模块：

1. 解析参数。
2. 创建 Cleaner 或 Diagnoser。
3. 调用核心方法。
4. 用 rich 把结果展示出来。
5. 把错误转换成用户能读懂的命令行反馈。

新增 Web API、notebook helper 或 GUI 时，可以直接复用 Cleaner 和 Diagnoser，无需复制 CLI 中的处理逻辑。

可以继续改进的地方

下一步可以补一层配置，让用户在 tidyflow.toml 中声明清洗规则：

fill_strategy = "median"
deduplicate = true
snake_case = true
strip_text = true

CLI 读取这份配置后，就能重复执行同一套规则，而不是每次都重新拼命令参数。它适合需要固定清洗步骤的任务。