alphax/docs/PROJECT_STRUCTURE.md

Project Structure

目标

这次整理的目标不是把项目“重写成新架构”，而是先把目录语义拉清楚：

• 根目录只放主运行链路和顶层配置
• 工具脚本集中到 tools/
• 校验脚本集中到 scripts/
• 模板资源集中到 templates/
• 运行/分析产物集中到 reports/
• 历史遗留与备份集中到 legacy/

当前建议心智模型

1. 真实实现层

真实实现现在集中在 app/ 下：

• app/services/
• app/db/
• app/core/
• app/config/
• app/integrations/
• app/analysis/
• app/web/

2. 运行主链路

• app/services/altcoin_screener.py
• app/services/altcoin_confirm.py
• app/services/price_tracker.py
• app/services/event_driven_screener.py
• app/services/review_engine.py
• app/web/web_server.py

3. 核心共享层

• app/db/altcoin_db.py
• app/db/auth_db.py
• app/config/config_loader.py
• app/core/opportunity_lifecycle.py
• app/core/pa_engine.py
• app/core/sector_map.py
• app/integrations/feishu_push.py
• app/integrations/feishu_review_push.py

4. 配置与部署

• rules.yaml
• .env.example
• Dockerfile
• docker-compose.yml
• docker/

5. 前端与模板

• static/
• templates/

6. 开发辅助

• tests/
• scripts/
• tools/
• docs/

7. 非主路径归档

• legacy/
• reports/

已整理的文件

移入 tools/

• backtest.py -> tools/backtest.py
• extract_summary.py -> tools/extract_summary.py
• summarize_output.py -> tools/summarize_output.py

移入 scripts/

• validate_params.py -> scripts/validate_params.py

移入 templates/

• stock_report_template.html -> templates/stock_report_template.html

移入 reports/

• backtest_result.json -> reports/backtest_result.json

移入 docs/reference/

• schema.py -> docs/reference/schema_reference.py

移入 legacy/

• coin_state_tracker.py
• price_tracker_ws.py
• legacy/web/index.html
• legacy/static/app.html.bak
• legacy/scratch/*

后续建议

如果继续整理，建议下一步做实现层拆分，而不是再搬目录：

1. 拆 web_server.py
2. 拆 altcoin_db.py
3. 为 rules.yaml 增加 schema 校验
4. 为主脚本建立统一 CLI 入口

当前结论

这次整理后：

• app/ 承载真实实现
• 根目录不再堆放业务实现脚本
• 旧工具/旧资产/产物不再继续污染主目录

这不是最终态，但已经从“所有实现都摊在根目录”进到了“实现按职责分层”的可维护阶段。