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）
216 lines
6.3 KiB
Markdown
216 lines
6.3 KiB
Markdown
# 项目目录整理完成总结
|
||
|
||
## ✅ 整理成果
|
||
|
||
### 根目录清理
|
||
|
||
**之前**：13 个 .md 文档 + 4 个 .py 脚本 + 2 个 .txt 报告混在根目录
|
||
|
||
**现在**：只保留 5 个必要文件
|
||
|
||
```text
|
||
japanese/
|
||
├── jclean.toml # 配置文件
|
||
├── pyproject.toml # 项目配置
|
||
├── requirements.txt # 依赖列表
|
||
├── README.md # 项目总览（已重写）
|
||
└── README_cleaner.md # jclean 用户文档
|
||
```text
|
||
|
||
---
|
||
|
||
## 📂 新增目录结构
|
||
|
||
### `docs/` — 项目文档（新建）
|
||
|
||
```text
|
||
docs/
|
||
├── README.md # 文档索引
|
||
├── design/ # 设计文档
|
||
│ ├── CONFIG_FILE_DESIGN.md
|
||
│ └── WORKFLOW.md
|
||
├── history/ # 历史记录
|
||
│ ├── REFACTOR_SUMMARY.md
|
||
│ ├── CONFIG_INTEGRATION_COMPLETE.md
|
||
│ ├── CONFIG_SIMPLIFICATION.md
|
||
│ └── CLEANUP_SUMMARY.md
|
||
└── analysis/ # 分析报告
|
||
└── REVIEW_ANALYSIS.md
|
||
```text
|
||
|
||
### `scripts/` — 工具脚本（重组）
|
||
|
||
```text
|
||
scripts/
|
||
├── analysis/ # 未来要集成的分析工具
|
||
│ ├── README.md
|
||
│ ├── analyze_phonetics.py (194 行)
|
||
│ └── validate_data.py (234 行)
|
||
├── legacy/ # 已废弃的旧脚本
|
||
│ ├── README.md
|
||
│ ├── pipeline.py (443 行，被 jclean 取代)
|
||
│ └── apply_corrections.py (77 行，历史修正已完成)
|
||
└── clean.py # 现有清理脚本
|
||
```text
|
||
|
||
### `reports/` — 临时报告（新建）
|
||
|
||
```text
|
||
reports/
|
||
├── phonetics_report.txt # 发音规律分析结果
|
||
└── validation_report.txt # 数据质量校验结果
|
||
```text
|
||
|
||
---
|
||
|
||
## 📋 移动清单
|
||
|
||
### 文档移动（9 个）
|
||
|
||
| 原位置（根目录） | 新位置 |
|
||
| ------------------------------------- | ------------------------------------------ |
|
||
| CONFIG_FILE_DESIGN.md | docs/design/ |
|
||
| WORKFLOW.md | docs/design/ |
|
||
| REFACTOR_SUMMARY.md | docs/history/ |
|
||
| CONFIG_INTEGRATION_COMPLETE.md | docs/history/ |
|
||
| CONFIG_SIMPLIFICATION.md | docs/history/ |
|
||
| CLEANUP_SUMMARY.md | docs/history/ |
|
||
| REVIEW_ANALYSIS.md | docs/analysis/ |
|
||
| phonetics_report.txt | reports/ |
|
||
| validation_report.txt | reports/ |
|
||
|
||
### 脚本移动（4 个）
|
||
|
||
| 原位置（根目录） | 新位置 |
|
||
| ------------------------------------- | ------------------------------------------ |
|
||
| analyze_phonetics.py | scripts/analysis/ |
|
||
| validate_data.py | scripts/analysis/ |
|
||
| pipeline.py | scripts/legacy/ |
|
||
| apply_corrections.py | scripts/legacy/ |
|
||
|
||
---
|
||
|
||
## 🎯 整理原则
|
||
|
||
### 1. 根目录只保留核心文件
|
||
|
||
- **配置**：`pyproject.toml`、`jclean.toml`、`requirements.txt`
|
||
- **文档**：`README.md`（总览）、`README_cleaner.md`（用户手册）
|
||
- **目录**：`src/`、`tests/`、`data/`、`tasks/`、`docs/`、`scripts/`、`reports/`
|
||
|
||
### 2. 文档按类型分类
|
||
|
||
- **设计文档** → `docs/design/` — 架构、工作流、配置方案
|
||
- **历史记录** → `docs/history/` — 重构总结、变更日志（只增不改）
|
||
- **分析报告** → `docs/analysis/` — 数据分析、统计报告
|
||
|
||
### 3. 脚本按用途分类
|
||
|
||
- **分析工具** → `scripts/analysis/` — 未来要集成到 jclean
|
||
- **废弃脚本** → `scripts/legacy/` — 已被 jclean 取代
|
||
- **现有脚本** → `scripts/` — 当前使用的工具
|
||
|
||
### 4. 临时输出隔离
|
||
|
||
- **报告文件** → `reports/` — 分析工具的临时输出（不入 git）
|
||
|
||
---
|
||
|
||
## 📖 新增索引文档
|
||
|
||
### `docs/README.md`
|
||
|
||
- 完整的文档索引
|
||
- 按类型分组的文档清单
|
||
- 快速导航指引
|
||
- 文档维护规则
|
||
|
||
### `scripts/analysis/README.md`
|
||
|
||
- 分析工具功能说明
|
||
- 依赖要求（pypinyin、jamdict）
|
||
- 当前使用方法
|
||
- 未来集成计划（`jclean analyze` / `jclean validate`）
|
||
|
||
### `scripts/legacy/README.md`
|
||
|
||
- 废弃脚本说明
|
||
- 被取代原因
|
||
- 现代替代方案
|
||
|
||
### `README.md`（根目录，重写）
|
||
|
||
- 项目简介、快速开始
|
||
- 完整目录结构
|
||
- 核心特性（三层架构、智能分类、配置驱动）
|
||
- 测试、文档、开发指南
|
||
- 版本历史
|
||
|
||
---
|
||
|
||
## ✨ 整理效果
|
||
|
||
### 之前（混乱）
|
||
|
||
```text
|
||
japanese/
|
||
├── analyze_phonetics.py # 脚本混在根目录
|
||
├── validate_data.py
|
||
├── pipeline.py
|
||
├── apply_corrections.py
|
||
├── CONFIG_FILE_DESIGN.md # 文档混在根目录
|
||
├── WORKFLOW.md
|
||
├── REFACTOR_SUMMARY.md
|
||
├── CONFIG_INTEGRATION_COMPLETE.md
|
||
├── CONFIG_SIMPLIFICATION.md
|
||
├── REVIEW_ANALYSIS.md
|
||
├── phonetics_report.txt
|
||
├── validation_report.txt
|
||
├── ... (共 20+ 个文件)
|
||
└── src/...
|
||
```text
|
||
|
||
### 现在（清晰）
|
||
|
||
```text
|
||
japanese/
|
||
├── src/ # 源代码
|
||
├── tests/ # 测试
|
||
├── data/ # 数据
|
||
├── tasks/ # 任务工作目录
|
||
├── docs/ # 📚 文档（分类归档）
|
||
├── scripts/ # 🔧 脚本（分类归档）
|
||
├── reports/ # 📊 临时报告
|
||
├── jclean.toml # 配置
|
||
├── pyproject.toml # 项目配置
|
||
├── requirements.txt # 依赖
|
||
├── README.md # 总览
|
||
└── README_cleaner.md # 用户文档
|
||
```text
|
||
|
||
---
|
||
|
||
## 🎉 完成状态
|
||
|
||
✅ **4 个脚本** 从根目录移到 `scripts/analysis/` 和 `scripts/legacy/`
|
||
✅ **7 个文档** 从根目录移到 `docs/design/` 和 `docs/history/` 和 `docs/analysis/`
|
||
✅ **2 个报告** 从根目录移到 `reports/`
|
||
✅ **4 个索引** 新增（`docs/README.md`、`scripts/analysis/README.md`、`scripts/legacy/README.md`、根目录 `README.md` 重写）
|
||
✅ **根目录** 只保留 5 个核心文件
|
||
✅ **目录结构** 清晰、分类明确、易于导航
|
||
|
||
---
|
||
|
||
## 📍 快速导航
|
||
|
||
- **新用户** → [README.md](../README.md) → [README_cleaner.md](../README_cleaner.md)
|
||
- **开发者** → [docs/design/WORKFLOW.md](docs/design/WORKFLOW.md)
|
||
- **了解历史** → [docs/history/](docs/history/) 按时间顺序阅读
|
||
- **查看文档** → [docs/README.md](docs/README.md) 完整索引
|
||
|
||
---
|
||
|
||
**整理完成时间**：当前会话
|
||
**整理原因**：根目录 4 个 py 脚本 + 13 个 md 文档混乱，不利于项目维护
|
||
**整理结果**：目录清晰、分类合理、文档完善、易于导航
|