刘国栋
8f7f082c3d
- 重构项目目录结构，将功能模块移至 modules/ 目录 - 创建平台同步基础架构，包括发布器基类和 GitHub 发布器 - 新增 UI 状态管理模块 (modules/ui/state.py) 统一管理会话状态 - 更新依赖配置，添加平台同步所需依赖 (httpx, pyperclip) - 整理文档结构，将所有文档分类移至 docs/ 目录 - 添加 .cursorrules 文件定义项目开发规范 - 清理根目录重复文件，保持项目结构整洁
204 lines
5.8 KiB
Markdown
204 lines
5.8 KiB
Markdown
# 最终目录结构优化指南
|
||
|
||
## ✅ 当前状态检查
|
||
|
||
### 已完成的优化
|
||
- ✅ `geo_tool.py` 已更新导入路径（使用 `modules.xxx`）
|
||
- ✅ `modules/storage_example.py` 已更新导入路径
|
||
- ✅ 文档已分类移动到 `docs/` 目录
|
||
- ✅ 重组相关文档已移动到 `docs/guides/`
|
||
|
||
### 待优化的部分
|
||
- ⏳ 根目录仍有18个重复的模块文件（已在 `modules/` 中）
|
||
- ⏳ 根目录有5个工具脚本（可移动到 `scripts/`）
|
||
|
||
## 🎯 优化目标
|
||
|
||
### 优化前（根目录约30+个文件）
|
||
```
|
||
geo_tool/
|
||
├── README.md
|
||
├── DOCS.md
|
||
├── geo_tool.py
|
||
├── requirements.txt
|
||
├── [18个重复模块文件] ❌
|
||
├── [5个工具脚本] ❌
|
||
└── ...
|
||
```
|
||
|
||
### 优化后（根目录约5个文件）
|
||
```
|
||
geo_tool/
|
||
├── README.md # ✅ 保留
|
||
├── DOCS.md # ✅ 保留
|
||
├── geo_tool.py # ✅ 保留（主程序）
|
||
├── requirements.txt # ✅ 保留
|
||
├── .gitignore # ✅ 保留
|
||
│
|
||
├── modules/ # ✅ 功能模块
|
||
├── platform_sync/ # ✅ 平台同步
|
||
├── scripts/ # ✅ 工具脚本（新增）
|
||
└── docs/ # ✅ 文档目录
|
||
```
|
||
|
||
## 📋 优化步骤（安全执行）
|
||
|
||
### 步骤1：移动工具脚本（低风险，先执行）
|
||
|
||
**操作**：将工具脚本移动到 `scripts/` 目录
|
||
|
||
**执行**：
|
||
```powershell
|
||
python move_scripts.py
|
||
```
|
||
|
||
**影响**：
|
||
- ✅ 低风险：工具脚本不参与主程序运行
|
||
- ✅ 可回滚：如有问题可轻松恢复
|
||
|
||
**验证**：
|
||
```powershell
|
||
# 测试脚本是否仍可运行
|
||
python scripts/update_imports.py --help
|
||
```
|
||
|
||
### 步骤2：清理重复模块文件（中等风险，需谨慎）
|
||
|
||
**前提条件**：
|
||
- ✅ 已确认 `geo_tool.py` 使用 `modules.xxx` 导入
|
||
- ✅ 已测试程序可以正常运行
|
||
|
||
**执行**：
|
||
```powershell
|
||
python cleanup_duplicate_modules.py
|
||
```
|
||
|
||
**影响**：
|
||
- ⚠️ 中等风险：删除后无法直接恢复（需从Git恢复）
|
||
- ✅ 安全：`modules/` 中已有完整版本
|
||
|
||
**验证**：
|
||
```powershell
|
||
# 1. 测试导入
|
||
python -c "from modules.data_storage import DataStorage; print('✓ 导入成功')"
|
||
|
||
# 2. 测试主程序
|
||
streamlit run geo_tool.py
|
||
```
|
||
|
||
## 🔍 详细文件清单
|
||
|
||
### 需要删除的重复模块文件（18个）
|
||
|
||
这些文件在根目录和 `modules/` 目录都存在，删除根目录版本：
|
||
|
||
1. `config_optimizer.py`
|
||
2. `content_metrics.py`
|
||
3. `content_scorer.py`
|
||
4. `data_storage.py`
|
||
5. `eeat_enhancer.py`
|
||
6. `fact_density_enhancer.py`
|
||
7. `keyword_mining.py`
|
||
8. `keyword_tool.py`
|
||
9. `multimodal_prompt.py`
|
||
10. `negative_monitor.py`
|
||
11. `optimization_techniques.py`
|
||
12. `resource_recommender.py`
|
||
13. `roi_analyzer.py`
|
||
14. `schema_generator.py`
|
||
15. `semantic_expander.py`
|
||
16. `storage_example.py`
|
||
17. `technical_config_generator.py`
|
||
18. `topic_cluster.py`
|
||
19. `workflow_automation.py`
|
||
|
||
### 需要移动的工具脚本（5个）
|
||
|
||
这些脚本移动到 `scripts/` 目录：
|
||
|
||
1. `scripts/cleanup_duplicate_docs.py`
|
||
2. `scripts/move_reorganization_docs.py`
|
||
3. `scripts/reorganize_files.py`
|
||
4. `scripts/update_imports.py`
|
||
5. `scripts/update_doc_references.py`
|
||
|
||
## ⚠️ 风险评估与缓解
|
||
|
||
### 风险1：删除重复文件后程序无法运行
|
||
|
||
**概率**：低（已确认导入路径已更新）
|
||
|
||
**缓解措施**：
|
||
1. 先测试：`python -c "from modules.data_storage import DataStorage"`
|
||
2. 再删除：确认测试通过后再执行删除
|
||
3. Git备份：删除前先提交，便于回滚
|
||
|
||
### 风险2：工具脚本移动后无法使用
|
||
|
||
**概率**：极低（只是位置移动）
|
||
|
||
**缓解措施**：
|
||
1. 更新使用方式：`python scripts/script_name.py`
|
||
2. 测试脚本：移动后立即测试
|
||
|
||
### 风险3：遗漏某些导入路径
|
||
|
||
**概率**：低（已检查 `geo_tool.py`）
|
||
|
||
**缓解措施**：
|
||
1. 全局搜索：`grep -r "from data_storage import" .`
|
||
2. 运行测试：完整测试所有功能
|
||
|
||
## 📝 完整执行清单
|
||
|
||
### 准备阶段
|
||
- [ ] 确认 Git 仓库状态（建议先提交当前更改）
|
||
- [ ] 备份关键文件（可选，Git已提供版本控制）
|
||
- [ ] 阅读本指南
|
||
|
||
### 执行阶段
|
||
- [ ] 步骤1：运行 `python move_scripts.py`
|
||
- [ ] 验证：测试脚本是否仍可运行
|
||
- [ ] 步骤2：运行 `python cleanup_duplicate_modules.py`
|
||
- [ ] 验证：测试导入 `python -c "from modules.data_storage import DataStorage"`
|
||
- [ ] 验证：运行主程序 `streamlit run geo_tool.py`
|
||
|
||
### 验证阶段
|
||
- [ ] 检查根目录文件数量（应该只有5个左右）
|
||
- [ ] 测试所有主要功能模块
|
||
- [ ] 确认没有导入错误
|
||
- [ ] Git 提交优化结果
|
||
|
||
## 🎉 优化后的优势
|
||
|
||
1. **根目录极简**：从30+个文件减少到5个核心文件
|
||
2. **结构清晰**：功能模块、工具脚本、文档分类明确
|
||
3. **易于维护**：新功能添加时，只需在对应目录操作
|
||
4. **符合最佳实践**：遵循Python项目标准结构
|
||
5. **便于协作**：团队成员更容易理解项目结构
|
||
|
||
## 📚 相关文档
|
||
|
||
- `ADVANCED_OPTIMIZATION_PLAN.md` - 详细优化方案
|
||
- `cleanup_duplicate_modules.py` - 清理重复模块脚本
|
||
- `move_scripts.py` - 移动工具脚本脚本
|
||
|
||
## 🆘 遇到问题？
|
||
|
||
### 问题1：删除文件后程序无法运行
|
||
**解决方案**：
|
||
1. 从Git恢复：`git checkout HEAD -- filename.py`
|
||
2. 检查导入路径：确认使用 `modules.xxx` 格式
|
||
3. 重新测试：`python -c "from modules.data_storage import DataStorage"`
|
||
|
||
### 问题2：工具脚本无法运行
|
||
**解决方案**：
|
||
1. 使用完整路径：`python scripts/script_name.py`
|
||
2. 或在 `scripts/` 目录下运行：`cd scripts && python script_name.py`
|
||
|
||
### 问题3：遗漏某些文件
|
||
**解决方案**：
|
||
1. 检查 `modules/` 目录：确认所有模块文件都在
|
||
2. 检查导入错误：运行程序查看具体错误信息
|
||
3. 从Git恢复：`git checkout HEAD -- .`
|