# 配置文件管理方案设计

## 📋 概述

用配置文件管理 `tasks/` 和 `data/db/` 等路径，支持相对路径和绝对路径。

---

## 📁 配置文件格式

**文件名**：`jclean.toml` 或 `.jclean.toml`

**示例配置**：

```toml
# Japanese Cleaner 配置文件
# 路径可以是相对路径（相对本配置文件所在目录）或绝对路径

[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

---

## 🔍 配置文件查找优先级

```text
1. 命令行参数 --config /path/to/config.toml（最高优先级）

2. 当前工作目录
   ./jclean.toml
   ./.jclean.toml

3. 向上查找项目根
   ../jclean.toml
   ../../jclean.toml
   ...（遇到 .git 目录停止）

4. 用户主目录
   ~/.jclean.toml

5. 硬编码默认值（兜底）
   tasks_root = "tasks"
   vocabulary = "data/db/vocabulary.txt"
   skipped = "data/db/skipped.txt"
```text

---

## 🎯 路径解析规则

配置文件中的路径解析：

```python
# 规则：
# 1. 绝对路径 → 直接使用
# 2. 相对路径 → 相对配置文件所在目录

# 示例：配置文件在 /home/user/project/jclean.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

---

## 🛠️ CLI 更新

### **新增命令**

```bash
# 生成示例配置文件
jclean init-config [--output jclean.toml]

# 查看当前配置（调试用）
jclean show-config
```text

### **更新全局参数**

```bash
# 使用自定义配置文件
jclean --config /path/to/custom.toml create batch1 --source ...

# 配置文件中的值可被命令行参数覆盖（命令行优先级最高）
jclean --tasks-root /custom/tasks create batch1 --source ...
```text

---

## 📊 优先级总结

**从高到低**：

```text
1. 命令行参数（--tasks-root / --main / --skipped）
2. 命令行指定的配置文件（--config）
3. 自动查找的配置文件（当前目录 → 项目根 → 用户主目录）
4. 硬编码默认值
```text

---

## 🎨 使用场景

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

在项目根目录创建 `jclean.toml`：

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

使用：

```bash
cd /path/to/project
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：全局配置 + 项目覆盖**

**用户主目录**：`~/.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_specific_vocab.txt"  # 覆盖全局
# tasks_root 继承全局配置
```text

---

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

**项目 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

---

## 🚀 实现清单

### **已完成**

- ✅ `config.py` 模块：加载配置、查找配置文件、解析路径

### **待实现**（需要你确认是否继续）

1. **更新 CLI**（约 30 分钟）
   - 添加 `--config` 全局参数
   - 添加 `init-config` 命令生成示例配置
   - 添加 `show-config` 命令查看当前配置
   - 更新 `create` 命令使用配置文件中的默认值

2. **更新 TaskManager**（约 15 分钟）
   - 构造函数接受 `config: JCleanConfig`
   - 使用 `config.resolve_path()` 解析所有路径

3. **更新文档**（约 15 分钟）
   - README_cleaner.md 添加配置文件说明
   - 生成配置文件示例文档

4. **添加测试**（约 30 分钟）
   - 测试配置文件查找逻辑
   - 测试路径解析（相对/绝对）
   - 测试优先级覆盖

5. **添加 tomli 依赖**（约 5 分钟）
   - 更新 `pyproject.toml` 添加 `tomli` 依赖（Python 3.10 需要）

---

## 💡 设计优点

1. **灵活性**：相对路径/绝对路径都支持
2. **可扩展**：配置文件易于添加新配置项
3. **向后兼容**：没有配置文件时使用硬编码默认值
4. **多项目友好**：每个项目独立配置，或共享全局配置
5. **调试友好**：`show-config` 命令查看当前生效配置

---

## ❓ 需要你决定

**要继续实现吗？**

如果要，我会：

1. 更新 CLI 添加配置文件支持
2. 更新 TaskManager 使用配置
3. 添加测试
4. 更新文档

**如果不要**，当前设计也能工作：

- 继续使用命令行参数（`--tasks-root` / `--main` / `--skipped`）
- 在项目根目录运行 jclean（相对路径）
- 或者每次都传绝对路径

你希望我继续实现配置文件功能吗？还是当前的命令行参数方式已经足够？