刘国栋
8f7f082c3d
- 重构项目目录结构，将功能模块移至 modules/ 目录 - 创建平台同步基础架构，包括发布器基类和 GitHub 发布器 - 新增 UI 状态管理模块 (modules/ui/state.py) 统一管理会话状态 - 更新依赖配置，添加平台同步所需依赖 (httpx, pyperclip) - 整理文档结构，将所有文档分类移至 docs/ 目录 - 添加 .cursorrules 文件定义项目开发规范 - 清理根目录重复文件，保持项目结构整洁
306 lines
9.5 KiB
Markdown
306 lines
9.5 KiB
Markdown
# 项目目录结构优化方案
|
||
|
||
## 📋 当前问题分析
|
||
|
||
### 当前目录结构问题
|
||
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提交**：建议分步骤提交，便于回滚
|