# 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/` 承载真实实现
- 根目录不再堆放业务实现脚本
- 旧工具/旧资产/产物不再继续污染主目录

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