# 项目文档索引

本目录存放所有项目相关文档，按类型分类组织。

---

## 📂 目录结构

```text
docs/
├── design/      设计文档（架构、工作流、配置方案）
├── history/     历史记录（重构总结、变更日志）
└── analysis/    分析报告（数据分析、Review 桶统计）
```

---

## 📖 文档清单

### `design/` — 设计文档

#### [CONFIG_FILE_DESIGN.md](design/CONFIG_FILE_DESIGN.md)

配置文件系统设计文档

- 配置文件格式（TOML）
- 查找优先级（--config > 当前目录 > 项目根 > 用户主目录）
- 路径解析规则（相对路径相对配置文件所在目录）
- 优先级规则（命令行 > 配置文件 > 默认值）

#### [WORKFLOW.md](design/WORKFLOW.md)

三层架构工作流设计

- 底层：`TangoAnalyser` — 单词分析（无文件概念）
- 中层：`TaskProcessor` — 文件 I/O、桶管理
- 顶层：`CleanerWorkflow` — 状态机、任务推进
- 状态转换图、CLI 命令映射

---

### `history/` — 历史记录

#### [REFACTOR_SUMMARY.md](history/REFACTOR_SUMMARY.md)

最初的大重构总结（单脚本 → 三层架构）

- 重构前的问题（500+ 行单文件、全局变量、职责混乱）
- 三层架构设计决策
- 文件清单（9 个核心模块）
- 73 个测试覆盖

#### [CONFIG_INTEGRATION_COMPLETE.md](history/CONFIG_INTEGRATION_COMPLETE.md)

配置文件集成完成总结（v0.3.0）

- 配置文件功能（init-config / show-config）
- 查找优先级、路径解析规则
- 多项目使用场景（单项目、多项目隔离、共享权威库）
- UTF-8 BOM 容错修复

#### [CONFIG_SIMPLIFICATION.md](history/CONFIG_SIMPLIFICATION.md)

配置文件简化总结（移除不必要配置项）

- 移除 `sources_dir`、`default_start_line`、`default_count`
- `count: Optional[int] = None` 语义（None = 处理到文件末尾）
- CLI 默认行为变更（--start 默认 1，--count 默认全部）
- 配置文件精简（3 个段 → 2 个段）

#### [CLEANUP_SUMMARY.md](history/CLEANUP_SUMMARY.md)

项目目录清理总结

- 根目录脚本分类移动（analysis / legacy）
- 文档归档到 docs/
- 临时报告移到 reports/

---

### `analysis/` — 分析报告

#### [REVIEW_ANALYSIS.md](analysis/REVIEW_ANALYSIS.md)

Review 桶数据分析（tasks/legacy_batch1/）

- 341 条待审核数据的分布统计
- review_pinyin: 218 条（多音字）
- review_split: 79 条（假名分割失败）
- review_verb: 37 条（动词形态）
- review_special: 7 条（特殊格式）
- 典型案例分析和修正建议

---

## 🗂️ 其他文档位置

### 根目录

- `README.md` — 项目总览
- `README_cleaner.md` — jclean 工具用户文档
- `jclean.toml` — jclean 配置文件（示例）

### 脚本目录

- `scripts/analysis/README.md` — 分析工具说明（待集成）
- `scripts/legacy/README.md` — 已废弃脚本说明

### 临时报告

- `reports/phonetics_report.txt` — 发音规律分析结果
- `reports/validation_report.txt` — 数据质量校验结果

---

## 📝 文档维护规则

1. **设计文档** (`design/`) — 重大架构变更时更新
2. **历史记录** (`history/`) — 每次重构/重大变更后添加总结，只增不改
3. **分析报告** (`analysis/`) — 数据分析结果，按需生成
4. **用户文档** (根目录) — 与代码同步更新

---

## 🔗 快速导航

- **新用户**：先读 [README.md](../README.md)，再读 [README_cleaner.md](../README_cleaner.md)
- **开发者**：读 [WORKFLOW.md](design/WORKFLOW.md) 了解架构
- **了解历史**：按时间顺序读 `history/` 目录
- **数据分析**：看 `analysis/` 和 `reports/`