# Japanese Cleaner - 日语词表清洗工具

工程化的日语词表清洗流水线，自动化处理汉字-假名-拼音对齐。采用**任务化架构**：
每次清洗是一个跨会话、有状态、可并存的任务。

> 完整协作规范见 [`WORKFLOW.md`](WORKFLOW.md)。

## 功能特性

- **任务化**：每次清洗是独立任务（独立配置 + 独立临时文件 + 状态机），多任务可并存
- **两层分离**：单批临时工作区 / 最终只增去重的权威库
- **数据源只读**：处理时不修改原文件，支持任意切片（起始行 + 条数）
- **严格校验**：输入输出条数自动校验
- **半自动协作**：自动分流 + 人工 review + 改代码重跑
- **单元测试**：核心逻辑全覆盖

## 数据目录布局

```
data/
├── db/                          # 权威成品库（只增不删 + 去重）
│   ├── vocabulary.txt           # 所有批次累积的成品
│   └── skipped.txt              # 所有批次累积的跳过项
├── sources/                     # 原始数据源（只读）
│   └── xinbiaori_1.txt
└── backup/                      # 备份
    └── *.backup.txt

tasks/
└── {task_id}/                   # 每个任务独立目录
    ├── task.json                # 任务配置 + 状态
    ├── auto_done.txt            # 单批结果
    ├── skip.txt
    └── review_*.txt             # 待确认桶
```

## 入口方式

本项目的清洗流程**需要人工介入**（review 循环：改字典/规则 → 重跑），因此
**推荐用测试驱动**协作（见 [`tests/test_cleaner_workflow.py`](tests/test_cleaner_workflow.py)），
命令行只是便捷入口。

三种等价的命令行入口：

```bash
jclean <cmd> ...                          # 安装后的 console 命令（推荐）
python -m pl_japanese.cleaner.cli <cmd> ... # 模块调用（无需 console 入口）
python scripts/clean.py <cmd> ...          # 兼容薄壳（未安装包时）
```

安装（开发模式，注册 `jclean` 命令）：

```bash
pip install -e .
```

## 快速开始

```bash
# 创建任务（数据源只读，可指定处理范围）
jclean create batch1 --source data/sources/xinbiaori_1.txt --start 1 --count 300

# 处理一批数据（分流到单批文件）
jclean process batch1

# 查看任务状态
jclean status batch1

# 列举所有任务
jclean list

# 重跑某个 review 桶（修正字典/规则后）
jclean reprocess batch1 --bucket pinyin

# 合并单批结果到权威库（review 全清零后）
jclean merge batch1 --dry-run   # 先校验
jclean merge batch1             # 正式合并

# 清空任务的单批文件
jclean clear batch1
```

## 代码调用

```python
from pl_japanese.cleaner import TaskManager, BatchProcessor

tm = TaskManager()

# 创建任务（权威库路径默认全局，可覆盖）
task = tm.create_task(
    task_id='batch1',
    source='data/sources/xinbiaori_1.txt',
    start_line=1,
    count=300,
)

# 处理一批
bp = BatchProcessor(task)
result = bp.process_batch()
print(f"处理 {result['valid_lines']} 条，auto {result['buckets']['auto']} 条")

# review 全清零后合并
bp.merge_all(dry_run=True)   # 校验
bp.merge_all()               # 正式合并
```

## 任务状态机

```
created → processing → reviewing → ready → merged
```

- `created` — 已创建，未处理
- `processing` — 已跑分类
- `reviewing` — review 中，部分桶待确认
- `ready` — review 全清零，待合并
- `merged` — 已合并进权威库，完成

## 核心规则

| 规则 | 说明 | 例 |
|------|------|-----|
| 无汉字词跳过 | 汉字段不含汉字 → `skip` | `IT:アイティー:` |
| 混合词正常处理 | 字母作为独立段 | `JC|自|動|車:...` |
| 含~自动处理 | ~ 是任意长通配，对齐后丢弃 | `経営～:けいえいします:` → `経|営:けい|えい:jing|ying` |
| ます形转原型 | 五段/一段动词转辞書形（词典验证） | |
| 完整表达保留 | 寒暄句保留 ます → `review_verb` | |
| 々展开 | 同字重复符号自动展开 | `我々:われわれ:` → `我|我:われ|われ:wo|wo` |

完整规则见 [`tests/data/rules.md`](tests/data/rules.md)。

## 输出分类桶

**自动分类：**
- `auto_done.txt` — 高置信度，可直接使用
- `skip.txt` — 无汉字词，已跳过

**需人工确认：**
- `review_pinyin.txt` — 含多音字，需校对拼音
- `review_split.txt` — 假名分割失败，需手动处理
- `review_verb.txt` — 动词/完整表达，需确认形式
- `review_special.txt` — 含字母/片假名，需人工判断

## 关键设计原则

1. **任务化** — 每次清洗是有状态、可并存的任务，路径是任务配置而非全局配置
2. **数据源只读** — 处理时不修改原文件
3. **单批/最终两层分离** — 单批临时工作区，权威库只增去重
4. **改代码而非改文件** — 指出问题后改字典/规则重跑，不手改输出文件
5. **合并需授权** — 只有明确说"合并"才执行合并到权威库
6. **去重保证幂等** — 多次合并同一数据不会重复

## 项目结构

```
japanese/
├── src/pl_japanese/cleaner/     # 核心模块
│   ├── task.py                  # 任务模型（配置 + 状态机）
│   ├── task_manager.py          # 任务管理器
│   ├── batch_processor.py       # 批处理调度
│   ├── classifier.py            # 词条分类
│   ├── aligner.py               # 汉字-假名对齐
│   ├── pinyin_maker.py          # 拼音生成
│   ├── pinyin_overrides.py      # 多音字覆盖字典
│   ├── rules.py                 # 规则配置
│   ├── validator.py             # 格式校验
│   ├── cli.py                   # 命令行外壳（jclean 入口）
│   └── __main__.py              # python -m 入口
├── scripts/clean.py             # CLI 兼容薄壳（未安装包时用）
├── data/                        # 数据（db / sources / backup）
├── tasks/                       # 任务目录
└── tests/
    ├── test_cleaner_workflow.py # 工作流测试（任务驱动协作）
    └── ...
```

## 运行测试

```bash
pytest tests/ -v
```

工作流本身需要人工介入，日常"处理 → review → 重跑 → 合并"协作推荐用
[`tests/test_cleaner_workflow.py`](tests/test_cleaner_workflow.py) 里的任务驱动方式，
或 `jclean` / `python -m pl_japanese.cleaner.cli` 命令行。

## 依赖

- Python 3.11+
- jamdict / pypinyin / pydantic / loguru
- pytest（测试）