# 智策 StockTerminal — 架构总结

> 版本：当前实现态（2026-06）  
> 定位：个人/小团队 A 股分析·复盘·智能辅助系统

---

## 一、整体分层

```
┌─────────────────────────────────────────────────────────────┐
│                      展示层（前端）                          │
│  HTML + ECharts 5 + 原生 JS                                 │
│  prototype/index.html · style.css · app.js                  │
└────────────────────────┬────────────────────────────────────┘
                         │ HTTP / REST
┌────────────────────────▼────────────────────────────────────┐
│                   服务层（后端 FastAPI）                      │
│  main.py  —— 50+ API 端点，静态文件托管                      │
│                                                              │
│  数据服务     akshare_service.py   (行情·情绪·资讯·实时报价)  │
│  AI 分析      ai.py                (证据链·置信度·LLM/规则)   │
│  信号统计     signals.py           (胜率回测·预测留痕·核验)   │
│  RAG 检索     rag.py               (资讯检索·情绪标注)        │
│  复盘日报     report.py            (结构化日报·推送)          │
│  组合计算     portfolio.py         (持仓·P&L·资金曲线)        │
│  回测引擎     backtest.py          (MA交叉·净值曲线)          │
│  预警引擎     alerts.py            (实时报价判断·触发事件)     │
│  推送通知     notifier.py          (SMTP·Server酱·企微·PP)   │
│  大模型客户端 llm.py               (OpenAI 兼容接口)          │
│  定时调度     scheduler.py         (APScheduler 5 个任务)     │
│  ETL 入库     ingest.py            (AkShare→PostgreSQL)      │
│  CLI 工具     cli.py               (init/ingest/ingest_all)  │
│  配置         config.py + .env     (DB·LLM·推送密钥)         │
└────────────────────────┬────────────────────────────────────┘
                         │ SQLAlchemy ORM / psycopg2
┌────────────────────────▼────────────────────────────────────┐
│                   数据层（PostgreSQL）                        │
│  13 张业务表，见下方数据模型                                  │
└─────────────────────────────────────────────────────────────┘
```

---

## 二、后端模块职责

| 文件 | 职责 | 关键依赖 |
|---|---|---|
| `main.py` | FastAPI 入口，50+ REST 端点，静态托管 | 所有模块 |
| `config.py` | 环境变量读取，支持 `.env` 文件 | python-dotenv |
| `db.py` | 引擎/Session，自动建库建表 | SQLAlchemy, psycopg2 |
| `models.py` | 13 个 ORM 表（见下节） | SQLAlchemy |
| `akshare_service.py` | AkShare 数据抓取，带 TTL 缓存和 mock 降级 | akshare, cachetools |
| `ingest.py` | ETL：AkShare → PostgreSQL 增量 upsert | akshare, models |
| `scheduler.py` | APScheduler 后台任务（5 个定时任务） | apscheduler |
| `backtest.py` | MA 交叉策略回测，读 DB 日线，输出净值曲线 | sqlalchemy, pandas |
| `ai.py` | AI 分析：证据链构造、置信度计算、LLM 调用/规则降级 | llm, signals, rag |
| `signals.py` | 6 类信号历史胜率回测；预测留痕 + 到期核验 | sqlalchemy, pandas, numpy |
| `rag.py` | 资讯检索 + 利好/利空情绪标注，作为 LLM 上下文 | akshare_service |
| `report.py` | 七段式 AI 复盘日报生成、落库、推送精简版 | ai, notifier |
| `portfolio.py` | 持仓计算（移动加权均价）、P&L 归因、逐日资金曲线 | sqlalchemy |
| `alerts.py` | 实时报价轮询 → 规则命中 → 写事件 + 推送 | akshare_service, notifier |
| `notifier.py` | 四渠道推送：SMTP 邮件、Server酱、企业微信 Webhook、PushPlus | requests, smtplib |
| `llm.py` | OpenAI 兼容客户端（DeepSeek/通义/Kimi 均适用） | requests |
| `cli.py` | 命令行工具：`init` / `ingest` / `ingest_all` | ingest, db |

---

## 三、数据模型（PostgreSQL）

| 表名 | 说明 | 主键 / 唯一约束 |
|---|---|---|
| `securities` | 证券基础信息（代码·名称·市场） | `code` |
| `quotes_daily` | 个股日线（OHLCV，前复权） | `(code, date)` |
| `index_daily` | 指数日线（上证/深证/沪深300） | `(code, date)` |
| `sector_daily` | 板块每日快照（涨跌·成交额·龙头） | `(date, name)` |
| `fund_flow_daily` | 行业主力资金流每日快照 | `(date, name)` |
| `sentiment_daily` | 全市场情绪（涨跌家数/涨跌停） | `date` |
| `dragon_tiger` | 龙虎榜明细（代码·席位·净买额） | `(date, code, reason)` |
| `stock_metrics` | 个股最新因子快照（MA/RSI/MACD/量比/分位/连涨 等 15 个因子） | `code` |
| `signal_stats` | 6 类技术信号历史胜率（回测样本·N日上涨概率·平均收益） | `(signal, horizon)` |
| `predictions` | AI 诊断留痕（方向·置信度·N日后核验·命中与否） | `(code, date, kind)` |
| `daily_reports` | AI 复盘日报（markdown 正文·来源·是否已推送） | `date` |
| `trades` | 交易记录（买卖·价格·数量·手续费·理由·情绪标签） | `id` |
| `alert_rules` | 预警规则（价格上穿/下穿/涨跌幅条件·状态） | `id` |
| `alert_events` | 预警触发事件（站内通知·已读状态） | `id` |
| `job_runs` | 定时任务执行日志 | `id` |

---

## 四、定时任务（APScheduler，周一至周五）

| 任务 ID | 触发时间 | 功能 |
|---|---|---|
| `daily_ingest` | 15:35（收盘后，可配） | 抓取当日板块/资金流/情绪/龙虎榜/自选股日线入库 |
| `alert_check` | 每 60 秒 | 实时报价核查所有 active 预警规则，触发则写事件并推送 |
| `daily_report` | 15:45（入库+10分） | 生成 AI 七段式复盘日报并推送微信/邮件 |
| `verify_pred` | 15:50 | 核验到期 AI 预测，计算命中率 |
| `signal_stats` | 每周六 09:00 | 对全市场样本股回测 6 类信号历史胜率（可手动触发） |

---

## 五、AI 分析层设计（可回溯）

```
用户请求 /api/ai/diagnose
        │
        ▼
 _stock_context()           从 stock_metrics + DailyQuote 取最新因子
        │
        ├─ signals.get_stats()    读 signal_stats 表，取各信号历史胜率
        │
        ├─ rag.stock_context()    拉近期资讯 → 情绪标注（利好/利空/中性）
        │
        ▼
 _build_evidence()          生成 6 维证据链（趋势/技术/动量/资金/位置/消息）
   每条附：事实描述 · 方向(bull/bear/neutral) · 历史胜率 · 样本数
        │
        ▼
 _confidence_direction()    加权多空净值 → 置信度(%) + 预测方向(up/down/flat)
        │
        ├─ signals.record_prediction()   写入 predictions 表留痕
        │
        ├─ llm.ask()  (有 key)    将证据链+胜率+RAG资讯构造 prompt → 大模型输出
        │  或
        └─ 规则文本降级           格式化证据链为可读文本
```

实测准确率闭环：
```
预测留痕(open) → N 个交易日后 verify_predictions() 拉 DailyQuote 核验
→ 填写 actual_ret + hit(True/False) → status=closed
→ /api/ai/accuracy 按方向汇总命中率
```

---

## 六、推送通知渠道

| 渠道 | 触发条件 | 配置项（`.env`） |
|---|---|---|
| SMTP 邮件 | 预警触发 / 复盘日报 / 测试 | `SMTP_HOST/PORT/USER/PASSWORD/TO` |
| Server酱（微信） | 同上 | `SERVERCHAN_KEY` |
| 企业微信群机器人 | 同上 | `WECOM_WEBHOOK` |
| PushPlus（微信） | 同上 | `PUSHPLUS_TOKEN` |

任意渠道配置即自动启用，互不依赖。

---

## 七、前端菜单结构（app.js MENU）

```
大盘行情
  ├─ 市场总览       行情/三大指数/情绪温度计/资金流向
  ├─ 大盘云图       行业/板块涨跌热力图（ECharts treemap）
  ├─ 热股榜         实时热股+板块
  └─ 龙虎榜         当日龙虎榜净买额排名

自选股
  ├─ 自选列表       持仓快照 + K线
  ├─ 全市场选股     8 个内置策略 + SQL 直查 stock_metrics
  └─ 条件选股       客户端多因子过滤

复盘中心
  ├─ 每日复盘       板块/情绪/资金流统计
  ├─ AI日报         七段式 markdown 日报，历史翻阅，一键推送
  └─ 个股复盘       K线回放 + MA交叉买卖点标注

策略与中台
  ├─ 策略回测       MA交叉净值曲线 + 最大回撤
  └─ 数据中台       入库状态 / 手动触发 / 任务日志

AI 分析
  ├─ 今日策略       大模型/规则 生成当日操作方向
  ├─ 个股诊断       6维证据链 + 历史胜率 + 置信度 + RAG资讯
  ├─ AI复盘点评     当日大模型复盘摘要
  └─ AI准确率       信号历史胜率表 + 实测命中率 + 近期核验记录

组合交易
  ├─ 组合持仓       实时市值/浮亏/胜率
  ├─ 资金曲线       逐日净值 vs 沪深300基准（ECharts折线）
  ├─ 交易日志       录入买卖 / 理由 / 情绪标签
  └─ 盈亏归因       按个股/理由/情绪三维归因

智能预警
  ├─ 预警规则       创建/删除/重激活规则，推送渠道状态检测
  └─ 触发记录       预警事件列表，标记已读，🔔铃铛角标

资讯中心
  ├─ 要闻快讯       全球财经资讯 + 情绪标注 + AI摘要
  └─ 自选相关       自选股关联资讯聚合
```

---

## 八、技术栈

| 层 | 技术选型 |
|---|---|
| 前端 | 纯 HTML + CSS + 原生 JS，ECharts 5（CDN） |
| 后端 | Python 3.12 + FastAPI 0.115 + uvicorn |
| 数据库 | PostgreSQL（psycopg2-binary + SQLAlchemy 2.0） |
| 数据源 | AkShare（新浪/同花顺/乐估备选源），Sina hq 实时报价 |
| 调度 | APScheduler 3.x BackgroundScheduler |
| AI | OpenAI 兼容 REST（默认 DeepSeek），规则降级无缝切换 |
| 缓存 | cachetools TTL（内存），无 Redis 依赖 |
| 推送 | SMTP(SSL) + Server酱 + 企业微信 Webhook + PushPlus |
| 部署 | WSL2 / Linux，`nohup python main.py`，可 Docker 化 |

---

## 九、待完善方向

| 优先级 | 模块 | 建议 |
|---|---|---|
| 高 | 回测引擎 | 手续费/滑点建模，参数寻优，月度收益热力图 |
| 高 | 数据稳定性 | 东财源封锁问题，增加 Tushare 备用源，分钟线入库 |
| 中 | RAG 升级 | Embedding + 向量库（Chroma/Qdrant），支持语义检索财报 |
| 中 | 多组合 | 目前单一组合，扩展为模拟盘/真实盘多组合管理 |
| 中 | 盘中异动雷达 | 快速拉升/放量突破/涨停打开实时监测 |
| 低 | 用户系统 | 登录/鉴权，多用户自选股独立管理 |
| 低 | 部署文档 | Docker Compose（FastAPI + PostgreSQL），Nginx 反代 |