刘国栋
8f7f082c3d
- 重构项目目录结构，将功能模块移至 modules/ 目录 - 创建平台同步基础架构，包括发布器基类和 GitHub 发布器 - 新增 UI 状态管理模块 (modules/ui/state.py) 统一管理会话状态 - 更新依赖配置，添加平台同步所需依赖 (httpx, pyperclip) - 整理文档结构，将所有文档分类移至 docs/ 目录 - 添加 .cursorrules 文件定义项目开发规范 - 清理根目录重复文件，保持项目结构整洁
189 lines
5.6 KiB
Markdown
189 lines
5.6 KiB
Markdown
# 深度目录结构优化方案
|
||
|
||
## 📊 当前问题分析
|
||
|
||
### 根目录文件统计
|
||
|
||
**Python 文件（根目录）**：约30+个
|
||
- 主程序：1个（`geo_tool.py` - 必须保留）
|
||
- 重复模块文件：18个（已在 `modules/` 中，应删除根目录版本）
|
||
- 工具脚本：5个（可移动到 `scripts/` 目录）
|
||
- 配置文件：1个（`requirements.txt` - 必须保留）
|
||
|
||
**问题**：
|
||
1. ❌ 根目录有大量重复的模块文件（既在根目录又在 `modules/`）
|
||
2. ❌ 工具脚本混在根目录
|
||
3. ❌ 根目录文件过多，不够整洁
|
||
|
||
## 🎯 优化目标
|
||
|
||
### 理想根目录结构
|
||
|
||
```
|
||
geo_tool/
|
||
├── README.md # 项目主文档
|
||
├── DOCS.md # 文档索引
|
||
├── requirements.txt # 依赖文件
|
||
├── .gitignore # Git配置
|
||
├── .streamlit/ # Streamlit配置
|
||
│ └── config.toml
|
||
├── geo_tool.py # 主程序（唯一入口）
|
||
│
|
||
├── modules/ # 功能模块
|
||
│ └── [所有模块文件]
|
||
│
|
||
├── platform_sync/ # 平台同步模块
|
||
│ └── [平台同步文件]
|
||
│
|
||
├── scripts/ # 工具脚本（新增）
|
||
│ ├── cleanup_duplicate_docs.py
|
||
│ ├── move_reorganization_docs.py
|
||
│ ├── reorganize_files.py
|
||
│ ├── update_imports.py
|
||
│ └── update_doc_references.py
|
||
│
|
||
└── docs/ # 文档目录
|
||
├── features/
|
||
├── analysis/
|
||
├── guides/
|
||
└── implementation/
|
||
```
|
||
|
||
## 📋 优化步骤
|
||
|
||
### 步骤1：清理重复模块文件
|
||
|
||
**需要删除的根目录文件**（18个，已在 `modules/` 中）：
|
||
- `config_optimizer.py`
|
||
- `content_metrics.py`
|
||
- `content_scorer.py`
|
||
- `data_storage.py`
|
||
- `eeat_enhancer.py`
|
||
- `fact_density_enhancer.py`
|
||
- `keyword_mining.py`
|
||
- `keyword_tool.py`
|
||
- `multimodal_prompt.py`
|
||
- `negative_monitor.py`
|
||
- `optimization_techniques.py`
|
||
- `resource_recommender.py`
|
||
- `roi_analyzer.py`
|
||
- `schema_generator.py`
|
||
- `semantic_expander.py`
|
||
- `storage_example.py`
|
||
- `technical_config_generator.py`
|
||
- `topic_cluster.py`
|
||
- `workflow_automation.py`
|
||
|
||
**影响评估**：
|
||
- ⚠️ **中等影响**：需要更新 `geo_tool.py` 中的导入路径
|
||
- ✅ **安全**：`modules/` 中已有完整版本
|
||
|
||
### 步骤2：移动工具脚本
|
||
|
||
**需要移动到 `scripts/` 的文件**（5个）：
|
||
- `scripts/cleanup_duplicate_docs.py`
|
||
- `scripts/move_reorganization_docs.py`
|
||
- `scripts/reorganize_files.py`
|
||
- `scripts/update_imports.py`
|
||
- `scripts/update_doc_references.py`
|
||
|
||
**影响评估**：
|
||
- ✅ **低影响**：这些是工具脚本，不参与主程序运行
|
||
- ✅ **安全**：只是位置移动，不影响功能
|
||
|
||
### 步骤3：更新导入路径
|
||
|
||
**需要更新的文件**：
|
||
1. `geo_tool.py` - 更新所有模块导入（从 `from xxx import` 改为 `from modules.xxx import`）
|
||
2. `modules/storage_example.py` - 更新 `data_storage` 导入
|
||
|
||
**影响评估**：
|
||
- ⚠️ **关键影响**：必须正确更新，否则程序无法运行
|
||
- ✅ **自动化**：可以使用 `scripts/update_imports.py` 脚本自动更新
|
||
|
||
## 🔧 实施计划
|
||
|
||
### 阶段1：准备（低风险）
|
||
|
||
1. ✅ 创建 `scripts/` 目录
|
||
2. ✅ 创建清理脚本
|
||
3. ✅ 备份关键文件
|
||
|
||
### 阶段2：移动工具脚本（低风险）
|
||
|
||
1. 移动工具脚本到 `scripts/`
|
||
2. 更新脚本中的路径引用（如果需要）
|
||
3. 验证脚本仍可正常运行
|
||
|
||
### 阶段3：清理重复文件（中等风险）
|
||
|
||
1. 确认 `modules/` 中所有文件完整
|
||
2. 更新 `geo_tool.py` 的导入路径
|
||
3. 删除根目录的重复文件
|
||
4. 测试程序运行
|
||
|
||
### 阶段4：验证（必须）
|
||
|
||
1. 运行 `python -c "from modules.data_storage import DataStorage"`
|
||
2. 运行 `streamlit run geo_tool.py`
|
||
3. 测试所有功能模块
|
||
|
||
## ⚠️ 风险评估
|
||
|
||
### 改动影响
|
||
|
||
| 操作 | 影响程度 | 风险等级 | 回滚难度 |
|
||
|------|---------|---------|---------|
|
||
| 移动工具脚本 | 低 | 低 | 容易 |
|
||
| 删除重复模块文件 | 中 | 中 | 中等 |
|
||
| 更新导入路径 | 高 | 中 | 容易（有脚本） |
|
||
|
||
### 风险缓解措施
|
||
|
||
1. **Git 提交**：每步完成后立即提交，便于回滚
|
||
2. **自动化脚本**：使用脚本自动更新，减少人为错误
|
||
3. **分步执行**：分阶段执行，每步验证后再继续
|
||
4. **备份**：关键文件备份
|
||
|
||
## 📝 执行命令
|
||
|
||
### 快速执行（推荐）
|
||
|
||
```powershell
|
||
# 1. 创建 scripts 目录
|
||
New-Item -ItemType Directory -Force -Path scripts
|
||
|
||
# 2. 移动工具脚本
|
||
Move-Item cleanup_duplicate_docs.py scripts\ -Force
|
||
Move-Item move_reorganization_docs.py scripts\ -Force
|
||
Move-Item reorganize_files.py scripts\ -Force
|
||
Move-Item update_imports.py scripts\ -Force
|
||
Move-Item update_doc_references.py scripts\ -Force
|
||
|
||
# 3. 更新导入路径（在移动脚本后）
|
||
python scripts/update_imports.py
|
||
|
||
# 4. 删除重复模块文件（在更新导入后）
|
||
# 使用 cleanup_duplicate_modules.py 脚本
|
||
```
|
||
|
||
## ✅ 优化后的优势
|
||
|
||
1. **根目录极简**：只保留必要的入口文件
|
||
2. **结构清晰**：功能模块、工具脚本、文档分类明确
|
||
3. **易于维护**：新功能添加时，只需在对应目录操作
|
||
4. **符合最佳实践**：遵循Python项目标准结构
|
||
|
||
## 🎯 最终根目录文件（约5个）
|
||
|
||
```
|
||
geo_tool/
|
||
├── README.md # 项目主文档
|
||
├── DOCS.md # 文档索引
|
||
├── requirements.txt # 依赖文件
|
||
├── geo_tool.py # 主程序
|
||
└── .gitignore # Git配置
|
||
```
|
||
|
||
**对比**：从 30+ 个文件减少到 5 个核心文件！
|