# AGENTS.md

## 1. 项目定位

AlphaX 是一个以 `Python + FastAPI + PostgreSQL + Docker + 静态 HTML` 组成的加密市场机会监控系统。当前核心目标不是完整自动交易执行，而是围绕“发现机会 -> 确认机会 -> 跟踪机会 -> 复盘迭代”建立一套可持续优化的研究、提示、模拟交易和复盘闭环。

当前仓库是一个 Docker 化运行目录。运行时数据库已经切换为 PostgreSQL；SQLite 只作为历史数据导入来源，不再作为应用运行时数据库。后续开发和排查都应以 PostgreSQL、`DATABASE_URL`、Docker 服务和当前 migration 为准。

## 2. 当前技术栈

- 后端：`FastAPI`, `uvicorn`, `pydantic`
- 数据库：PostgreSQL 16，连接入口为 `DATABASE_URL`
- 数据访问：`psycopg` + 兼容旧 row 读取方式的 `DbRow`
- 数据与计算：`pandas`, `numpy`
- 交易所/行情：`ccxt`, `requests`
- 配置：`rules.yaml` + `app/config/config_loader.py` + `system_config`/runtime DB 配置
- 测试：`pytest` / `unittest`
- 部署：`Dockerfile`, `docker-compose.yml`
- 前端：`static/*.html` 页面，由 FastAPI/Jinja2 提供页面壳和 API

## 3. 真实运行架构

### 3.1 Docker 服务

当前 `docker-compose.yml` 定义的核心服务：

- `postgres`
  - PostgreSQL 16
  - 默认宿主机端口 `5433 -> 5432`
  - 数据保存在 compose volume `postgres_data`
- `alphax-web`
  - FastAPI + 页面/API
  - 默认宿主机端口 `8191 -> 8190`
  - 启动入口：`app.web.web_server:app`
- `alphax-scheduler`
  - 后台调度器
  - 从 PostgreSQL 中读取任务配置和运行状态
  - 以并发子进程运行，通过 lock group 避免关键写路径冲突
- `alphax-price-streamer`
  - 实时价格流服务
  - 更新最新价格缓存，供页面和部分链路读取

关键原则：

- PostgreSQL 是唯一运行时数据库。
- `DATABASE_URL` 是唯一运行时数据库连接入口。
- SQLite 只用于历史导入脚本，不参与应用运行。
- `.env`、`data/`、数据库文件、日志等不应被打进镜像。

### 3.2 数据库入口

- `app/db/schema.py`
  - PostgreSQL schema/init 门面。
  - `init_db()` 实际调用 `apply_migrations()`。
  - `get_conn` 来自 `app.db.postgres_connection.connect`。
- `app/db/postgres_connection.py`
  - PostgreSQL 连接、migration、row factory 的底层实现。
  - `DbRow` 用于兼容旧代码里按下标读取 row 的过渡逻辑。
- `app/db/migrations/*.sql`
  - PostgreSQL migration 单一事实源。
  - 新表/字段优先新增 migration，不要在业务函数里临时补 schema。

### 3.3 调度入口

- `docker/entrypoint.sh`
  - `web` -> 启动 uvicorn
  - `scheduler` -> 启动 `docker/scheduler.py`
  - `price-streamer` -> 启动实时价格流
  - `once` -> 执行单次命令
- `docker/scheduler.py`
  - 从 `scheduler_job_config` 加载任务。
  - 写入 `scheduler_runtime_status`。
  - 支持 `scheduler_manual_trigger` 手动触发。
  - 使用 lock group 控制并发冲突。
- `app/cli.py`
  - 统一命令入口：`screener`, `confirm`, `tracker`, `paper-trader`, `price-streamer`, `market`, `review`, `event`, `sentiment`, `onchain`, `llm-insights`。

## 4. 代码主线

### 4.1 推荐系统业务闭环

建议把系统理解为 9 个层次：

1. `app/services/market_overview.py`
   采集全市场快照，为行情环境、涨幅榜和市场温度提供数据。
2. `app/services/altcoin_screener.py`
   负责粗筛/细筛，基于 Binance 行情、量价/结构等规则找候选币；同时写入交易宇宙缓存和覆盖率审计，方便排查“是否扫全、哪里漏掉”。
3. `app/services/altcoin_confirm.py`
   负责确认，判断候选是否形成更可执行的机会，并生成入场计划、上下文和推送候选。
4. `app/services/event_driven_screener.py`
   负责事件/舆情驱动的快速触发检查，是技术筛选主链路的补充入口。
5. `app/services/price_streamer.py`
   负责实时价格缓存，不等同于完整推荐状态跟踪。
6. `app/services/price_tracker.py`
   负责可执行推荐的价格跟踪、状态迁移和动态风险提示。
7. `app/services/paper_trader.py`
   负责模拟交易账本同步，真实 TP/SL、移动止盈、杠杆和资金口径在 paper trading 层管理。
8. `app/db/live_trading.py` / `app/web/routes_live_trading.py`
   负责实盘控制台：多交易所/多 API 账户配置、账号级风控、交易所接口验收和执行审计事件。页面不再使用“订单意图”作为产品概念，也不区分 Demo/正式环境，实际环境由 endpoint/API key 配置决定。
9. `app/services/review_engine.py`
   负责复盘与策略自迭代，包括信号绩效、漏选复盘、规则候选、版本演进。

### 4.1.1 因子评分与复盘进化

- 核心认知：因子不等于策略。一个因子可以是先决条件、触发、确认、入场、风控或归因，但不能因为单个因子表现好就直接升级成完整策略。
- 完整策略必须至少包含：适用市场环境、交易宇宙、先决条件、核心触发、辅助确认、入场规则、止盈止损、失效条件、仓位/杠杆约束和独立复盘口径。
- 多策略链路必须保持独立：`main_composite_v1`、`box_retest_1h_v1`、`box_retest_4h_v1` 等策略可以共享行情、账户级风控和执行框架，但不能共享同一套入场门槛、RR、挂单距离和 paper trading 执行门禁。
- 策略级配置入口在 `app/core/strategy_registry.py`，`StrategyDefinition.entry_gate_config` 控制确认/跟踪/展示派生的买点质量闸门，`StrategyDefinition.paper_config` 控制该策略进入 paper trading 的入场、挂单和动态杠杆门槛。
- 新增策略时必须注册稳定 `strategy_code`，并明确自己的 `entry_gate_config` / `paper_config`。不要把新策略的特殊门槛写进全局 `paper_trading_config()` 或 `DEFAULT_ENTRY_GATE`，否则会影响其他策略的信号生成和成交样本。
- `apply_entry_quality_gate()` 必须传入或从 `entry_plan.strategy_code` 派生策略身份；`paper_trader.py` 中开仓、挂单、挂单成交和挂单维护应通过策略级配置合并后的参数执行。
- `app/core/factor_scoring.py` 是确认层因子评分中心。新增确认加减分不要继续散落写死 `score += N`，应优先通过 `FactorScorer.delta(factor_code, base_delta, evidence=...)` 计算。
- 稳定因子代码来自 `app/core/signal_taxonomy.py`，例如 `vp_fly_1h_current`、`volume_consecutive_1h`、`ignition_d1_current`、`sector_rotation`、`sentiment_resonance`、`top_trader_long`、`risk_reward_bad`。
- `signal_performance` 是复盘后动态权重来源；`review_engine.py` 更新信号绩效后，`config_loader.get_signal_weights()` 会让下一轮筛选/确认读取生效权重。
- 当前确认层已把核心技术因子、资金面因子、板块因子、舆情因子和买点风险因子接入 `FactorScorer`，并在 `market_context.factor_score_breakdown` / `entry_plan.factor_score_breakdown` 中保留因子明细。
- `FactorScorer` 已加入因子组去相关，同一类 `momentum` / `structure` / `entry_quality` / `onchain_flow` / `narrative` 信号会受 group cap 限制，避免同一根行情被重复加分。
- 小样本复盘不能直接杀死核心因子。`signal_performance` 的动态权重至少要满足 `review.min_samples_for_weight` 与 `review.signal_deprecation.min_samples` 后才覆盖确认层基线；未达样本门槛时只用于观察，不应用 0 权重把 15min 启动、日线突破回踩等因子压没。
- 扣分因子应传负数，例如 `FactorScorer.delta("false_breakout", -5, ...)`，不要再外部 `score -= delta`，否则 `factor_score_breakdown` 会把风险误记成正向贡献。
- 确认层会输出 `score_components`：`opportunity_score` 表示机会质量，`entry_score` 表示买点质量，`risk_score` 表示扣分风险；后续策略不要再只看单一 `rec_score`。
- `market_context.decision_log` / `entry_plan.decision_log` 是结构化决策解释；paper trading 开仓事件也会记录当时 `market_regime`、`global_risk` 和 `score_components`。
- NodeReal 链上因子通过 `app/db/onchain_db.py#get_onchain_factor_context()` 进入确认层，正向事件如 `whale_accumulation`、`smart_money_buying`、`exchange_outflow` 会加分，风险事件如 `exchange_inflow_risk`、`liquidity_remove_risk`、`holder_concentration_risk` 会扣分；这些因子同样受 `signal_performance.weight` 复盘权重约束。
- 后续新增链上、资金、事件、舆情等非 K 线因子时，必须给出稳定 `factor_code`、默认基准权重、证据字段和复盘归因口径，避免只做展示标签而不参与策略进化。
- `box_breakout_pullback_4h` 是 4H 箱体突破回踩强结构因子，不是完整策略；它可以作为 `box_retest_4h_v1` 这类策略的核心触发，但仍必须经过市场环境、交易宇宙、确认、入场、风控和失效条件。

### 4.1.2 多策略架构方向

- 多策略改造计划记录在 `docs/MULTI_STRATEGY_ARCHITECTURE.md`。后续做策略级改造前必须先阅读并更新该文档。
- 目标架构是：统一交易宇宙 -> 多个独立策略并行扫描 -> 标准策略信号 -> 冲突/重复仲裁 -> 推荐/观察/挂单 -> paper trading 保留策略血缘 -> 按策略独立复盘。
- `strategy_version` 只表示版本，不应替代策略身份；后续推荐、挂单和交易账本都应补充 `strategy_code`、`strategy_signal_id`、`strategy_snapshot_json` 和 `factor_roles_json`。
- 现有综合确认链路在迁移期应标记为 `main_composite_v1`，避免无策略来源的推荐继续进入 paper trading。
- 第一个建议拆出的独立策略是 `box_retest_4h_v1`：核心触发来自 `box_breakout_pullback_4h`，但策略成立还需要市场环境、交易量、回踩距离、15m/1H 承接、盈亏比、失效条件和账户风控。
- 新增策略必须先 observe-only 或 paper-only 积累样本，再进入灰度/发布；不能因为某个因子短期表现好就直接同步真实交易。

### 4.1.3 链上数据源

- 当前链上主数据源支持 NodeReal 与 Alchemy，入口分别是 `app/services/nodereal_client.py`、`app/services/alchemy_client.py` 和 `app/services/onchain_monitor.py`。
- 默认仍可跑 `ALPHAX_ONCHAIN_PROVIDER=nodereal`；如果 NodeReal 额度受限，可切到 `ALPHAX_ONCHAIN_PROVIDER=alchemy` 并设置 `ALPHAX_ALCHEMY_API_KEY`；并行模式可用 `ALPHAX_ONCHAIN_PROVIDER=nodereal,alchemy`。
- NodeReal 通过 `ALPHAX_NODEREAL_API_KEY` 访问 EVM JSON-RPC / Enhanced API；Alchemy 通过 `ALPHAX_ALCHEMY_API_KEY` 访问 Ethereum / BSC 标准 EVM JSON-RPC。
- DEX Screener、Etherscan、Helius 已从运行时代码链路移除；当前只做 Ethereum / BSC 的 NodeReal 采集。
- NodeReal / Alchemy 原始 Transfer 会先记录到 `onchain_raw_events`，再通过 ERC-20 `symbol/name/decimals` 自动尝试映射到交易所 `XXX/USDT`，人工 `ALPHAX_ONCHAIN_TOKEN_MAPPINGS` 只作为兜底。
- 新增链上信号优先落到 `onchain_token_metrics` / `onchain_events`，不要直接创建推荐；高质量事件仍通过 `event_news` 进入技术检查。

### 4.2 Web/API

`app/web/web_server.py` 只应负责 FastAPI 应用装配、模板装配、中间件、全局异常处理和 router include。新增业务 API 优先放到对应 route 模块：

- `app/web/routes_auth.py`
- `app/web/routes_chat.py`
- `app/web/routes_recommendations.py`
- `app/web/routes_review_center.py`
- `app/web/routes_strategy.py`
- `app/web/routes_onchain.py`
- `app/web/routes_paper_trading.py`
- `app/web/routes_live_trading.py`
- `app/web/routes_market.py`
- `app/web/routes_admin.py`
- `app/web/routes_pages.py`
- `app/web/routes_content.py`
- `app/web/shared.py`

如果要改 Web 逻辑，先判断问题属于哪一层：

- 数据口径问题：优先检查 `app/db/*`、`app/core/opportunity_lifecycle.py`、`app/core/opportunity_funnel.py`
- 参数问题：优先检查 `rules.yaml`、`app/config/config_loader.py`
- 页面展示问题：再检查 `static/*.html`
- 管理端/运行态问题：检查 `app/db/scheduler_db.py`、`app/db/runtime_config_db.py`、`app/config/system_config.py`

### 4.3 状态与漏斗中心

- `app/core/opportunity_lifecycle.py`
  - 推荐生命周期、展示桶、执行状态、买点质量闸门的中心。
  - 新增状态时必须同步 API、前端、推送、统计和测试。
- `app/core/opportunity_funnel.py`
  - 漏斗阶段词表与筛选层映射中心。
  - 筛选、确认、pipeline 页面和分析口径应优先复用这里的 vocabulary。
- `app/core/opportunity_level.py`
  - 机会级别、持有周期、入场/止损/止盈模型等结构化口径。
- `app/core/signal_taxonomy.py`
  - 信号分类与信号语义口径。
- `app/core/market_regime.py`
  - 市场环境识别中心，第一版基于市场快照、BTC/ETH 涨跌、山寨涨跌广度、强势/大跌数量和 funding 热度识别 `risk_off`、`btc_main_uptrend`、`altcoin_rotation`、`sideways_chop`、`meme_frenzy`、`unknown`。
- `app/core/global_risk.py`
  - paper trading 全局风控门禁。单币机会进入开仓或挂单成交前，需要先检查市场环境和账户风险；critical 禁止新开仓，high 只允许高质量机会。
- 多策略基础设施当前内置 `main_composite_v1`、`box_retest_4h_v1`、`box_retest_1h_v1`。`box_breakout_pullback_4h` / `box_breakout_pullback_1h` 只是触发因子，只有和入场确认、风控、失效条件组成完整剧本后，才作为对应策略信号写入 `strategy_signals`。
  - 确认层也会应用同一市场风控语义：`risk_level=critical` 且 `position_multiplier=0` 时，强势发现仍可记录为观察，但不能输出 `buy_now` 或新挂单动作；已有活跃可交易推荐会被降级为观察并写入 `market_risk_gate`。

## 5. 数据与状态中心

### 5.1 DB 模块分工

- `app/db/altcoin_db.py`
  - 现在主要是历史兼容门面和少量读接口；推荐写入、推送、状态派生、跟踪、筛选、cron、复盘基础写入等都应走细分模块。
  - 后续新增查询不要默认继续塞回这里，优先放到更细分模块。
- `app/db/recommendation_commands.py`
  - 推荐创建、旧推荐过期、推荐 action_status 状态迁移、派生字段重算、操作状态更新。
- `app/db/coin_state_queries.py`
  - 旧 `coin_state` 兼容状态写入、active 状态读取、过期状态清理。
- `app/db/screening_queries.py`
  - 筛选日志写入、细筛历史读取、确认层候选读取。
- `app/db/universe_audit.py`
  - 交易宇宙缓存与筛选覆盖率审计。`symbol_universe_cache` 保存稳定币/封装币/异常交易对/低成交额等过滤结论；`screening_coverage_audit` 保存每轮 Binance USDT 总数、可交易宇宙、缓存命中、K 线成功率、粗筛/细筛数量等覆盖率快照。
- `app/db/short_tf_signals.py`
  - 5m/15m 短周期启动信号的证据采样与复盘读模型。短周期信号先进入 `short_tf_signal_samples`，通过转推荐率、后续收益等数据验证价值，不应拍脑袋直接变成交易动作。
- `app/db/recommendation_state.py`
  - 推荐状态派生、展示桶、发现层/交易层字段、entry_plan 解析、观察池分层。
- `app/db/recommendation_queries.py`
  - 推荐热路径查询、active/deduped 查询；不应反向依赖 `altcoin_db.py`。
- `app/db/push_queries.py`
  - 推送冷却去重、推送日志、推送前单条推荐读取；推送层只能消费这里派生后的主链路口径。
- `app/db/tracking_queries.py`
  - 最新价格缓存、推荐跟踪价格/PnL 写入、入场时点更新。
- `app/db/cron_queries.py`
  - cron/调度任务运行日志写入、列表与汇总查询。
- `app/db/review_basic_queries.py`
  - 基础复盘写入、漏选记录写入、信号绩效和动态权重读取。
- `app/db/strategy_rule_queries.py`
  - 策略规则候选、失败模式、候选状态判定、历史回填、候选生成、dry-run/refresh、迭代 dashboard 等复盘迭代基础能力。
- `app/db/strategy_insights.py`
  - 策略归因读模型，基于 opportunity/recommendation 与 paper_trades 转化统计，不把 recommendation.pnl_pct 当交易收益。
- `app/db/analytics.py`
  - 筛选历史、复盘概览、cron 汇总等读多写少查询。
- `app/db/review_queries.py`
  - 策略迭代日志和汇总查询；不应再直接顶层依赖 `altcoin_db.py`。
- `app/db/admin_queries.py`
  - 管理端数据查询。
- `app/db/scheduler_db.py`
  - 调度任务配置、运行态、手动触发。
- `app/db/runtime_config_db.py`
  - 运行时系统配置。
- `app/db/paper_trading.py`
  - 模拟交易账本、仓位、成交事件和资金口径。
- `app/db/live_trading.py`
  - 实盘控制台账本，多 API 账户、账号级风控、交易所接口验收与执行事件；不保存真实 API secret。
- `app/db/market_db.py`
  - 市场快照。
- `app/db/system_logs.py`
  - 系统错误与异常日志。
- `app/db/auth_db.py`
  - 用户、会员、邀请码、邮箱验证、订阅、订单预留。

### 5.2 核心表

当前 PostgreSQL 运行时重要表包括：

- `recommendation`
- `screening_log`
- `screening_coverage_audit`
- `symbol_universe_cache`
- `short_tf_signal_samples`
- `price_tracking`
- `latest_price_cache`
- `review_log`
- `missed_explosions`
- `cron_run_log`
- `scheduler_job_config`
- `scheduler_runtime_status`
- `scheduler_manual_trigger`
- `paper_trades`
- `paper_orders`
- `paper_trade_events`
- `live_trade_accounts`
- `live_order_intents`
- `live_order_events`
- `market_snapshots`
- `sentiment_events`
- `onchain_*`
- `llm_insights`
- `system_config`
- `system_error_log`
- `app_user` / `user_*` / `subscription_plan`

不要把 SQLite 文件或 `data/altcoin_monitor.db` 当作当前状态来源。排查最近链路数据时，优先查询 PostgreSQL。

## 6. 配置中心

- `rules.yaml` 是策略参数单一事实源。
- `app/config/config_loader.py` 负责读取、缓存、兼容旧信号名，以及部分复盘参数写回。
- `app/config/rules_schema.py` 负责规则结构校验。
- `app/config/system_config.py` 负责运行时系统配置，如 scheduler dry run、poll interval 等。
- `system_config` / `strategy_runtime_config` 等 PostgreSQL 表承载运行态配置。
- `live_trading` runtime config 使用 `execution_mode=exchange_api` 表示真实调用当前配置的交易所 API endpoint；API key/secret 只通过环境变量名引用；多账户配置保存在 `live_trade_accounts`。

如果要改筛选阈值、确认门槛、止盈止损、动态权重逻辑，优先检查 `rules.yaml` 和 `app/config/config_loader.py`。如果要改调度行为或系统开关，优先检查 runtime config，而不是只看环境变量。

## 7. 目录速览

- `/app`
  - 真实实现层，按职责拆成 `services`, `db`, `core`, `config`, `integrations`, `analysis`, `web`
- `/static`
  - 页面文件，如 `app.html`, `pipeline.html`, `paper_trading.html`, `live_trading.html`, `review_center.html`, `market.html`, `onchain.html`, `chat.html`
- `/tests`
  - 状态机、认证订阅、推荐链路、调度、模拟交易、行情、复盘、前端页面约束等回归测试
- `/scripts`
  - 校验脚本和 PostgreSQL 导入/备份/恢复脚本
- `/scripts/postgres`
  - PostgreSQL migration、SQLite 历史导入、导入校验、备份恢复
- `/docker`
  - 容器入口与调度器
- `/tools`
  - 非主链路工具脚本，如回测和输出摘要脚本
- `/templates`
  - 后端读取的 HTML 模板资源
- `/docs`
  - 项目结构、迁移、专题审计、参考 schema 等文档
  - `OPTIMIZATION_TODO.md` 记录筛选、风控、因子、复盘进化的后续优化路线；继续做策略优化前应先阅读并更新。
- `/data`
  - 本地挂载数据目录，主要用于历史导入源或运行产物，不是 PostgreSQL 主存储
- `/logs`
  - 运行日志目录

根目录应尽量只保留：

- 顶层配置
- Docker 入口与部署文件
- 项目说明文档
- 明确约定的非代码资产目录

Python 业务实现不应直接留在根目录。

## 8. 运行与验证

### 8.1 Docker 启动

常规启动：

```bash
cp .env.example .env
docker compose build
docker compose up -d postgres alphax-web alphax-scheduler alphax-price-streamer
```

访问：

```text
http://127.0.0.1:8191
```

常用状态检查：

```bash
docker compose ps
docker compose logs --tail=100 alphax-web
docker compose logs --tail=100 alphax-scheduler
docker compose logs --tail=100 alphax-price-streamer
```

容器内 API smoke：

```bash
docker compose exec alphax-web curl -fsS http://127.0.0.1:8190/api/stats
docker compose exec alphax-web curl -fsS 'http://127.0.0.1:8190/api/pipeline/runs?page=1&page_size=5'
docker compose exec alphax-web curl -fsS http://127.0.0.1:8190/api/onchain/overview
```

### 8.2 CLI

统一入口：

```bash
python -m app.cli screener
python -m app.cli confirm
python -m app.cli tracker
python -m app.cli paper-trader
python -m app.cli market
python -m app.cli review
python -m app.cli event
python -m app.cli sentiment --collect
python -m app.cli onchain
python -m app.cli llm-insights --scope sentiment --limit 40
```

Docker 内建议通过 `docker compose exec alphax-web python -m app.cli ...` 执行，确保使用容器内 `DATABASE_URL` 和依赖环境。

实盘接口 smoke test 会调用当前配置的 Binance Futures API endpoint：

```bash
docker compose exec alphax-web python -m app.cli live-trading-smoke --account-id 1 --symbol BTC/USDT --notional-usdt 10 --leverage 1
```

该命令会依次测试余额/行情、设置杠杆、市价单、止盈单、止损单、限价挂单、撤单、最后市价平仓，并写入 `live_order_events`。不要把真实 API key 写入数据库或聊天；只在环境变量中保存密钥，`live_trade_accounts` 只保存 env key 名。

### 8.3 测试与校验

常用回归命令：

```bash
pytest -q
python3 scripts/validate_docker_layout.py
python3 scripts/validate_state_machine.py
python3 scripts/validate_push_state_flow.py
python3 scripts/validate_signal_recency.py
```

涉及 PostgreSQL migration/import 时：

```bash
docker compose run --rm alphax-web python scripts/postgres/run_migrations.py
docker compose run --rm alphax-web python scripts/postgres/validate_import.py --all-tables
```

如果只是小范围修改，优先跑和改动模块最相关的测试文件，不要盲目只看 `pytest` 是否全绿。

## 9. 开发守则

### 9.1 改动前先判断“应该改哪一层”

- 调参数：优先 `rules.yaml`
- 策略配置读取/兼容：`app/config/config_loader.py`
- 系统运行态配置：`app/config/system_config.py` / `app/db/runtime_config_db.py`
- 状态口径：`app/core/opportunity_lifecycle.py`
- 漏斗口径：`app/core/opportunity_funnel.py`
- DB 表结构：新增 PostgreSQL migration
- DB 查询：优先对应 `app/db/*_queries.py` 或细分 DB 模块
- API 契约：优先对应 `app/web/routes_*.py`
- 页面壳和交互：`static/*.html`
- 调度任务：`app/cli.py` + `app/db/scheduler_db.py` + `docker/scheduler.py`

### 9.2 PostgreSQL 约束

这个项目当前运行时依赖 PostgreSQL，因此要特别注意：

- 不要新增 SQLite 运行时分支。
- 不要把 `data/*.db` 当作线上或当前状态来源。
- schema 变化必须通过 `app/db/migrations/*.sql`。
- 查询最新运行状态优先看 PostgreSQL 表，而不是历史文件。
- Docker 容器内运行和宿主机运行可能使用不同连接地址，排查时先确认 `DATABASE_URL`。
- 调度器并发运行时要检查 lock group，避免多个任务同时写推荐主链路。

### 9.3 状态机不要各写各的

项目已经存在比较强的状态派生中心化趋势：

- `normalize_action_status`
- `derive_display_bucket`
- `apply_entry_quality_gate`
- `apply_recommendation_state_transition`
- `screening_stage_meta`
- `build_screening_detail`

新增状态时，必须检查：

1. DB 中原始状态字段怎么存。
2. API 输出怎么派生。
3. 前端如何解释。
4. 推送是否会误触发。
5. paper trading 是否会误开仓或误平仓。
6. 复盘统计是否会被污染。
7. 相关测试是否需要补齐。

### 9.4 推荐链路当前特别注意点

当前主链路已经能持续产生筛选和确认样本，但后半段仍需要重点盯住：

- `latest_price_cache` 可能是实时的，但不代表 `recommendation.pnl_pct` 已更新。
- `price_tracking` 是跟踪流水，不应和 `latest_price_cache` 混为一谈。
- `price_tracker.py` 会为 active 观察池样本更新观察价/PnL，但未触发入场的 watch_pool/wait_pullback 不能触发止盈止损、不能进入 paper trading 收益账本。
- `rec_state` 是发现层状态（如“爆发/加速”），`execution_status`/`trade_stage` 才是交易执行阶段（如 `buy_now`/`wait_pullback`/`observe`），不要把“发现爆发”直接解读成“现在可买”。
- 每轮粗筛会写 `screening_coverage_audit`，用于确认 `Binance USDT 总数 -> 可交易宇宙 -> K线成功 -> 粗筛候选 -> 细筛通过` 的覆盖漏斗；排查“为什么没有机会/是否漏选”时应先看这张表和 `/pipeline` 的覆盖率指标。
- `symbol_universe_cache` 只应把静态/半静态问题长期缓存，例如稳定币、封装币、异常交易对、非标准交易对；`low_turnover`、`stale_ticker` 等动态问题只能短 TTL，不能永久拉黑，否则会错过后续流动性改善的币。
- 静K蓄力旁路已要求配置化共振（见 `rules.yaml` 的 `screener.static_accumulation_bypass.require_resonance`），避免单一静K样本淹没确认层；无追高风险的强势榜异动仍可作为发现入口。
- 粗筛发现层已加入 `screener.short_timeframe_ignition`：15m 用于捕捉 1H 成型前的短周期启动，5m 只在 15m 已启动或已有结构背景时启用；短周期信号只作为早期发现/共振，不应绕过确认层直接买入。
- 短周期信号会写入 `short_tf_signal_samples`，`/api/screening/short-tf-review` 和 `/pipeline` 的“短周期验证”会展示样本数、转推荐率、当前收益等证据。后续若要把 5m/15m 提升为更强交易触发，必须先基于这张表和历史暴涨样本验证，而不是固定写死。
- 确认评分不再应被理解为固定技术分；确认层通过 `FactorScorer` 读取复盘后的 `signal_performance.weight`，高胜率因子会升权，低胜率/负收益因子会降权或淘汰。
- 评分因子必须保留 `factor_score_breakdown`，否则复盘无法知道一次推荐具体由哪些因子贡献、哪些因子拖累。
- `paper_trader.py` 只应处理可执行推荐，不能把观察池样本当成已成交。
- `review_engine.py` 的可信度依赖跟踪数据质量；如果 PnL 没更新，复盘结论也会失真。
- `missed_explosions` 历史数据可能存在同一 symbol 多次记录，读模型/KPI 需要保持去重口径，写入侧后续仍建议加唯一性或冷却约束。

### 9.5 面向兼容开发

这个仓库里仍有不少“迭代中兼容旧逻辑”的痕迹，例如：

- `DbRow` 兼容旧的 row 下标读取。
- `app/config/config_loader.py` 中的信号别名兼容。
- 多处 `entry_plan_json` / `detail_json` / `*_context_json`。
- `app/db/altcoin_db.py` 仍承载较多历史兼容逻辑。

因此改动时应优先做增量兼容，而不是假设数据库、配置、旧数据永远是干净新鲜的。

## 10. 当前仓库事实

- 当前运行态是 PostgreSQL，不是 SQLite。
- `README_DOCKER.md` 是 Docker/PostgreSQL 运行说明的重要事实源。
- `docs/PROJECT_STRUCTURE.md` 记录了目录整理背景，但具体运行状态仍以代码、compose 和 PostgreSQL 为准。
- `DESIGN.md` 当前更像品牌/样式 YAML，不是系统架构设计文档。
- `app/db/altcoin_db.py` 仍保留兼容门面，但推荐写入/状态迁移已迁到 `recommendation_commands.py`，推送去重已迁到 `push_queries.py`，状态派生、价格/跟踪写入、筛选日志、旧 coin_state、cron 日志、基础复盘写入、策略规则候选、策略归因也已迁出；后续新增 DB 查询应优先放到 `recommendation_queries.py`、`screening_queries.py`、`tracking_queries.py`、`cron_queries.py`、`review_basic_queries.py`、`strategy_rule_queries.py`、`strategy_insights.py`、`analytics.py`、`review_queries.py`、`admin_queries.py`、`paper_trading.py` 等分组模块。

## 11. 推荐的后续重构方向

后续若继续开发，建议优先考虑：

1. 继续把 `app/db/altcoin_db.py` 剩余读接口迁到 `recommendation_queries.py` / `analytics.py`，最终让它只保留极薄兼容导出或逐步废弃。
2. 为 watch_pool / wait_pullback 建立更完整的观察绩效报表，继续避免和已执行仓位 PnL 混在一起。
3. 把 `rules.yaml` 的 schema 校验从“顶层结构校验”推进到“关键子字段校验”。
4. 让 Docker、文档、测试样例全面收敛到 `python -m app.cli ...` 入口。
5. 继续梳理推送链路，把“是否推送”的判断、推送内容组装、通道发送彻底分层。
6. 对 `missed_explosions` 写入侧建立唯一性或冷却约束，避免重复样本继续进入历史表。
7. 梳理 price-streamer、tracker、paper-trader 三者边界，确保实时价格、推荐跟踪、模拟成交各自语义清晰。

## 12. 给后续 Agent 的工作方式建议

接手这个仓库时，优先按下面顺序理解问题：

1. 先确认问题发生在“筛选 / 确认 / 跟踪 / 模拟交易 / 复盘 / Web 展示 / 认证订阅 / 调度运行态”哪一层。
2. 再确认它属于“参数失真、状态派生错误、DB 查询口径不一致、前端展示错误、任务调度副作用、数据水位滞后、样本去重缺失”中的哪一类。
3. 排查数据时直接查 PostgreSQL，不要使用 SQLite 文件作为当前状态来源。
4. 修改后至少补 1 个相关测试，最好补到最接近业务口径的那层。
5. 如果变更影响推荐状态或展示桶，务必同时检查 API、前端、推送、paper trading、历史统计五个面。
6. 如果变更影响调度任务，务必检查 `scheduler_job_config`、`scheduler_runtime_status` 和最近 `cron_run_log`。

---

这份文档以当前仓库实际代码、Docker compose 和 PostgreSQL 运行态为准整理。后续如果引入新的服务、迁移表结构、改变调度模式或调整推荐状态机，必须同步更新本文件，避免后续 Agent 再被过时信息带偏。