# MoFin 系统架构（3+1 Cron 层次 · 3+1 环节）

> 版本：2026-08-12 ｜ 维护：小小莫（Sisyphus）
> 定位：**系统架构权威文档**——3+1 cron 层次 + 3+1 环节 + cron 体系统一 + 开发原则。
> 区别于方法论（3+6+12 研究方法，见 docs/research/methodology.md）：本文档管**系统怎么跑**，方法论管**策略怎么研究**。

---

## 一、3+1 Cron 层次（系统架构主干）

```
┌─────────────────────────────────────────────────────┐
│  L1 数据采集层（原始数据，不重复不缺失，各司其职）      │
│     外部 API/行情/新闻/基本面 → 原始表                 │
├─────────────────────────────────────────────────────┤
│  L2 数据加工层（衍生数据，不采集不使用）                │
│     原始数据 → 技术指标/行业指数/分位/多周期 → 衍生表   │
├─────────────────────────────────────────────────────┤
│  L3 数据使用层（只读数据，不采集不现算）                │
│     衍生数据 → 扫描/重评/候选/推荐 → 业务结果           │
├─────────────────────────────────────────────────────┤
│  L4 监控运维层（健康/审计/备份/推送/自修复）            │
│     贯穿三层的健康监控与系统自愈                        │
└─────────────────────────────────────────────────────┘
```

**核心规则**：
- **能拉取的拉取（采集层），拉不了的才自己算（加工层）**——同一数据不重复来源
- **统一规范，不遗漏不重复**——指标单一权威算法，数据按层存储
- **使用层只使用数据，不采集数据**——扫描器/重评只读加工层预算值

## 二、3+1 环节（业务产出）

| 环节 | 产出 | 核心 cron（使用层） |
|------|------|---------------------|
| **选股**（入自选） | 候选池→过滤→提拔→自选 | predictive_oversold_scanner(p_oversold) / mr_scanner(v_weak) / accumulation_scanner → candidate_filter → promote_candidates |
| **买入**（盘中推荐） | 自选/持仓进买入区→推送+触发重评 | stale_push_wlin（*/30 盘中，2026-08-12 恢复注册） |
| **卖出**（盘中推荐） | 自选退出/清理→移除 | watchlist_auto_exit（50 8 盘前，2026-08-12 从系统 crontab 迁移到 hermes） / clean_watchlist（5 9） |
| **每日重评**（盘后） | 持仓+自选 12 维重评→更新策略/移除 | premarket_full_review（10 8 盘前全量，已修 import） / per_stock_reassess（0 12,15 午间尾盘，已恢复） / stale_detector（周末批量） |

## 三、环节 × 层次 Cron 映射（当前实际）

### L1 数据采集层
| cron | 调度 | 数据 |
|------|------|------|
| market_watch.py | `*/10 9-11,13-15 * * 1-5` | 板块快照 market_snapshots + 大盘 regime |
| price_monitor.py | `*/2 9-16 * * 1-5` | 实时价 live_prices（DB 唯一价格源） |
| capital_flow_collector.py | `1,31 9-15 * * 1-5` | 资金流 stock_capital_flow（⚠️ ERROR 待修） |
| macro_context_collector.py | `*/30 8-16 * * *` | 宏观新闻 macro_raw_news |
| refresh_macro_context.py | `*/30 9-15 * * 1-5` | 宏观上下文 macro_context_log |
| collect_evaluation_data.py | `30 20 * * 1-5` | 策略评估数据 |
| refresh_mtf_cache.py | `50 7,11,14 * * 1-5` | 多周期 mtf_cache（兼加工） |
| fundamentals_refresh.py | `52 7 * * 1-5` | 基本面 stock_fundamentals（早间，持仓/自选） |
| sector_enrich_cninfo.py | `50 7 * * 1-5` | 行业富集 sector_snapshots（早间） |
| **daily_kline_sh/sz.py** | `10/25 16 * * 1-5` | **全市场日K stock_daily**（2026-08-12 新增） |
| **news_collector_full_b0-3.py** | `30-0 7-8 * * 1-5` | **全市场新闻 stock_news**（新增） |
| **fundamentals_full_refresh.py** | `35 16 * * 1-5` | **全市场基本面 stock_fundamentals**（新增） |

### L2 数据加工层
| cron | 调度 | 产物 |
|------|------|------|
| **factor_engine.py** | `5 17 * * 1-5` | **技术指标 stock_indicators(26项) + 大盘 market_indicators + mcap_q/pe_q 分位**（新增） |
| **sector_index_builder.py** | `0 17 * * 1-5` | **行业指数 sector_index_daily（stock_sectors_em 聚合 307 行业）**（新增） |
| refresh_mtf_cache.py | `50 7,11,14 * * 1-5` | 多周期均线 mtf_cache |

### L3 数据使用层
| 环节 | cron | 调度 |
|------|------|------|
| 选股 | predictive_oversold_scanner.py | `35 9 * * 1-5` |
| 选股 | mr_scanner.py (v_weak) | `35 9 * * 1-5` |
| 选股 | accumulation_scanner.py | `*/10 9-15 * * 1-5` |
| 选股 | candidate_filter.py | `*/30 9-15 * * 1-5` |
| 选股 | promote_candidates.py | `*/30 9-15 * * 1-5` |
| 买入 | **stale_push_wlin.py** | `*/30 9-15 * * 1-5`（2026-08-12 恢复注册：自选买入区提醒+触发重评） |
| 买入 | review_needed_watchdog.py | `0,30 9-15 * * 1-5` |
| 卖出 | **watchlist_auto_exit.py** | `50 8 * * 1-5`（2026-08-12 从系统 crontab 迁移到 hermes） |
| 卖出 | clean_watchlist.py | `5 9 * * 1-5` |
| 每日重评 | **premarket_full_review.py** | `10 8 * * 1-5`（2026-08-12 修 import 恢复：盘前全量重评-自选退出） |
| 每日重评 | **per_stock_reassess.py** | `0 12,15 * * 1-5`（2026-08-12 恢复：自选 12 维重评+买入区提醒） |
| 每日重评 | strategy-staleness-check.py | `0 9 * * 1-5` |
| 每日重评 | stale_detector.py | `30 10 * * 0,6`（周末批量） |

### L4 监控运维层
morning_health_check(0 8) / preflight_verify(30 8) / intraday_health_check(*/15) / mofin_health(*/15) / functional_health_check(*/15) / system_audit(30 17) / system_hygiene_audit(20 8) / hardcode_scanner(25 17) / verify_reassess_pipeline(*/30) / data_governance(0 10 周六) / memory_guardian(0 7) / meta_watchdog(5 * * * *) / self_repair(*/30) / agent_spiral_watchdog(*/10) / deploy_guard(*/15) / self_todo_executor_v2(*/10) / db_daily_backup(50 7) / vacuum_state_db(0 3 周六) / fix_gateway_port(10m) / cron_to_xmpp(*/5) / opening_brief(35 9) / closing_brief(10 16) / market_insight(35 15) / macro_signal_consumer / divergence_detector(*/30) / strategy_evaluator(0 21 周六) / advice_reconciliation(0 20 周六) / prepare_report_data(0 20 周四)

## 四、数据流（采集 → 加工 → 使用）

```
腾讯/东财/THS/akshare API
  ↓【L1 采集】
stock_daily(K线) / stock_news(新闻) / stock_fundamentals(基本面)
stock_capital_flow(资金流) / market_snapshots(板块) / sector_index_daily(行业)
  ↓【L2 加工】
stock_indicators(技术指标26项) / market_indicators(大盘) / sector_index_daily(行业指数)
mtf_cache(多周期) / mcap_q/pe_q(分位)
  ↓【L3 使用】
扫描器(p_oversold/v_weak/accumulation) → candidates
  → candidate_filter → promote_candidates → watchlist_stocks(自选)
重评(premarket/per_stock) → 更新策略 / 移除自选
  ↓【L4 监控】
mofin_health(健康采集) → F健康 Dashboard（三层架构健康 + cron来源标记）
```

## 五、Cron 体系统一（强制开发原则）

> 🚫 **自动任务必须部署在 hermes（position-analyst），严禁使用系统 crontab。**

- **唯一体系**：hermes cron（`/home/hmo/.hermes/profiles/position-analyst/cron/jobs.json`）
- **禁止**：系统 crontab 部署 MoFin 自动任务（避免新旧一起跑、状态不可见、无单例守卫）
- **历史迁移**：watchlist_auto_exit / kanban_xmpp_bridge / parallel_batch / live_data_collector 已于 2026-08-12 从系统 crontab 迁移到 hermes；news_collector(旧版) / agents_health_check(MoFin) 已停用（与 hermes 重复）
- **监控**：F 健康 cron 列表带**来源标记**（✅ hermes 合规 / ⚠️ 系统cron 违规红色警告），顶部横幅提示本原则
- **备份**：系统 crontab 备份在 `.backups/crontab_backup_*.txt`

## 六、开发原则（自动任务强约束）

1. **单例守卫**：每个定时脚本必须 `_singleton_guard`（fcntl flock /tmp/mofin_locks/），防重复实例并发写（2026-08-05 进程堆积事故后统一加装）
2. **600s 护栏**：hermes child_timeout 内完成；超时任务分批（如 daily_kline 分 sh/sz、news_collector_full 分 4 批）
3. **幂等**：数据写入用 `INSERT OR REPLACE`（同 key 覆盖，重跑安全）；候选扫描当日幂等（同股30日去重+当天已扫跳过）
4. **限速防封**：外部 API 请求间隔（腾讯/东财 0.05-0.5s），批量上限（腾讯 100 只/批）
5. **git 版本管理**：改动必须 commit 入库（deploy_guard 回滚机制）；**脚本文件不删除**（保留作参考，停 cron 即可），crontab/cron 变更留备份
6. **统一 hermes**：自动任务只部署 hermes（见第五节）
7. **口径一致**：指标用 backtest_framework 权威算法（回测实盘同口径），使用层读加工层预算值，不现算

---

> 关联文档：方法论 docs/research/methodology.md（3+6+12 研究方法）｜ 数据模型 portfolio-data-model.md ｜ 系统梳理 system-architecture-review-20260812.md（三层架构补缺过程）