# Japanese Vocabulary Cleaner

日语词表清理工具 — 半自动处理「汉字 + 假名 + 拼音」三段式词表。

---

## 项目简介

本项目用于清理和规范化日语词表数据，将原始格式转换为标准的三段式格式：

```text
输入：日本人:にほんじん:
输出：日|本|人:に|ほん|じん:ri|ben|ren
```

核心功能：

- 🔍 **自动分割** — 汉字/假名智能对齐，管道符分割
- 🔤 **拼音生成** — 基于 pypinyin + 多音字规则
- 🤖 **智能分类** — 成功/失败/待审核自动分流
- 📋 **任务管理** — 批次隔离、状态机、断点续处理
- ⚙️ **配置驱动** — TOML 配置文件，多项目友好

---

## 快速开始

### 安装

```bash
# 安装项目（开发模式）
pip install -e .

# 验证安装
jclean --help
```

### 创建第一个任务

```bash
# 1. 初始化配置文件（可选）
jclean init-config

# 2. 创建清理任务
jclean create my_task --source data/sources/xinbiaori_1.txt

# 3. 运行任务
jclean run my_task

# 4. 查看状态
jclean status my_task

# 5. 人工修正 review 文件后重跑
jclean run my_task --bucket pinyin
```

详细使用说明见 [README_cleaner.md](README_cleaner.md)。

---

## 项目结构

```text
japanese/
├── src/pl_japanese/
│   ├── cleaner/              # 清理工具核心（三层架构）
│   │   ├── tango_analyser.py    # 底层：单词分析
│   │   ├── task_processor.py    # 中层：文件 I/O、桶管理
│   │   ├── workflow.py           # 顶层：状态机、任务推进
│   │   ├── cli.py                # 命令行接口
│   │   ├── config.py             # 配置文件管理
│   │   └── ...
│   ├── tango/                # Tango 数据模型（下游）
│   └── dict_utils.py         # 词典工具
│
├── tests/                    # 测试（74 个）
│   ├── test_cleaner.py           # 底层单元测试
│   ├── test_cleaner_workflow.py  # 三层集成测试
│   ├── test_config.py            # 配置管理测试
│   └── ...
│
├── scripts/
│   ├── analysis/             # 未来要集成的分析工具
│   │   ├── analyze_phonetics.py  # 发音规律统计
│   │   └── validate_data.py      # 数据质量校验
│   └── legacy/               # 已废弃的旧脚本
│
├── data/
│   ├── db/                   # 权威库（最终成果）
│   │   ├── vocabulary.txt        # 清理完成的词表
│   │   └── skipped.txt           # 跳过的词条
│   └── sources/              # 原始数据源
│
├── tasks/                    # jclean 任务目录（每任务一个子目录）
│   └── my_task/
│       ├── task.json             # 任务元数据
│       ├── auto_done.txt         # 自动处理成功
│       ├── skip.txt              # 跳过（无汉字等）
│       └── review_*.txt          # 待人工确认
│
├── docs/                     # 项目文档
│   ├── design/                   # 设计文档
│   ├── history/                  # 历史记录
│   └── analysis/                 # 分析报告
│
├── reports/                  # 临时分析报告
├── jclean.toml               # jclean 配置文件
├── pyproject.toml            # 项目配置
└── README_cleaner.md         # jclean 用户文档
```

---

## 核心特性

### 三层架构

```text
┌─────────────────────────────────────┐
│  CleanerWorkflow (顶层)              │  状态机、任务推进
│  - run() 统一入口                    │
│  - 状态转换：CREATED → PROCESSING   │
│              → REVIEWING → READY    │
└─────────────────────────────────────┘
              ↓
┌─────────────────────────────────────┐
│  TaskProcessor (中层)                │  文件 I/O、桶管理
│  - process_source()                 │  无状态更新
│  - reprocess_bucket()               │
│  - merge_to_authoritative()         │
└─────────────────────────────────────┘
              ↓
┌─────────────────────────────────────┐
│  TangoAnalyser (底层)                │  单词级分析
│  - analyze(kanji, kana)             │  无文件/桶概念
│  - 返回 AnalysisResult              │
└─────────────────────────────────────┘
```

设计细节见 [docs/design/WORKFLOW.md](docs/design/WORKFLOW.md)。

### 智能分类

处理结果自动分流到 5 个桶：

| 桶名 | 说明 | 自动处理 |
| ------ | ------ | --------- |
| `auto_done.txt` | 成功：单音字、唯一分割 | ✅ |
| `skip.txt` | 跳过：无汉字、纯假名 | ✅ |
| `review_pinyin` | 多音字：已填最常见读音 | ⚠️ 人工 |
| `review_split` | 分割失败：假名对齐失败 | ⚠️ 人工 |
| `review_verb` | 动词形态：する/でした 结尾 | ⚠️ 人工 |
| `review_special` | 特殊格式：片假名/符号/～ | ⚠️ 人工 |

### 配置文件驱动

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

[defaults]
backup_before_merge = true
backup_dir = "data/backup"

[logging]
level = "INFO"
```

配置文件查找顺序：`--config` > 当前目录 > 项目根 > `~/.jclean.toml` > 默认值

详细说明见 [docs/design/CONFIG_FILE_DESIGN.md](docs/design/CONFIG_FILE_DESIGN.md)。

---

## 测试

```bash
# 运行全部测试（74 个）
pytest tests/ -v

# 按模块测试
pytest tests/test_config.py          # 配置管理
pytest tests/test_cleaner_workflow.py # 三层集成
pytest tests/test_cleaner.py          # 底层单元
pytest tests/test_validator.py        # 格式校验
```

---

## 文档

- **用户文档** → [README_cleaner.md](README_cleaner.md) — jclean 工具使用指南
- **设计文档** → [docs/design/](docs/design/) — 架构、工作流、配置方案
- **历史记录** → [docs/history/](docs/history/) — 重构总结、变更日志
- **分析报告** → [docs/analysis/](docs/analysis/) — 数据分析、Review 桶统计

完整文档索引见 [docs/README.md](docs/README.md)。

---

## 开发

### 环境搭建

```bash
# 克隆项目
git clone <repo>
cd japanese

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 安装依赖（开发模式）
pip install -e .
pip install pytest

# 运行测试
pytest tests/
```

### 目录约定

- `src/` — 源代码（src-layout）
- `tests/` — 测试（pytest，pythonpath = ["src"]）
- `tasks/` — jclean 任务工作目录（git ignore）
- `data/db/` — 权威库（最终成果，git 跟踪）
- `data/sources/` — 原始数据源（git 跟踪）
- `docs/` — 项目文档
- `scripts/` — 工具脚本

---

## 版本历史

### v0.3.0 (当前)

- ✅ 配置文件系统（TOML 格式，多项目支持）
- ✅ 配置简化（移除不必要的默认值）
- ✅ UTF-8 BOM 容错
- ✅ 项目目录清理（脚本归档、文档整理）

### v0.2.0

- ✅ 三层架构重构（底层/中层/顶层职责分离）
- ✅ 任务化管理（批次隔离、状态机）
- ✅ CLI 简化（统一 `jclean run` 命令）
- ✅ 73 个测试覆盖

### v0.1.0

- 🗑️ 单文件 500+ 行脚本（已废弃）
- 🗑️ 全局变量、硬编码路径（已重构）

---

## 许可

(待添加)

---

## 联系

(待添加)