diff --git a/README.md b/README.md new file mode 100644 index 0000000..b546ecc --- /dev/null +++ b/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/` | ECharts K线、技术指标、六因子评分、相关资讯、AI 研报、历史分析 | +| 📑 AI 分析详情 | `/analysis/` | 研报正文 + **大模型参考的数据源**（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/`** 可追溯每次分析参考的： +- 📰 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/` | 个股详情页 | +| GET | `/analysis/` | AI 分析详情页 | + +### 行情/股票 +| 方法 | 路径 | 说明 | +|---|---|---| +| GET | `/api/health` | 健康检查 | +| GET | `/api/overview` | 仪表盘聚合数据（指数/情绪/荐股/要闻/自选） | +| GET | `/api/stocks?keyword=&industry=&board=&rating=&sort=&page=` | 股票列表（含评分） | +| GET | `/api/stock/` | 个股详情 + 指标 + 评分 | +| GET | `/api/stock//kline?days=` | K线数据 + MA 序列 | +| GET | `/api/stock//news` | 个股相关新闻 | +| GET | `/api/stock//institutions` | 个股机构评级 + 基金持仓 | + +### 荐股/AI +| 方法 | 路径 | 说明 | +|---|---|---| +| GET | `/api/recommend?rating=&limit=` | 评分排名 | +| POST | `/api/stock//analyze` | 提交 AI 研报任务 `{focus}` | +| GET | `/api/stock//analyze/status` | 轮询研报状态 | +| GET | `/api/stock//analyses` | 历史分析列表 | +| GET | `/api/analyses/` | 分析详情（含数据源） | + +### 自选 +| 方法 | 路径 | 说明 | +|---|---|---| +| GET | `/api/watchlist` | 自选列表 | +| POST | `/api/watchlist/` | 加入自选 | +| DELETE | `/api/watchlist/` | 移出自选 | + +### 新闻/机构 +| 方法 | 路径 | 说明 | +|---|---|---| +| GET | `/api/news?keyword=&category=&page=` | 新闻列表（分页） | +| GET | `/api/news/` | 新闻详情（含关联股票） | +| GET | `/api/institutions?type=` | 机构列表 | +| GET | `/api/institutions/` | 机构详情 | +| 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/<id>，展示 RAG 新闻/提示词等） | +| v1.2.0 | 量化策略模块：6 主流策略全市场回测 + 单股净值曲线 + 交易明细 | +| v1.3.0 | 舆情驱动自动化（定期扫新闻→邮件通知）+ 系统设置区（邮件/大模型/监控可配） | + +--- + +## 🗺️ 后续规划（可叠加的高级能力） + +- 模拟盘/实盘信号推送（每日盘前舆情日报） +- 策略参数调优、策略组合与仓位管理 +- 自选股策略联动、财务因子库（真实财报数据） +- 多模型对比研报、行业轮动分析 + +--- + +> ⚠️ 本系统所有内容基于模拟数据生成，仅供系统演示与量化研究，**不构成任何投资建议**。