docs: add MacrolactoneDB validation module usage to README

README.md

@@ -62,6 +62,89 @@ pixi run macro-lactone-toolkit fragment \
 
 默认读取 `smiles` 列；若存在 `id` 列则将其作为 `parent_id`，否则自动生成 `row_<index>`。
 
+## MacrolactoneDB 验证模块
+
+用于对 MacrolactoneDB 数据库进行抽样验证、分类、侧链断裂和数据库存储。
+
+### 验证脚本使用
+
+```bash
+# 基本使用（10% 分层抽样）
+pixi run python scripts/validate_macrolactone_db.py \
+  --input data/MacrolactoneDB/ring12_20/temp.csv \
+  --output validation_output \
+  --sample-ratio 0.1
+
+# 处理全量数据
+pixi run python scripts/validate_macrolactone_db.py \
+  --input data/MacrolactoneDB/ring12_20/temp.csv \
+  --output validation_output \
+  --sample-ratio 1.0
+
+# 指定列名（如果 CSV 列名不同）
+pixi run python scripts/validate_macrolactone_db.py \
+  --input data.csv \
+  --output validation_output \
+  --id-col ml_id \
+  --chembl-id-col IDs \
+  --smiles-col smiles
+```
+
+### 输出结构
+
+```
+validation_output/
+├── README.md                    # 目录说明
+├── fragments.db                 # SQLite 数据库
+├── summary.csv                  # 汇总表（含 ml_id, chembl_id）
+├── summary_statistics.json      # 统计信息
+├── ring_size_12/                # 按环大小组织
+├── ring_size_13/
+...
+└── ring_size_20/
+    ├── standard/
+    │   ├── numbered/            # 带编号的环图（文件名使用 ml_id）
+    │   │   └── {ml_id}_numbered.png
+    │   └── sidechains/          # 片段图
+    │       └── {ml_id}/
+    │           └── {ml_id}_frag_{n}_pos{pos}.png
+    ├── non_standard/original/
+    └── rejected/original/
+```
+
+### 数据库查询示例
+
+```bash
+# 查看表结构
+sqlite3 validation_output/fragments.db ".tables"
+
+# 查询标准大环内酯
+sqlite3 validation_output/fragments.db \
+  "SELECT ml_id, chembl_id, ring_size, num_sidechains \
+   FROM parent_molecules \
+   WHERE classification='standard_macrolactone' LIMIT 5;"
+
+# 查询片段
+sqlite3 validation_output/fragments.db \
+  "SELECT fragment_id, cleavage_position, dummy_isotope \
+   FROM side_chain_fragments \
+   WHERE ml_id='ML00000001';"
+
+# 按环大小统计
+sqlite3 validation_output/fragments.db \
+  "SELECT ring_size, COUNT(*) FROM parent_molecules GROUP BY ring_size;"
+```
+
+### 关键字段说明
+
+| 字段 | 说明 |
+|------|------|
+| `ml_id` | MacrolactoneDB 唯一 ID（如 ML00000001），用于文件命名 |
+| `chembl_id` | 原始 CHEMBL ID（如 CHEMBL94657），可能为空 |
+| `classification` | standard_macrolactone / non_standard_macrocycle / not_macrolactone |
+| `dummy_isotope` | 裂解位置编号，用于片段重建 |
+| `cleavage_position` | 环上的断裂位置 |
+
 ## Legacy Scripts
 
 `scripts/` 目录保留为薄封装或迁移提示，不再承载核心实现。正式接口以 `macro_lactone_toolkit.*` 与 `macro-lactone-toolkit` CLI 为准。