first commit

doc/开发规范.md

@@ -0,0 +1,3 @@
+- 每个函数都要有中文注释, 包括功能说明、参数说明、返回值说明等,如果有注意事项,也要在注释中特别说明。
+- 每次需求修改都要同时更新文档、代码、测试代码。
+- 每条测试用例都要有一个唯一编号。例如 1-1、2-20 等。

doc/数据源选型.md

@@ -0,0 +1,93 @@
+## 一 mootdx：行情层的绝对主力
+
+mootdx 走 TCP 二进制协议，连的是通达信行情服务器群（37 台，端口 7709）。不需要注册、不需要 API Key、不封 IP。
+
+数据源
+
+- **K 线**：日/周/月/1分/5分/15分/30分/60分，最多 800 根/次
+- **五档盘口**：实时 46 个字段，含 5 档买卖价量
+- **逐笔成交**：含买卖方向标记（0=买、1=卖、2=中性）
+- **季报快照**：37 个字段——EPS、每股净资产、ROE、净利润、营收、流通股本、总股本…
+- **F10 公司资料**：9 大类文本——最新提示、公司概况、财务分析、股东研究、股本结构…
+
+### K 线的 category 参数（文档不全，实测补齐）
+
+|category 值|周期|
+|---|---|
+|4|日线|
+|5|周线|
+|6|月线|
+|7|1 分钟|
+|8|5 分钟|
+|9|15 分钟|
+|10|30 分钟|
+|11|60 分钟|
+
+很多教程写 category=9 是日线，这是错的。**4 才是日线**。
+
+### 踩过的坑
+
+坑 1：datetime 双重存在  
+mootdx 返回的 DataFrame 里，`datetime` 同时出现在 index 和 column 里。直接 `reset_index()` 会报列名重复。正确做法：先 `drop(columns=["datetime"])`，再 `reset_index()`。
+
+坑 2：海外 IP 连不上  
+TCP 直连通达信服务器，需要国内 IP 才稳定。海外 VPS 会超时。
+
+坑 3：block() 和 minute() 返回空  
+这两个接口文档里有，但实测返回空数据。别浪费时间。
+
+坑 4：首次连接测速  
+第一次运行会自动测速所有 37 台服务器，生成 `~/.mootdx/config.json`。之后复用最快的那台。
+
+## 二 腾讯财经：估值数据的最佳来源
+
+腾讯财经的行情接口返回大约 88 个字段，用 `~` 分隔，GBK 编码。不需要注册，不封 IP。
+
+### 全网最大的错误：字段 43 不是 PB
+
+我搜了十几篇腾讯财经 API 的教程，几乎所有人都写"索引 43 = PB（市净率）"。
+
+这是错的。实测校准结果：
+
+|索引|真实含义|备注|
+|---|---|---|
+|39|PE（TTM）||
+|43|振幅%（不是 PB！）|全网教程写错|
+|44|总市值（亿）||
+|45|流通市值（亿）||
+|46|PB（市净率）|真正的 PB 在这|
+|47|涨停价||
+|48|跌停价||
+|52|PE（静态）||
+
+检查你的代码  
+如果你用了别人的代码解析腾讯行情，查一下 PB 数据对不对。很多人用了错误的索引 43，算出来的估值全是歪的。
+
+### 腾讯 vs mootdx：互补关系
+
+mootdx 擅长  
+
+- K 线（多周期）
+- 五档盘口 46 字段
+- 逐笔成交（含方向）
+- 季报快照 37 字段
+- F10 公司资料 9 大类
+- PE / PB / 换手率
+- 总市值 / 流通市值
+- 涨跌停价
+
+  
+腾讯财经擅长  
+
+- PE（TTM）/ PE（静态）
+- PB（市净率）
+- 总市值 / 流通市值
+- 换手率
+- 涨跌停价
+- 季报快照
+- F10 公司资料
+- 逐笔成交方向
+
+  
+
+两个源合在一起，你就有了一个不需要 Key、不封 IP 的完整行情 + 估值数据管道。

doc/概要设计.md

@@ -0,0 +1,279 @@
+# Tortoise 投研回测系统 概要设计
+
+## 1. 项目背景与目标
+
+Tortoise 定位为**个人/小团队**使用的轻量级 A 股投研回测平台。基于
+`doc/数据源选型.md` 中确定的免费、无 Key 的数据组合（mootdx + 腾讯财经），
+对照 `doc/需求.md` 的功能清单，向上构建：自选股管理、行情查看、内置策略
+回测、AI 短期上涨概率推算的一体化工作台。
+
+核心目标（与 `doc/需求.md` 对齐）：
+- **自选股**：增删改查、多分组、当前行情（当日/周/月涨跌、PE/PB）、历史 K 线。
+- **策略**：内置主要策略，按"选股策略 + 执行参数"运行；结果图表化、可叠加多策略、
+  自动持久化（同参数复用，参数变更则覆盖）。
+- **AI 接入**：可配置多模型与提示词，输出短期上涨概率。
+- **暂不开发**：用户权限（仅保留扩展位）。
+
+非功能目标：
+- 单机即可部署，前后端同进程，开箱即用。
+- 数据可复现：策略结果与"数据快照版本"绑定。
+- 预留分布式扩展点（任务队列、独立计算节点）。
+
+## 2. 设计原则
+
+- **B/S 架构**：浏览器即客户端，服务端集中调度数据与计算。
+- **JS 一体式框架**：前后端共享同一个 Node.js 进程与同一套 TS 类型定义。
+- **数据源解耦**：以 `DataAdapter` 抽象隔离 mootdx / 腾讯财经接口，未来可加 akshare、tushare 等。
+- **存储极简**：行情/因子/元数据/任务/策略结果全部收敛到 **单一 DuckDB 文件**，
+  不再引入 SQLite 与独立 Parquet 目录（详见第 5.2 节）。
+- **任务化**：所有耗时操作（拉数据、回测、AI 调用）走任务队列，UI 实时订阅进度。
+- **可复现**：策略代码版本 + 参数 + 数据快照版本号 三者绑定。
+- **遵循 `doc/开发规范.md`**：函数中文注释（功能/参数/返回/注意事项）；需求变更
+  同步更新文档+代码+测试；测试用例使用唯一编号（章-序）。
+
+## 3. 技术选型
+
+| 层 | 选型 | 说明 |
+|---|---|---|
+| 一体式框架 | **Nuxt 3 (Nitro + Vue 3)** | 同进程托管 SSR 前端 + `server/api` REST + WebSocket；TS 原生 |
+| UI 库 | Element Plus + ECharts 5 | 表格、表单、K 线、净值/概率曲线 |
+| 状态管理 | Pinia | 与 Nuxt 3 集成最佳 |
+| 后端运行时 | Node.js ≥ 20（Nitro） | |
+| **存储** | **DuckDB（单文件）** | 同一个 `tortoise.duckdb` 同时承载行情、因子、元数据、任务、策略与 AI 结果；通过 schema 分区（`md.* / meta.* / run.*`） |
+| 缓存 | 进程内 LRU | 热点行情/快照短期缓存，避免穿透 DuckDB |
+| 任务队列 | 内置内存队列（默认） / BullMQ + Redis（可选） | 检测到 `REDIS_URL` 自动切换 |
+| 数据源桥接 | 本地 Python sidecar（FastAPI + mootdx） + Node 端 HTTP（腾讯财经） | mootdx 仅 Python 实现 |
+| AI 接入 | OpenAI 兼容协议为主，扩展 Anthropic/本地 Ollama | 模型与 Prompt 配置存 DuckDB |
+| 策略沙箱 | `isolated-vm` | 隔离用户/内置策略代码，禁用 fs/net |
+| 测试 | Vitest（单测/接口） + Playwright（端到端） | 用例编号遵循 `章-序` |
+| 包管理 | pnpm | |
+| 部署 | 单机 `node .output/server/index.mjs` 或 Docker Compose（含 sidecar） | |
+
+> 关于 mootdx：因仅有 Python 实现，Tortoise 用一个常驻 **Python FastAPI sidecar**
+> 暴露 `/kline /snapshot /f10 /finance` 等接口，Node 端通过 `DataAdapter` 调用。
+> 腾讯财经字段解析全部在 Node 端实现（已校准索引：39=PE_TTM、43=振幅、46=PB、52=PE 静态）。
+
+## 4. 总体架构
+
+```
+┌───────────────────────────────────────────────────────────────┐
+│                        Browser (Vue 3 SSR/SPA)                │
+│  自选股 │ 行情/K 线 │ 策略运行台 │ 结果对比 │ AI 概率 │ 任务  │
+└───────────────▲───────────────────────────▲───────────────────┘
+                │ HTTPS / WebSocket         │
+┌───────────────┴───────────────────────────┴───────────────────┐
+│                Nuxt 3 一体式服务（Node.js 20）                │
+│ ┌──────────┐ ┌────────────┐ ┌─────────────────────────────┐   │
+│ │  Pages   │ │ server/api │ │   WebSocket / SSE 推送      │   │
+│ └──────────┘ └─────┬──────┘ └──────────────┬──────────────┘   │
+│                     │                       │                  │
+│ ┌───────────────────┴───────────────────────┴───────────────┐  │
+│ │                     Service 层                             │  │
+│ │ Watchlist │ Market │ Strategy │ AI │ Job │ Data           │  │
+│ └───┬────────┬─────────┬─────────┬─────┬─────────┬──────────┘  │
+│     │        │         │         │     │         │             │
+│ ┌───┴───┐ ┌──┴──────┐ ┌┴────────┐ ┌┴──┐ ┌──────┴─────────┐     │
+│ │Adapter│ │ Indicator│ │Strategy │ │AI │ │  Job Queue     │     │
+│ │mootdx │ │ Library  │ │Registry │ │Hub│ │ memory/BullMQ  │     │
+│ │腾讯   │ │          │ │(内置)   │ │   │ │                │     │
+│ └─┬───┬─┘ └──────────┘ └─────────┘ └─┬─┘ └────────────────┘     │
+│   │   │                              │                          │
+│   │   └─ HTTP ─► 腾讯财经 qt.gtimg.cn │                          │
+│   └──── HTTP ─► Python sidecar (mootdx, FastAPI)               │
+│                                                                 │
+│ ┌────────────────────────────────────────────────────────────┐  │
+│ │   单一存储：tortoise.duckdb（schema 分区 md/meta/run）     │  │
+│ └────────────────────────────────────────────────────────────┘  │
+└───────────────────────────────────────────────────────────────┘
+```
+
+## 5. 模块划分
+
+### 5.1 数据采集层（DataAdapter）
+- `MootdxAdapter`：通过 sidecar 拉取 K 线（category 4=日、5=周、6=月、7=1m…11=60m）、
+  五档、逐笔、季报、F10。内置坑位规避：`drop(columns=["datetime"])` 后 `reset_index`；
+  屏蔽 `block()/minute()` 空接口。
+- `TencentAdapter`：HTTP 调 `qt.gtimg.cn`，GBK 解码，按校准后的索引解析 PE/PB/振幅/
+  市值/涨跌停。带断言（PE/PB 合理性），异常告警。
+- 统一输出标准 DTO：`Kline`、`Snapshot`、`Tick`、`FinanceSnapshot`、`F10Section`，
+  共享于 `shared/dto/`，前后端复用 Zod 校验。
+
+### 5.2 数据存储层（**单一 DuckDB**）
+
+> 决策：原方案"DuckDB + SQLite + Parquet"三件套合并为 **一个 DuckDB 文件**。
+> 理由：
+> 1. DuckDB 同时支持列存大表（行情/因子）与小事务表（元数据），单连接即可覆盖。
+> 2. 备份/迁移 = 拷贝单文件，避免三套生命周期不一致。
+> 3. Parquet 仅作为"导出/外部分析"格式，不再作为运行期主存储；需要时用
+>    `COPY ... TO 'xxx.parquet'` 一行导出即可。
+> 4. 单机场景下事务并发压力低，DuckDB 的 MVCC 足以承担元数据写入。
+
+DuckDB 内部按 schema 分区，文件名 `data/tortoise.duckdb`：
+
+| schema | 表 | 说明 |
+|---|---|---|
+| `md` (market data) | `kline_daily(symbol,date,o,h,l,c,vol,amount,adj)` | 日线，主键 (symbol,date) |
+|  | `kline_min(symbol,ts,period,o,h,l,c,vol)` | 多周期分钟线，period∈{1,5,15,30,60} |
+|  | `snapshot_daily(symbol,date,pe_ttm,pe_static,pb,mcap,float_mcap,turnover,limit_up,limit_down,amplitude)` | 估值快照（腾讯校准字段） |
+|  | `finance_quarter(symbol,report_date,...37 字段)` | mootdx 季报快照 |
+|  | `f10(symbol,section,content,fetched_at)` | F10 9 大类文本 |
+| `meta` | `instruments(symbol,name,exchange,board,listed_at,delisted_at,...)` | 标的元数据 |
+|  | `watchlist(id,symbol,note,created_at)` | 自选股 |
+|  | `watchlist_group(id,name)` | 分组 |
+|  | `watchlist_group_map(watchlist_id,group_id)` | 多对多映射（满足"一个自选股属多个分组"） |
+|  | `data_jobs(id,kind,params,status,error,started_at,finished_at)` | 数据/策略/AI 任务 |
+|  | `ai_providers(id,name,base_url,api_key_enc,model,enabled)` | AI 模型配置 |
+|  | `ai_prompts(id,scene,template,version,active)` | 提示词模板（按场景版本化） |
+|  | `data_versions(as_of_ts,scope,row_count,checksum)` | 数据快照版本（供回测/AI 复现） |
+| `run` | `strategies(id,code_id,name,kind,params_schema)` | 内置策略注册表 |
+|  | `strategy_runs(id,strategy_id,universe_hash,params_hash,as_of_ts,status,started_at,finished_at)` | 策略运行记录；同 (strategy_id,universe_hash,params_hash) 复用，参数变化即新建 |
+|  | `strategy_curves(run_id,date,equity,position_json)` | 策略每日净值/持仓 |
+|  | `strategy_metrics(run_id,key,value)` | 年化、回撤、Sharpe 等指标 |
+|  | `ai_runs(id,provider_id,prompt_id,symbol,as_of_ts,prob_up,horizon_days,raw_response)` | AI 概率推算结果 |
+
+> **复用规则**（对应需求"自动保存策略执行结果"）：
+> 以 `(strategy_id, universe_hash, params_hash, as_of_ts)` 作为幂等键，相同键复用历史结果；
+> 参数或选股变化导致 hash 变化 → 新建运行，旧记录保留；同 hash 重跑则覆盖（按需求要求）。
+
+并发与备份：
+- **写入集中**：仅 Job Worker 持有可写连接，Web 请求走只读连接。
+- **备份**：每日定时 `EXPORT DATABASE 'backup/yyyymmdd'`（DuckDB 原生命令，输出 Parquet+SQL）。
+  这是唯一保留的 Parquet 用途——离线备份/外部分析，不参与运行期。
+
+### 5.3 业务服务层
+
+- `WatchlistService`：自选股 CRUD + 分组多对多 + 当前行情聚合（合并 mootdx 当日 + 腾讯快照）。
+- `MarketService`：K 线/快照/F10 查询；周/月涨跌由日线即时聚合（DuckDB SQL `window`）。
+- `StrategyService`：
+  - 内置策略注册（`strategies` 表 + 代码集中在 `server/engine/strategies/*.ts`）。
+  - 运行入口：传入 `strategyId + 选股策略 + 参数`；命中幂等键直接返回历史结果。
+  - 多策略对比：同一图表叠加多个 `run_id` 的 `strategy_curves`。
+- `AIService`：
+  - `providers/prompts` 管理 API；
+  - `predictUp(symbol, horizon)`：拼装提示词（含最近行情、估值、F10 摘要）→ 调模型 → 解析概率 → 落 `ai_runs`。
+  - 提示词模板支持变量：`{{symbol}} {{kline_summary}} {{valuation}} {{news}}`。
+- `JobService`：任务登记/进度/取消；统一 WebSocket 频道 `/_ws/jobs`。
+- `DataService`：增量拉取调度、缺口检测、`data_versions` 写入。
+
+### 5.4 Web 应用层
+
+页面（与需求一一对应）：
+
+| 路由 | 对应需求 | 关键组件 |
+|---|---|---|
+| `/watchlist` | 自选股增删改查、分组、当前行情 | 分组侧栏 + 行情表（涨跌/PE/PB） |
+| `/quote/:symbol` | 历史 K 线/财务/F10 | ECharts K 线 + 切换周期 |
+| `/strategy` | 策略运行台 | 选择内置策略 → 选股策略 → 参数表单 → 运行 |
+| `/strategy/compare` | 多策略叠加 | 多 `run_id` 净值曲线叠加 |
+| `/ai` | AI 模型与提示词配置、批量预测 | Provider/Prompt 管理 + 概率结果 |
+| `/jobs` | 任务监控 | 列表 + 实时日志 |
+| `/data` | 数据更新 | 触发增量、查看版本 |
+
+API（统一 JSON + Zod 校验）：
+- `/api/watchlist/*`、`/api/quote/*`、`/api/strategy/*`、`/api/ai/*`、`/api/jobs/*`、`/api/data/*`。
+- 实时通道：`/_ws`（任务进度、策略增量净值、AI 流式 token 可选）。
+
+### 5.5 任务调度
+
+- 默认内存队列；检测到 `REDIS_URL` 自动切 BullMQ。
+- 内置任务：日终增量拉数、F10 月更、策略运行、AI 批量预测、每日备份。
+- cron 表达式存 `meta.data_jobs`（`kind='cron'` 子类）。
+
+## 6. 关键流程
+
+### 6.1 自选股查看
+1. 前端 `/watchlist` 拉 `meta.watchlist + watchlist_group_map`。
+2. `WatchlistService.enrich()`：
+   - 当日涨跌、PE/PB → `TencentAdapter` 实时（带 LRU 缓存 5s）。
+   - 周/月涨跌 → DuckDB 对 `md.kline_daily` 做 5/20 日窗口聚合。
+3. 返回合并 DTO；点击单只 → `/quote/:symbol` 走 `MarketService` 拉 K 线。
+
+### 6.2 策略运行（含自动保存与复用）
+1. 用户在 `/strategy` 选择内置策略 + 选股策略（universe）+ 参数。
+2. 服务端计算 `params_hash = sha1(json(params))`、`universe_hash = sha1(symbols)`、
+   `as_of_ts = max(md.kline_daily.date)`。
+3. 在 `run.strategy_runs` 查 `(strategy_id, universe_hash, params_hash, as_of_ts)`：
+   - 命中且状态=success → 直接返回历史 `run_id`（**自动复用**）。
+   - 否则新建 run（参数变更 → 新 run，覆盖语义通过 UI 保留最新一条同参数 run）。
+4. Job Worker 拉起策略：从 DuckDB 流式读 bar，按事件驱动撮合，写
+   `strategy_curves` 与 `strategy_metrics`。
+5. WebSocket 推送净值；完成跳到结果页（ECharts 渲染）。
+6. 多策略对比：在 `/strategy/compare` 选多条 `run_id` → 单图叠加曲线。
+
+### 6.3 AI 短期上涨概率
+1. `/ai/predict` 选标的、提示词模板、模型 provider、预测窗口（如 5 日）。
+2. `AIService` 拼上下文：最近 60 日 K 线摘要、最新估值、最近一期财报关键指标、F10 摘要。
+3. 调模型（OpenAI 兼容/Anthropic/Ollama），解析输出概率（要求模型按指定 JSON 格式返回）。
+4. 落 `run.ai_runs`，前端图表展示概率 + 置信区间 + 模型/Prompt 版本。
+5. 支持批量：自选股分组一键预测。
+
+### 6.4 数据增量更新
+1. 调度器触发 `daily-update`。
+2. `DataService` 读 `meta.instruments` → 比对 `md.kline_daily` 最新日期 → 计算缺口。
+3. `MootdxAdapter` 拉缺口 K 线（≤800 根/次自动分页）+ 季报；`TencentAdapter` 拉当日快照。
+4. 写入 DuckDB（事务），更新 `meta.data_versions`、`meta.data_jobs`。
+5. WebSocket 推送进度。
+
+## 7. 目录结构（建议）
+
+```
+tortoise/
+├── app/                     # Nuxt 前端
+│   ├── pages/
+│   │   ├── watchlist.vue
+│   │   ├── quote/[symbol].vue
+│   │   ├── strategy/index.vue
+│   │   ├── strategy/compare.vue
+│   │   ├── ai.vue
+│   │   ├── jobs.vue
+│   │   └── data.vue
+│   ├── components/
+│   └── composables/
+├── server/
+│   ├── api/                 # REST 端点
+│   ├── services/            # Watchlist/Market/Strategy/AI/Job/Data
+│   ├── adapters/            # mootdx / tencent
+│   ├── engine/
+│   │   ├── indicator/       # 指标库
+│   │   ├── strategies/      # 内置策略
+│   │   └── backtest/        # 撮合/绩效
+│   ├── ai/                  # provider/prompt 引擎
+│   ├── jobs/                # 队列与定时任务
+│   └── db/                  # duckdb 单连接封装、迁移脚本
+├── sidecar/                 # Python FastAPI + mootdx
+├── shared/                  # 前后端共享 TS 类型 + Zod schema
+├── tests/                   # Vitest + Playwright（用例编号 章-序）
+├── data/                    # tortoise.duckdb + backup/
+├── doc/
+└── nuxt.config.ts
+```
+
+## 8. 安全与运维
+
+- 默认绑定 `127.0.0.1`，对外发布需走反向代理（用户权限按需求暂不开发，仅预留中间件位）。
+- 数据源限速：mootdx 单连接串行 + 退避；腾讯每秒 ≤ 10 请求；AI 调用按 provider 配置 RPS。
+- AI Key：`ai_providers.api_key_enc` 用本地随机主密钥 AES-GCM 加密；主密钥放
+  `data/.master.key`（gitignore）。
+- 日志：pino + 按日切分；任务失败落 `meta.data_jobs.error`。
+- 备份：每日 `EXPORT DATABASE` 到 `data/backup/yyyymmdd/`，保留 N 天。
+- 策略沙箱：`isolated-vm` 禁用 fs/net，仅暴露受控的指标/数据 API。
+
+## 9. 里程碑（与需求一致的优先级）
+
+| 阶段 | 范围 | 产出 |
+|---|---|---|
+| M1 数据底座 | DataAdapter + 单 DuckDB + 数据更新页 | A 股全市场日线/估值/季报入库 |
+| M2 自选股与行情 | Watchlist CRUD + 分组 + 当前行情 + K 线页 | 覆盖需求"自选股"全部条目 |
+| M3 策略 | 内置策略 + 运行台 + 自动保存/复用 + 多策略叠加 | 覆盖需求"策略"全部条目 |
+| M4 AI 接入 | Provider/Prompt 管理 + 概率预测 + 批量 | 覆盖需求"AI 接入" |
+| M5 调度与备份 | 定时任务 + 备份 + 任务监控完善 | 长期稳定运行 |
+
+## 10. 风险与对策
+
+- **mootdx 海外不可用** → sidecar 必须部署在国内主机；UI 给出连通性自检。
+- **腾讯字段索引漂移** → `TencentAdapter` 自带断言（PE_TTM、PB 范围），异常立即告警。
+- **DuckDB 单文件并发** → 写入仅 Job Worker；Web 请求走只读连接；高频读热表加 LRU。
+- **DuckDB 单文件损坏风险** → 每日 `EXPORT DATABASE` 备份，启动时校验。
+- **策略代码安全** → `isolated-vm` 沙箱禁用 fs/net。
+- **AI 输出不稳定** → 强制 JSON Schema 输出 + 重试 + 失败留 `raw_response` 供排查。
+- **数据一致性 / 结果可复现** → 每次写入登记 `meta.data_versions`，策略与 AI 运行绑定 `as_of_ts`。

doc/需求.md

@@ -0,0 +1,20 @@
+
+## 必须功能
+- 自选股
+    - 支持增删改查
+    - 支持分组，一个自选股可以属于多个分组
+    - 支持查看当前信息（当日涨跌、当周涨跌、当月涨跌、PB、PE）
+    - 支持查看历史数据和其他信息（K线图等）
+- 策略
+    - 主要策略内置，每次执行输入选股策略和执行策略参数。
+    - 策略执行结果绘制成图表展示。
+    - 支持多个策略运行结果展示在同一个图表上。
+    - 自动保存策略执行结果，方便多次打开。除非修改参数重新运行后，结果替换。
+
+- AI 接入
+    - 可接入多个 AI 模型，提示词可配置。
+    - 基于 AI 模型推算短期上涨概率。近 10 个交易日内预测结果和实际结果对比。
+
+
+## 暂时不开发的功能
+- 用户权限