feat: 重构项目结构并添加平台同步基础架构

- 重构项目目录结构，将功能模块移至 modules/ 目录 - 创建平台同步基础架构，包括发布器基类和 GitHub 发布器 - 新增 UI 状态管理模块 (modules/ui/state.py) 统一管理会话状态 - 更新依赖配置，添加平台同步所需依赖 (httpx, pyperclip) - 整理文档结构，将所有文档分类移至 docs/ 目录 - 添加 .cursorrules 文件定义项目开发规范 - 清理根目录重复文件，保持项目结构整洁
2026-01-30 10:21:29 +08:00
parent 77d5ec70f8
commit 8f7f082c3d
102 changed files with 33742 additions and 1526 deletions
@@ -0,0 +1,305 @@
+# 项目目录结构优化方案
+
+## 📋 当前问题分析
+
+### 当前目录结构问题
+1. **根目录文件过多**：50+ 个文件混在一起
+   - 15个功能模块（.py文件）
+   - 15个功能文档（*_FEATURE.md）
+   - 7个分析报告（*_ANALYSIS.md, *_REPORT.md）
+   - 5个指南文档（*_GUIDE.md）
+   - 7个实现文档
+   - 主程序（geo_tool.py）
+   - 配置文件
+
+2. **文件引用关系**
+   - `modules/geo_tool.py` 从根目录导入所有模块
+   - 文档之间相互引用，路径混乱
+   - 没有清晰的模块化结构
+
+## 🎯 优化目标
+
+1. **清晰的目录结构**：按功能分类组织文件
+2. **易于维护**：相关文件集中管理
+3. **便于扩展**：新功能易于添加
+4. **保持兼容**：更新所有引用路径
+
+## 📁 优化后的目录结构
+
+```
+geo_tool/
+├── README.md                    # 项目主文档（保留在根目录）
+├── requirements.txt             # 依赖文件（保留在根目录）
+├── .gitignore                   # Git配置（保留在根目录）
+├── .streamlit/                  # Streamlit配置（保留）
+│   └── config.toml
+├── geo_tool.py                  # 主程序（保留在根目录）
+│
+├── modules/                      # 功能模块目录
+│   ├── __init__.py              # 包初始化文件
+│   ├── modules/data_storage.py
+│   ├── modules/keyword_tool.py
+│   ├── modules/content_scorer.py
+│   ├── modules/eeat_enhancer.py
+│   ├── modules/semantic_expander.py
+│   ├── modules/fact_density_enhancer.py
+│   ├── modules/schema_generator.py
+│   ├── modules/topic_cluster.py
+│   ├── modules/multimodal_prompt.py
+│   ├── modules/roi_analyzer.py
+│   ├── modules/workflow_automation.py
+│   ├── modules/keyword_mining.py
+│   ├── modules/optimization_techniques.py
+│   ├── modules/content_metrics.py
+│   ├── modules/technical_config_generator.py
+│   ├── modules/negative_monitor.py
+│   ├── modules/resource_recommender.py
+│   ├── modules/config_optimizer.py
+│   └── storage_example.py
+│
+├── platform_sync/                # 平台同步模块（已存在）
+│   ├── __init__.py
+│   ├── base_publisher.py
+│   ├── github_publisher.py
+│   └── copy_manager.py
+│
+└── docs/                         # 文档目录
+    ├── features/                 # 功能文档
+    │   ├── docs/features/CONFIG_OPTIMIZER_FEATURE.md
+    │   ├── docs/features/CONTENT_METRICS_FEATURE.md
+    │   ├── docs/features/CONTENT_SCORER_FEATURE.md
+    │   ├── docs/features/EEAT_FEATURE.md
+    │   ├── docs/features/FACT_DENSITY_FEATURE.md
+    │   ├── docs/features/JSON_LD_SCHEMA_FEATURE.md
+    │   ├── docs/features/KEYWORD_MINING_FEATURE.md
+    │   ├── docs/features/MULTIMODAL_FEATURE.md
+    │   ├── docs/features/NEGATIVE_MONITOR_FEATURE.md
+    │   ├── docs/features/OPTIMIZATION_TECHNIQUES_FEATURE.md
+    │   ├── docs/features/RESOURCE_RECOMMENDER_FEATURE.md
+    │   ├── docs/features/ROI_ANALYSIS_FEATURE.md
+    │   ├── docs/features/SEMANTIC_EXPANSION_FEATURE.md
+    │   ├── docs/features/TECHNICAL_CONFIG_FEATURE.md
+    │   ├── docs/features/TOPIC_CLUSTER_FEATURE.md
+    │   └── docs/features/WORKFLOW_AUTOMATION_FEATURE.md
+    │
+    ├── analysis/                 # 分析报告
+    │   ├── ANALYSIS_ACCURACY_REPORT.md
+    │   ├── CODE_DOCUMENTATION_ANALYSIS.md
+    │   ├── DOCUMENTATION_REVERSE_VERIFICATION.md
+    │   ├── FEATURE_ANALYSIS.md
+    │   ├── FEATURE_PRIORITY_ANALYSIS.md
+    │   ├── FUNCTION_VERIFICATION_REPORT.md
+    │   └── GEO_COMPLIANCE_ANALYSIS.md
+    │
+    ├── guides/                   # 指南文档
+    │   ├── QUICK_START_GUIDE.md
+    │   ├── STORAGE_GUIDE.md
+    │   ├── PLATFORM_SETUP.md
+    │   ├── LAYOUT_UPGRADE_GUIDE.md
+    │   └── DECISION_GUIDE.md
+    │
+    └── implementation/           # 实现文档
+        ├── IMPLEMENTATION_SUMMARY.md
+        ├── PLATFORM_SYNC_ANALYSIS.md
+        ├── PLATFORM_SYNC_IMPLEMENTATION.md
+        ├── PLATFORM_SYNC_TEST.md
+        ├── INTEGRATION_NOTES.md
+        ├── FEATURES_COMPLETE_LIST.md
+        └── ADVANCED_FEATURES.md
+```
+
+## 🔧 实施步骤
+
+### 步骤1：创建目录结构
+
+```powershell
+# 创建目录
+New-Item -ItemType Directory -Force -Path modules
+New-Item -ItemType Directory -Force -Path docs\features
+New-Item -ItemType Directory -Force -Path docs\analysis
+New-Item -ItemType Directory -Force -Path docs\guides
+New-Item -ItemType Directory -Force -Path docs\implementation
+```
+
+### 步骤2：移动文件
+
+**注意**：如果文件被IDE或其他程序占用，需要先关闭这些程序。
+
+#### 2.1 移动功能模块到 modules/
+```powershell
+# 需要移动的文件列表
+$modules = @(
+    "modules/data_storage.py",
+    "modules/keyword_tool.py",
+    "modules/content_scorer.py",
+    "modules/eeat_enhancer.py",
+    "modules/semantic_expander.py",
+    "modules/fact_density_enhancer.py",
+    "modules/schema_generator.py",
+    "modules/topic_cluster.py",
+    "modules/multimodal_prompt.py",
+    "modules/roi_analyzer.py",
+    "modules/workflow_automation.py",
+    "modules/keyword_mining.py",
+    "modules/optimization_techniques.py",
+    "modules/content_metrics.py",
+    "modules/technical_config_generator.py",
+    "modules/negative_monitor.py",
+    "modules/resource_recommender.py",
+    "modules/config_optimizer.py",
+    "storage_example.py"
+)
+
+foreach ($file in $modules) {
+    if (Test-Path $file) {
+        Move-Item $file -Destination "modules\" -Force
+        Write-Host "Moved: $file"
+    }
+}
+```
+
+#### 2.2 移动功能文档到 docs/features/
+```powershell
+Get-ChildItem -Filter "*_FEATURE.md" | ForEach-Object {
+    Move-Item $_.FullName -Destination "docs\features\" -Force
+    Write-Host "Moved: $($_.Name)"
+}
+```
+
+#### 2.3 移动分析报告到 docs/analysis/
+```powershell
+$analysis = @(
+    "ANALYSIS_ACCURACY_REPORT.md",
+    "CODE_DOCUMENTATION_ANALYSIS.md",
+    "DOCUMENTATION_REVERSE_VERIFICATION.md",
+    "FEATURE_ANALYSIS.md",
+    "FEATURE_PRIORITY_ANALYSIS.md",
+    "FUNCTION_VERIFICATION_REPORT.md",
+    "GEO_COMPLIANCE_ANALYSIS.md"
+)
+
+foreach ($file in $analysis) {
+    if (Test-Path $file) {
+        Move-Item $file -Destination "docs\analysis\" -Force
+        Write-Host "Moved: $file"
+    }
+}
+```
+
+#### 2.4 移动指南文档到 docs/guides/
+```powershell
+$guides = @(
+    "QUICK_START_GUIDE.md",
+    "STORAGE_GUIDE.md",
+    "PLATFORM_SETUP.md",
+    "LAYOUT_UPGRADE_GUIDE.md",
+    "DECISION_GUIDE.md"
+)
+
+foreach ($file in $guides) {
+    if (Test-Path $file) {
+        Move-Item $file -Destination "docs\guides\" -Force
+        Write-Host "Moved: $file"
+    }
+}
+```
+
+#### 2.5 移动实现文档到 docs/implementation/
+```powershell
+$implementation = @(
+    "IMPLEMENTATION_SUMMARY.md",
+    "PLATFORM_SYNC_ANALYSIS.md",
+    "PLATFORM_SYNC_IMPLEMENTATION.md",
+    "PLATFORM_SYNC_TEST.md",
+    "INTEGRATION_NOTES.md",
+    "FEATURES_COMPLETE_LIST.md",
+    "ADVANCED_FEATURES.md"
+)
+
+foreach ($file in $implementation) {
+    if (Test-Path $file) {
+        Move-Item $file -Destination "docs\implementation\" -Force
+        Write-Host "Moved: $file"
+    }
+}
+```
+
+### 步骤3：创建 modules/__init__.py
+
+创建 `modules/__init__.py` 文件，方便导入：
+
+```python
+"""
+GEO Tool 功能模块包
+"""
+```
+
+### 步骤4：更新导入路径
+
+运行 `modules/update_imports.py` 脚本自动更新所有文件中的导入路径。
+
+### 步骤5：更新文档引用
+
+运行 `modules/update_doc_references.py` 脚本自动更新所有文档中的路径引用。
+
+## 📝 需要更新的文件
+
+### Python 文件导入更新
+
+**geo_tool.py** 中的导入需要从：
+```python
+from data_storage import DataStorage
+from keyword_tool import KeywordTool
+# ...
+```
+
+更新为：
+```python
+from modules.data_storage import DataStorage
+from modules.keyword_tool import KeywordTool
+# ...
+```
+
+**storage_example.py** 中的导入需要从：
+```python
+from data_storage import DataStorage
+```
+
+更新为：
+```python
+from modules.data_storage import DataStorage
+```
+
+### 文档路径引用更新
+
+所有 `.md` 文件中的路径引用需要更新：
+
+- `xxx_FEATURE.md` → `docs/features/xxx_FEATURE.md`
+- `xxx_ANALYSIS.md` → `docs/analysis/xxx_ANALYSIS.md`
+- `xxx_GUIDE.md` → `docs/guides/xxx_GUIDE.md`
+- `xxx.md` (implementation) → `docs/implementation/xxx.md`
+
+## ✅ 验证清单
+
+- [ ] 所有模块文件已移动到 `modules/`
+- [ ] 所有文档文件已分类移动到 `docs/` 子目录
+- [ ] `modules/__init__.py` 已创建
+- [ ] `modules/geo_tool.py` 中的导入路径已更新
+- [ ] 所有文档中的路径引用已更新
+- [ ] 运行 `python geo_tool.py` 测试导入是否正常
+- [ ] 检查所有文档链接是否正常
+
+## 🚀 优化后的优势
+
+1. **清晰的目录结构**：文件按功能分类，易于查找
+2. **模块化组织**：功能模块集中管理
+3. **文档分类清晰**：功能文档、分析报告、指南文档分开管理
+4. **便于维护**：新功能添加时，只需在对应目录添加文件
+5. **专业规范**：符合Python项目最佳实践
+
+## 📌 注意事项
+
+1. **文件占用**：移动文件前，确保文件未被IDE或其他程序打开
+2. **路径更新**：移动文件后，必须更新所有引用路径
+3. **测试验证**：完成移动后，务必测试程序是否正常运行
+4. **Git提交**：建议分步骤提交，便于回滚