# 配置文件集成完成总结

## ✅ 已完成的工作

### 1. 核心模块 ✅

- **`config.py`** (220 行)
  - `JCleanConfig` 数据类
  - `find_config_file()` — 查找配置文件（5 级优先级）
  - `load_config()` — 加载并解析配置
  - `generate_sample_config()` — 生成示例配置
  - `resolve_path()` — 路径解析（绝对/相对）

### 2. CLI 更新 ✅

- **新增命令**：
  - `jclean init-config` — 生成示例配置文件
  - `jclean show-config` — 查看当前配置
- **全局参数**：
  - `--config` — 指定配置文件路径
  - `--tasks-root` — 覆盖配置文件中的 tasks_root
- **create 命令**：使用配置文件默认值（可被命令行参数覆盖）

### 3. 依赖管理 ✅

- 添加 `tomli>=2.0; python_version<'3.11'` 到 `pyproject.toml`
- Python 3.11+ 自带 `tomllib`，无需额外依赖

### 4. 测试覆盖 ✅

- **新增 13 个配置测试** (`test_config.py`)
  - 默认配置
  - 路径解析（绝对/相对/父目录）
  - 配置文件查找
  - 配置加载
  - 示例生成
- **总计 73 个测试全部通过** ✅

### 5. 文档更新 ✅

- **README_cleaner.md**
  - 配置文件章节（生成/示例/查找顺序/路径解析/优先级）
  - 功能特性增加配置文件管理
  - 版本历史更新到 v0.3.0
- **CONFIG_FILE_DESIGN.md** — 完整设计文档

### 6. 导出更新 ✅

- `__init__.py` 导出 `JCleanConfig` / `load_config` / `generate_sample_config`

---

## 🎯 配置文件功能

### **查找优先级**

```text
1. --config /path/to/custom.toml       (命令行指定，最高优先级)
2. ./jclean.toml 或 ./.jclean.toml    (当前目录)
3. ../jclean.toml, ../../...           (向上查找，遇到 .git 停止)
4. ~/.jclean.toml                      (用户主目录)
5. 硬编码默认值                         (兜底)
```text

### **路径解析规则**

- **绝对路径** → 直接使用
- **相对路径** → 相对配置文件所在目录

**示例**（配置文件在 `/home/user/project/jclean.toml`）：

```toml
[paths]
tasks_root = "tasks"                    # → /home/user/project/tasks
vocabulary = "/data/global/vocab.txt"   # → /data/global/vocab.txt
sources_dir = "../shared/sources"       # → /home/user/shared/sources
```text

### **配置优先级**

```text
命令行参数 > 配置文件 > 默认值
```text

**示例**：

```bash
# 配置文件中 count = 500
# 命令行参数覆盖
jclean create batch1 --source data.txt --count 300  # 使用 300
```text

---

## 📝 配置文件示例

```toml
# jclean.toml

[paths]
# 任务根目录
tasks_root = "tasks"

# 权威库（所有任务最终合并的目标）
vocabulary = "data/db/vocabulary.txt"
skipped = "data/db/skipped.txt"

# 数据源目录（可选）
sources_dir = "data/sources"

[defaults]
# 创建任务时的默认值
start_line = 1
count = 300

# 是否在合并前自动备份权威库
backup_before_merge = true
backup_dir = "data/backup"

[logging]
# 日志级别：DEBUG / INFO / WARNING / ERROR
level = "INFO"

# 日志输出位置（可选）
# log_file = "logs/jclean.log"
```text

---

## 🚀 使用示例

### **场景 1：单项目（最简单）**

```bash
# 在项目根目录生成配置
cd /path/to/project
jclean init-config

# 编辑 jclean.toml（可选）

# 使用默认配置创建任务
jclean create batch1 --source data/sources/xinbiaori_1.txt
jclean run batch1
```text

---

### **场景 2：多项目隔离**

**项目 A** (`/home/user/project_a/jclean.toml`)：

```toml
[paths]
tasks_root = "tasks"
vocabulary = "vocab/main.txt"
skipped = "vocab/skip.txt"
```text

**项目 B** (`/home/user/project_b/jclean.toml`)：

```toml
[paths]
tasks_root = "tasks"
vocabulary = "data/vocab.txt"
skipped = "data/skip.txt"
```text

**使用**：

```bash
cd /home/user/project_a
jclean create batch1 --source data/source.txt  # 使用项目 A 配置

cd /home/user/project_b
jclean create batch1 --source data/source.txt  # 使用项目 B 配置（独立）
```text

---

### **场景 3：共享权威库（多项目合并到同一库）**

**项目 A** (`/home/user/project_a/jclean.toml`)：

```toml
[paths]
tasks_root = "tasks"                              # 各自独立
vocabulary = "/shared/japanese/vocabulary.txt"    # 共享（绝对路径）
skipped = "/shared/japanese/skipped.txt"          # 共享
```text

**项目 B** (`/home/user/project_b/jclean.toml`)：

```toml
[paths]
tasks_root = "tasks"                              # 各自独立
vocabulary = "/shared/japanese/vocabulary.txt"    # 共享（同一个库）
skipped = "/shared/japanese/skipped.txt"          # 共享
```text

**结果**：

- 各项目任务独立（`tasks/` 目录独立）
- 最终成果合并到同一个权威库

---

### **场景 4：全局配置 + 项目覆盖**

**用户主目录** (`~/.jclean.toml`)：

```toml
[paths]
tasks_root = "~/japanese_tasks"
vocabulary = "~/japanese_vocab.txt"

[defaults]
count = 300
```text

**项目目录** (`/work/project1/jclean.toml`)：

```toml
[paths]
vocabulary = "data/project_vocab.txt"  # 覆盖全局
# tasks_root 继承全局配置
```text

---

## 📊 测试覆盖

```text
============================= 73 passed in 11.96s ==============================

tests/test_config.py           13 passed  (配置管理)
tests/test_cleaner.py           8 passed  (底层单元)
tests/test_cleaner_workflow.py 31 passed  (三层集成)
tests/test_tango.py             6 passed  (下游模型)
tests/test_validator.py        15 passed  (格式校验)
```text

---

## 🎨 CLI 命令

### **配置相关**

```bash
jclean init-config [--output jclean.toml]  # 生成示例配置
jclean show-config                         # 查看当前配置
```text

### **全局参数**

```bash
jclean --config /path/to/config.toml ...   # 指定配置文件
jclean --tasks-root /custom/tasks ...      # 覆盖 tasks_root
```text

### **工作流**

```bash
jclean create <task_id> --source <file> [options]
jclean list
jclean status <task_id>
jclean run <task_id> [--bucket <name>]
jclean clear <task_id>
```text

---

## 💡 关键设计决策

### **1. 路径相对配置文件所在目录**

**理由**：

- 配置文件可以放在项目根目录
- 所有相对路径相对项目根，符合直觉
- 移动项目不需要修改配置

**示例**：

```text
/home/user/project/
├── jclean.toml         # 配置文件
├── tasks/              # tasks_root = "tasks" → 此目录
└── data/
    └── db/
        └── vocabulary.txt  # vocabulary = "data/db/vocabulary.txt" → 此文件
```text

---

### **2. 命令行参数优先级最高**

**理由**：

- 配置文件是默认值，方便日常使用
- 命令行参数是临时覆盖，灵活调试
- 符合 Unix 传统（`--flag` > 配置文件 > 默认值）

---

### **3. 向上查找项目根（遇到 .git 停止）**

**理由**：

- 在子目录运行时自动找到项目根配置
- 遇到 `.git` 说明到达项目根，不再向上
- 用户体验好，无需每次 cd 到项目根

---

### **4. 配置文件可选**

**理由**：

- 没有配置文件时使用默认值，兼容旧版本
- 小项目/快速测试无需配置文件
- 大项目/团队协作推荐使用配置文件

---

## 🎉 完成总结

**配置文件集成已全部完成！**

**核心成果**：

- ✅ 完整的配置文件支持（加载/查找/解析/优先级）
- ✅ CLI 新增 `init-config` / `show-config` 命令
- ✅ 路径灵活（相对/绝对都支持）
- ✅ 多项目友好（独立配置/共享权威库都支持）
- ✅ 73 个测试全部通过
- ✅ 文档完整更新

**总耗时**：约 1.5 小时（如预期）

**可立即使用**：

```bash
cd /path/to/project
jclean init-config           # 生成配置
jclean show-config           # 查看配置
jclean create batch1 --source data/sources/xinbiaori_1.txt
jclean run batch1
```text

🚀 项目已就绪！