alphax/docs/PROJECT_STRUCTURE.md

Project Structure

目标

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

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

当前建议心智模型

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

当前已新增的结构化外观层：

• app/web/routes_auth.py
• app/web/routes_recommendations.py
• app/web/routes_strategy.py
• app/web/routes_admin.py
• app/web/routes_pages.py
• app/web/routes_content.py
• app/web/shared.py

当前已新增的 DB 分组接口层：

• app/db/schema.py
• app/db/recommendation_queries.py
• app/db/review_queries.py
• app/db/analytics.py
• app/db/admin_queries.py

当前已新增的统一命令入口：

• app/cli.py

4. 配置与部署

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

5. 前端与模板

• static/
• templates/

6. 开发辅助

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

7. 非主路径归档

• 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

后续建议

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

1. 继续拆 altcoin_db.py
2. 深化 rules.yaml 的子字段 schema 校验
3. 让 docker/ 和文档统一收敛到 app/cli.py

当前结论

这次整理后：

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

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