v1.3.1: 新增 README.md 完整文档(架构/功能/表结构/API/评分模型/策略/监控/数据接入指南)

README.md

@@ -0,0 +1,342 @@
+# 📈 智能荐股系统（Stock Advisor）
+
+一个专业的股票推荐与量化分析系统：**多因子荐股评分 + RAG 增强 AI 研报 + 主流量化策略回测 + 舆情驱动自动化通知**。
+
+- **技术栈**：Python Flask + SQLite + Chroma 向量库 + bge-large-zh 语义检索 + DeepSeek 大模型
+- **默认端口**：16095
+- **Git**：`hz4th_coder/stock-advisor`（v1.3.0）
+- **数据模式**：当前为模拟数据（`IS_MOCK=True`），后期可无缝切换真实数据
+
+---
+
+## ✨ 功能总览
+
+| 模块 | 页面 | 说明 |
+|---|---|---|
+| 📊 仪表盘 | `/` | 三大指数、市场情绪、今日荐股 TOP5、行业热度、最新要闻、自选股 |
+| 🏢 股票池 | `/stocks` | 68 只股票搜索/行业/板块/评级筛选，一键 ⭐ 自选 |
+| 🎯 荐股中心 | `/recommend` | 六因子评分排名 + 推荐理由 + AI 深度分析入口 |
+| 📈 量化策略 | `/strategies` | 6 主流策略全市场回测榜 + 单股净值曲线 + 交易明细 |
+| 📰 财经新闻 | `/news` | 新闻分类/搜索/情感标签/关联个股，RAG 语料库 |
+| 🏦 机构动向 | `/institutions` | 27 家机构、评级变动榜、基金增减持榜、机构详情 |
+| 📄 个股详情 | `/stock/<code>` | ECharts K线、技术指标、六因子评分、相关资讯、AI 研报、历史分析 |
+| 📑 AI 分析详情 | `/analysis/<id>` | 研报正文 + **大模型参考的数据源**（RAG新闻/概况/指标/评级/持仓/提示词） |
+| 🔧 系统设置 | `/settings` | 邮件 SMTP、大模型接口、舆情监控参数配置 |
+| ⚙️ 数据管理 | `/admin` | 数据统计、向量库状态、一键重灌、重建回测、依赖体检 |
+
+---
+
+## 🏗️ 技术架构
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    前端（模板 + 原生JS + ECharts）          │
+│   仪表盘 / 股票池 / 荐股 / 策略 / 新闻 / 机构 / 设置 / 详情    │
+└──────────────────────────┬──────────────────────────────┘
+                           │ HTTP (Flask)
+┌──────────────────────────▼──────────────────────────────┐
+│                      app.py（路由/API 层）                 │
+│  ┌──────────┬──────────┬──────────┬───────────────────┐  │
+│  │ 评分荐股  │ AI研报    │ 量化回测  │ 舆情监控+设置       │  │
+│  │scoring.py│analyst.py│strategies│notifier+settings  │  │
+│  └──────────┴──────────┴──────────┴───────────────────┘  │
+│  indicators.py（技术指标）      vector_store.py（向量REST） │
+└───────────────┬──────────────────────────┬──────────────┘
+                │                          │
+     ┌──────────▼──────────┐   ┌──────────▼───────────────┐
+     │  SQLite (本地库)      │   │  Chroma(16010) + bge(16011)│
+     │  stock_advisor.db    │   │  新闻索引/公司概况索引        │
+     └─────────────────────┘   └──────────────────────────┘
+                │
+     ┌──────────▼──────────┐
+     │  DeepSeek (RAG研报)  │   SMTP (舆情邮件通知)
+     └─────────────────────┘
+```
+
+- **向量库**：纯 REST 直连（无 chromadb 客户端依赖），Embedding 用 bge-large-zh-v1.5（1024 维）
+- **大模型**：DeepSeek `deepseek-v4-flash`（推理型，研报生成约 25-40 秒，后台线程 + 前端轮询）
+- **定时任务**：舆情监控调度器（后台守护线程，默认 30 分钟一轮）
+
+---
+
+## 📂 目录结构
+
+```
+stock-advisor/
+├── app.py                 # Flask 主应用（页面 + 全部 API）
+├── config.py              # 全局配置（端口/LLM/向量库/邮件/监控默认值）
+├── database.py            # SQLite 连接与表结构（13 张表）
+├── settings.py            # 设置管理器（settings 表 + 默认值合并）
+├── seed_data.py           # 模拟数据生成器（行情/新闻/机构/持仓 + 向量/回测构建）
+├── start.sh               # 启动/停止/重启/状态/重灌脚本
+├── requirements.txt       # 依赖：flask, requests
+├── engine/
+│   ├── indicators.py      # 技术指标：MA/RSI/MACD/KDJ/量比/波动率
+│   ├── scoring.py         # 六因子评分模型 + 规则化推荐理由
+│   ├── analyst.py         # DeepSeek 研报 + RAG 增强 + 历史记录
+│   ├── strategies.py      # 量化策略信号生成 + 回测引擎
+│   └── notifier.py        # 舆情监控：重要度评分 + SMTP 邮件 + 调度器
+├── rag/
+│   └── vector_store.py    # Chroma/Embedding 纯 REST 封装
+├── templates/             # 10 个页面模板
+├── static/
+│   ├── css/style.css
+│   ├── js/                # 各页面脚本
+│   └── lib/marked.min.js  # Markdown 渲染（本地无 CDN）
+├── data/                  # stock_advisor.db（运行时生成）
+└── logs/                  # 运行日志
+```
+
+---
+
+## 🚀 快速开始
+
+```bash
+cd works/stock-advisor
+./start.sh start     # 启动（端口 16095）
+./start.sh status    # 查看状态
+./start.sh stop      # 停止
+./start.sh restart   # 重启
+./start.sh seed      # 一键重灌数据（含向量重建 + 策略回测，约 1-3 分钟）
+
+# 手动执行数据生成（可选参数）
+/home/hz1/miniconda3/envs/openclaw/bin/python3 seed_data.py            # 全量（DB+向量+回测）
+/home/hz1/miniconda3/envs/openclaw/bin/python3 seed_data.py --skip-vector      # 跳过向量重建
+/home/hz1/miniconda3/envs/openclaw/bin/python3 seed_data.py --no-strategies    # 跳过策略回测
+```
+
+**访问**：`http://<服务器IP>:16095/`
+
+**依赖环境**：openclaw conda 环境（`flask`、`requests`）；外部服务 Chroma 16010 + Embedding 16011（本机常驻）。
+
+---
+
+## 🗄️ 数据库设计（SQLite，13 张表）
+
+| 表 | 说明 | 关键字段 |
+|---|---|---|
+| `stocks` | 股票基础信息（68 只） | code/name/industry/board/market_cap/pe/pb/description |
+| `stock_daily` | 日线行情（12240 条） | code/date/OHLC/volume/amount/change_pct |
+| `market_index` | 上证/深证/创业板指数 | date/sh/sz/cy |
+| `news` | 财经新闻（305 条，RAG 语料） | title/content/category/sentiment/related_stocks |
+| `institutions` | 机构实体（27 家） | name/type(公募/券商/保险/外资/私募)/description |
+| `inst_ratings` | 机构评级（165 条） | inst_id/stock_code/rating/target_price/rating_date |
+| `fund_holdings` | 基金季度持仓（363 条） | inst_id/stock_code/quarter/hold_value/change_pct |
+| `watchlist` | 用户自选股 | code |
+| `analysis_cache` | 研报最新缓存 | code/report |
+| `analysis_history` | AI 分析历史（含数据源 JSON） | code/focus/report/sources |
+| `strategy_backtests` | 策略回测结果（408 条） | strategy/code/metrics/equity/trades |
+| `settings` | 系统设置 KV | key/value |
+| `notification_log` | 舆情通知日志 | news_id/importance/status |
+
+---
+
+## 🎯 核心模块详解
+
+### 1. 六因子评分模型（engine/scoring.py）
+
+满分 100，评级：**强烈推荐 ≥82 / 推荐 ≥68 / 关注 ≥55 / 观望 <55**
+
+| 因子 | 满分 | 依据 |
+|---|---|---|
+| 趋势 | 25 | 均线多头排列 + 站上 MA20 |
+| 动量 | 20 | 5 日涨幅区间映射（过急扣分防追高） |
+| 技术 | 15 | RSI 健康区间 / 超买超卖 |
+| 量能 | 10 | 量比 |
+| 消息 | 15 | 近 7 日相关新闻情感均值 |
+| 机构 | 15 | 近 30 日正面评级数 + 基金持仓动向 |
+
+同时生成**规则化推荐理由**（趋势/动量/RSI/量能/消息/机构），列表页直接展示，无需 LLM。
+
+### 2. AI 深度研报（engine/analyst.py，RAG 增强）
+
+```
+触发 → RAG检索(个股新闻向量命中 + 公司概况) + 技术指标 + 机构评级/持仓 + 六因子评分
+     → 组装提示词 → DeepSeek 推理生成 Markdown 研报
+     → 写入 analysis_history（含数据源快照）→ 前端轮询展示
+```
+
+研报结构：公司概况 / 技术面 / 消息面 / 机构动向 / 风险提示 / 操作建议（目标区间·支撑·压力位）。
+
+**数据源详情页 `/analysis/<id>`** 可追溯每次分析参考的：
+- 📰 RAG 相关资讯（含情感 + 向量相似度）
+- 🏢 公司概况 / 📈 技术指标 / 🎯 综合评分
+- 🏦 机构评级 / 💼 基金持仓 / 🧠 完整提示词
+
+### 3. 量化策略回测（engine/strategies.py）
+
+**6 个主流策略**（全市场 × 6 = 408 条预计算，秒级加载）：
+
+| 策略 | 参数 | 类型 |
+|---|---|---|
+| 双均线金叉 | MA5/MA20 | 趋势 |
+| MACD 金叉 | 12/26/9 | 趋势 |
+| RSI 超买超卖 | RSI(14) 30/70 | 反转 |
+| 布林带回归 | 20日/2σ | 均值回归 |
+| 20日动量 | 20日涨幅/MA20 | 动量 |
+| N日新高突破 | 20日高低点 | 突破 |
+
+**回测规则**：收盘产生信号 → **次日开盘成交**（全仓多头，避免未来函数）；指标含总收益/年化/最大回撤/夏普/胜率/盈亏比/交易次数/超额收益；并对比**买入持有**基准净值曲线。
+
+> 扩展新策略：在 `STRATEGIES` 注册 name/desc + 实现 `_signals()` 即可。
+
+### 4. 舆情驱动自动化（engine/notifier.py）
+
+**流程**：后台调度线程（默认 30 分钟）→ 扫描新新闻（水位去重）→ **重要度评分** → 达标 → **SMTP 邮件通知**
+
+**重要度评分（0-100）**：
+```
+类别基础分（公司40/业绩35/机构30/行业25/市场15）
++ |情感| × 情感权重 × 100
++ 关键词命中 ×12/个（回购/中标/减持/问询/超预期…）
++ 关联个股 ×5/只
+```
+
+**防打扰机制**：`monitor_last_news_id` 水位只扫新增；首次启动只建水位不通知历史；单封邮件最多 20 条。
+
+### 5. 系统设置（/settings）
+
+- **📧 邮件**：SMTP 服务器/端口/加密模式（plain/starttls/ssl）/账号/密码/收件人 + 测试邮件
+- **🤖 大模型**：base_url / api_key / model（**运行时生效**）+ 测试连接
+- **📰 监控**：开关/间隔/分类/阈值/关键词 + 立即扫描 + 通知日志
+
+> 设置存入 `settings` 表，优先于 `config.py` 默认值，无需改代码。
+
+---
+
+## 🔌 API 文档
+
+### 页面
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| GET | `/` `/stocks` `/recommend` `/strategies` `/news` `/institutions` `/settings` `/admin` | 各页面 |
+| GET | `/stock/<code>` | 个股详情页 |
+| GET | `/analysis/<id>` | AI 分析详情页 |
+
+### 行情/股票
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| GET | `/api/health` | 健康检查 |
+| GET | `/api/overview` | 仪表盘聚合数据（指数/情绪/荐股/要闻/自选） |
+| GET | `/api/stocks?keyword=&industry=&board=&rating=&sort=&page=` | 股票列表（含评分） |
+| GET | `/api/stock/<code>` | 个股详情 + 指标 + 评分 |
+| GET | `/api/stock/<code>/kline?days=` | K线数据 + MA 序列 |
+| GET | `/api/stock/<code>/news` | 个股相关新闻 |
+| GET | `/api/stock/<code>/institutions` | 个股机构评级 + 基金持仓 |
+
+### 荐股/AI
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| GET | `/api/recommend?rating=&limit=` | 评分排名 |
+| POST | `/api/stock/<code>/analyze` | 提交 AI 研报任务 `{focus}` |
+| GET | `/api/stock/<code>/analyze/status` | 轮询研报状态 |
+| GET | `/api/stock/<code>/analyses` | 历史分析列表 |
+| GET | `/api/analyses/<id>` | 分析详情（含数据源） |
+
+### 自选
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| GET | `/api/watchlist` | 自选列表 |
+| POST | `/api/watchlist/<code>` | 加入自选 |
+| DELETE | `/api/watchlist/<code>` | 移出自选 |
+
+### 新闻/机构
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| GET | `/api/news?keyword=&category=&page=` | 新闻列表（分页） |
+| GET | `/api/news/<id>` | 新闻详情（含关联股票） |
+| GET | `/api/institutions?type=` | 机构列表 |
+| GET | `/api/institutions/<id>` | 机构详情 |
+| GET | `/api/ratings/upgrades` | 评级变动榜 |
+| GET | `/api/holdings/moves` | 基金增减持榜 |
+
+### 量化策略
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| GET | `/api/strategies` | 策略列表 + 全市场统计 |
+| GET | `/api/backtest/market?strategy=` | 某策略全市场收益榜 |
+| GET | `/api/backtest?strategy=&code=` | 单股回测详情（净值+交易） |
+| POST | `/api/backtest/rebuild` | 重建全市场回测 |
+
+### 设置/监控
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| GET | `/api/settings` | 读取全部设置 |
+| POST | `/api/settings` | 保存设置 `{mail, llm, monitor}` |
+| POST | `/api/settings/test-email` | 发送测试邮件 |
+| POST | `/api/settings/test-llm` | 测试大模型连接 |
+| POST | `/api/monitor/scan` | 立即扫描新闻 |
+| GET | `/api/monitor/log` | 通知日志 |
+
+### 数据管理
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| GET | `/api/admin/stats` | 表统计 + 向量库状态 |
+| POST | `/api/admin/reseed` | 一键重灌数据 |
+| GET | `/api/admin/healthcheck` | 外部依赖连通性检查 |
+
+---
+
+## 🔌 外部依赖
+
+| 服务 | 地址 | 用途 |
+|---|---|---|
+| Chroma 向量库 | `121.40.164.32:16010` | 新闻/概况向量索引 |
+| Embedding (bge-large-zh-v1.5) | `121.40.164.32:16011` | 1024 维语义向量 |
+| DeepSeek API | `https://api.deepseek.com` | AI 研报生成 |
+| SMTP | `mail.tphai.com:587` | 舆情邮件通知 |
+
+> 向量集合：`stock_news_v1`（新闻 474 条）/ `stock_profiles_v1`（公司概况 68 条）
+
+---
+
+## 📦 模拟数据说明
+
+当前所有行情/新闻/机构数据均为**模拟数据**（页面有"模拟数据"标识），用于功能演示与系统验证：
+
+- 68 只 A 股风格股票，覆盖 20+ 行业（白酒/新能源/半导体/医药/银行/券商…）
+- 180 个交易日日线（随机游走 + 趋势分化，让荐股/回测有区分度）
+- 305 条财经新闻（业绩/行业/公司/机构观点/市场 5 类，带情感标签 + 关联个股）
+- 27 家机构（公募/券商/保险资管/外资/私募）+ 165 条评级 + 363 条季度持仓
+
+### 接入真实数据
+
+```python
+# 1. 改 config.py
+IS_MOCK = False
+
+# 2. 替换 seed_data.py 的数据源（真实行情/新闻/机构接口），保持表结构不变
+#    - stocks / stock_daily / market_index → 真实行情
+#    - news → 真实新闻（保留 category / sentiment / related_stocks 字段）
+#    - institutions / inst_ratings / fund_holdings → 真实机构数据
+
+# 3. 重灌
+./start.sh seed
+```
+
+分析/检索/回测/监控逻辑**零改动**即可对接真实数据。
+
+---
+
+## 📝 版本历史
+
+| 版本 | 内容 |
+|---|---|
+| v1.0.0 | 基础版：股票池/行情/新闻/机构/多因子评分/AI 研报（RAG） |
+| v1.0.1 | 修复：重灌后机构 ID 自增未重置、行业板块字段错位、研报评分口径 |
+| v1.1.0 | AI 分析历史记录 + 数据源详情页（/analysis/&lt;id&gt;，展示 RAG 新闻/提示词等） |
+| v1.2.0 | 量化策略模块：6 主流策略全市场回测 + 单股净值曲线 + 交易明细 |
+| v1.3.0 | 舆情驱动自动化（定期扫新闻→邮件通知）+ 系统设置区（邮件/大模型/监控可配） |
+
+---
+
+## 🗺️ 后续规划（可叠加的高级能力）
+
+- 模拟盘/实盘信号推送（每日盘前舆情日报）
+- 策略参数调优、策略组合与仓位管理
+- 自选股策略联动、财务因子库（真实财报数据）
+- 多模型对比研报、行业轮动分析
+
+---
+
+> ⚠️ 本系统所有内容基于模拟数据生成，仅供系统演示与量化研究，**不构成任何投资建议**。