ef3df73166
清洗管线重构为严格三层架构：
- tango_analyser.py（底层：单词分析）
- task_processor.py（中层：文件 I/O、桶管理）
- workflow.py（顶层：状态机、任务推进）
- 移除旧的 batch_processor.py
新增配置文件系统：
- config.py：TOML 配置，相对路径相对配置文件目录解析
- 查找优先级 --config > cwd > 项目根 > ~ > 默认值
- count=None 语义为处理到文件末尾
项目目录整理：
- 根脚本归档到 scripts/analysis 与 scripts/legacy
- 文档归档到 docs/{design,history,analysis}
- 临时报告移到 reports/（已 gitignore）
文档质量：
- 新增 .markdownlint.json 与 scripts/mdlint.cmd
- 修复全部 14 个 md 文件的 markdownlint 警告
测试：74 passed（8 cleaner + 31 workflow + 6 tango + 15 validator + 14 config）
131 lines
3.6 KiB
Markdown
131 lines
3.6 KiB
Markdown
# 项目文档索引
|
||
|
||
本目录存放所有项目相关文档，按类型分类组织。
|
||
|
||
---
|
||
|
||
## 📂 目录结构
|
||
|
||
```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/`
|