# DCA Scanner & Monitoring Architecture

## Overview
Pattern for automated high-dividend stock scanning across multiple markets (HK/US/CN), with DCA ladder buy-signal monitoring.

## Architecture

### Two script types:
1. **Scanner** (`dca_scanner.py`) — Scans a candidate pool for high-yield stocks, pushes TOP5 with ladder prices
2. **Monitor** (`dca_monitor.py`) — Watches existing positions for buy-signal triggers against ladder levels

### Market separation:
- Each script accepts `--market=hk|us|cn` to filter positions/candidates
- Cron jobs are split per market to avoid API collisions and match trading hours
- Scanner candidate pools are hardcoded per market (24 HK / 15 US / 14 CN)

### Cron schedule pattern (EDT, staggered ≥15min):
```
A股扫描:   19:30  (= 北京 7:30AM, A股开盘前)
港股扫描:   20:00  (= 北京 8:00AM, 港股开盘前)
美股扫描:   21:30  (= 北京 9:30AM, 美股开盘前)
美股监控1:  22:30  (美股盘中)
美股监控2:  02:00  (美股盘中)
```

### Rate limiting prevention:
- No two LongPort jobs share the same minute
- Scanner and Monitor never run simultaneously
- RGTI price monitoring (if needed) at 30min intervals, NOT 10/15min

## Key design decisions:
1. **User wants push-based scanning** — "你要扫描高股息的发通知给我，不是我选" — system scans and pushes candidates, user doesn't manually pick from lists
2. **30min polling is enough** for price monitoring — user explicitly said "半小时吧，不需要太频繁"
3. **Merge overlapping tasks** — price alert + auto order were merged into one (RGTI)
4. **Pause mislabeled tasks** — "港股监控" that only had US stocks was paused
5. **Add dividend frequency** to all output — `[季度]` / `[月度]` / `[半年]` suffix

## Data files:
- `~/.hermes/scripts/dca_positions.json` — Current positions with ladder prices, yields, div_freq
- `~/.hermes/scripts/dca_scanner.py` — Market scanner with candidate pools
- `~/.hermes/scripts/dca_monitor.py` — Ladder monitor with market filter support