docs: 新建SYSTEM_ARCHITECTURE.md——3+1 cron层次(采集/加工/使用/监控运维)+3+1环节(选股/买入/卖出/每日重评)+cron体系统一hermes(禁止系统crontab)+开发原则强约束

docs/SYSTEM_ARCHITECTURE.md

@@ -0,0 +1,126 @@
+# 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 / per_stock_reassess（⚠️ 当前暂停，待恢复） |
+| **卖出**（盘中推荐） | 止损/止盈/退出→推送 | watchlist_auto_exit（自选退出） / clean_watchlist（自选清理） |
+| **每日重评**（盘后） | 持仓+自选 12 维重评→更新策略/移除 | premarket_full_review（盘前全量重评，⚠️ ERROR 待修） / strategy-staleness-check / 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 盘中） |
+| 买入 | per_stock_reassess.py | ⚠️ 已暂停（待恢复） |
+| 买入 | 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`（⚠️ ERROR 待修） |
+| 每日重评 | 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（三层架构补缺过程）