Skip to content

spec.md

Latest commit

 

History

History
350 lines (274 loc) · 24.1 KB

spec.md

File metadata and controls

350 lines (274 loc) · 24.1 KB
Raw

StockPro 产品规格

文档角色：当前产品级事实入口 更新日期：2026-08-28 当前交付边界：B/S、PostgreSQL、研究优先、仅 Paper 模拟交易（实盘仅预检与留痕）

1. 产品定义

StockPro 是面向个人量化研究员和 A 股策略操作者的本地研究工作台。它覆盖“数据 → 因子 → 股票池 → 策略 → 回测 → Paper → 盯盘/监控 → 复盘”的完整链路，并要求每个下游对象保留可重现的上游版本和证据。

StockPro 不以荐股、自动实盘或营销式 AI 评分为产品中心。系统的核心价值是：

  1. 把市场事实、研究假设和策略结论分开表达。
  2. 让数据来源、交易日、可用时间、新鲜度和缺失原因可见。
  3. 让因子、股票池、策略、回测和模拟执行可以追溯与复现。
  4. 在启用任何真实交易能力前维持明确的技术与产品隔离。

2. 用户与权限

管理员

  • 管理数据、因子、股票池、策略、回测、Paper 和本地 Agent Token。
  • 执行同步、创建版本、运行回测与控制 Paper 实例。
  • 查看所有审计证据。

访客

  • 以只读方式查看研究和运行状态。
  • 只允许在显式配额与权限范围内发起回测。
  • 不能同步数据、修改策略、控制 Paper 或执行其他写操作。

当前不是公开 SaaS，不提供注册、计费、团队租户或公开 API。

3. 一级信息架构

侧栏保持 BitPro 常驻信息架构，主线在视觉顺序上突出“策略 → 回测 → 模拟”。 所有紧凑指标卡、KPI 卡与小型数据方块使用至少 8px 的可见圆角；指标矩阵不得用 gap-px 拼成直角网格。 研究、运行和能力页都是同一壳层下的 Owner 页面，不另建研究台 IA。

分组 可见页面 路由
总览 首页 /
研究 行情 /market
研究 股票池/价差 /arbitrage
研究 因子 /factorlab
主线 策略 /strategy
主线 回测 /backtest
主线 模拟 /live
运行 盯盘 /watch
运行 信号 /signals
运行 监控 /monitor
运行 复盘 /review
能力 数据 /data
能力 AI 研发 /ai-lab

期货 /futures 仅领域预留，导航隐藏并回首页。真实交易 /live-real 不注册为产品路由； BitPro 遗留的 /pools、/factors、/paper 分别跳转到 /arbitrage、/factorlab、/live， 不再作为最终截图或验收入口。

首页首次就绪检查只读汇总管理员安全配置、PostgreSQL 迁移、TuShare 主源、封存研究快照以及后续策略/Paper/复盘状态；每项只提供 Owner 页面链接，不自动修复。首页和模拟页均提供统一盘后复盘入口。

首页市场驾驶舱通过单一 GET /api/v2/market/dashboard 读取真实 A 股封存事实；其中 overview 子合同统一返回 指数、宽度与涨跌分布、60 日趋势强度、成交/换手/量比和四类排行榜，后续模块返回涨跌停/炸板/连板梯队、 六阶段、行业/概念 RPS、异动和只读事件。各模块携带 trade_date、source_snapshot_id、 available_at、knowledge_cutoff_at、状态和缺失输入；历史或指标不足时保持 null/blocked，不得用 股票代替指数、用客户端合成走势或把缺失值改成 0。Dashboard GET 只读 PostgreSQL，并用短时单航班缓存避免 重复读取；provider_calls=0、writes_performed=false、paper_mutated=false 是固定安全边界。

首页另提供 ?tab= 分析板块：连板梯队、概念分析、行业分析、市场环境、异动监控、个股分析。 三个只读端点 /api/v2/market/limit-ladder、/concept-analysis、/industry-analysis 分别聚合旧管道连板/涨跌停池、概念每日快照+资金流、以及与热力图同口径的行业等权涨跌； RPS/六阶段/异动物化缺失时页面显示诚实空态与原因，GET 不补算、不写库。

完整路由：

/            首页 / 市场大盘
/market      行情（代码.市场）
/arbitrage   股票池/价差
/factorlab   因子
/strategy    策略
/backtest    回测
/live        模拟盘 / 现金账本
/watch       盯盘
/signals     信号
/monitor     监控
/review      复盘 / 交易日历
/data        数据
/ai-lab      AI 研发

当前 sprint 不开放真实交易入口。未配置券商通道且未开启 LIVE_TRADING_ENABLED 时， 任何实盘部署请求都被安全拦截并留痕。

二级标签表示同一工作阶段下的不同视图；详情页、抽屉和对象内标签属于三级界面。旧的情绪、新闻、日历、策略开发和交易路由只承担兼容跳转，不再成为独立一级菜单。

行情页提供 PostgreSQL 自选清单；清单只持久化证券代码与备注，价格、涨跌幅、成交额、换手、量比和振幅继续联接唯一的行情缓存，不复制行情事实。 行情页同时提供独立“指数”二级标签，复用 PostgreSQL 指数缓存；首页保留摘要，行情页承担指数深挖入口。 股票、ETF、指数切换清空上一类型状态；指数可回退到 sealed benchmark_bars，ETF 无定义时保持空态。 交易时段默认 1m AKShare 分时，盘后/周末默认 1D PostgreSQL 历史；空盘口不计算 0 价差。

数据中心逐标的覆盖以活动 A 股为统一分母，返回 row_count/from/to 并每页 200 只展示全部证券； 顶部汇总必须等于逐标的求和，统一维护模式下不展示逐标的危险删除操作。

资金流页分钟 OHLCV 主源为 AKShare 分时，服务端缓存 60 秒、前端每分钟刷新；Provider 失败时保留 最后成功快照并标记 stale。分钟线不是 tick/L2，不得推导主动买卖、大单明细或 CVD。

基本面页读取 sealed daily_basic 估值和公告时点 fundamental_factor_facts。管理员显式同步 TuShare 财务指标、股东户数和分红；GET 按 as_of 截止过滤未来公告，页面展示报告期、公告日、 可用时间、来源和 CNY 口径，不保留链上/DeFi 语义。

4. 核心产品对象

对象 关键要求
数据分区 按数据集、交易日和来源持久化，保留采集和质量状态
数据快照 质量通过后封存；包含知识截止时间、清单与哈希
因子版本/快照 定义、代码、方向、依赖和因子值不可变
股票池快照 固定股票范围、入选原因、规则和数据证据
策略版本 普通 Python 代码、参数、依赖和运行限制不可变
回测任务 异步执行；固定所有输入并持久化指标、订单、成交和日志
Paper 实例 隔离执行；记录信号、风控、订单、成交、持仓、现金和周期
复盘记录 绑定交易日与市场证据，记录结论、风险和次日计划

任何已被回测或 Paper 使用的版本不得原地修改。修改代码或参数必须创建子版本。

5. 标准工作流

  1. 数据中心同步证券主数据、交易日历和研究数据。 生产环境每天北京时间 18:10 通过 TuShare 全量刷新 A 股证券主数据、最近开放交易日日线和 daily_basic；单次运行先完整取数，再在 PostgreSQL 单事务 upsert，失败不得留下半批业务数据。 管理员也可以显式发起最近 180 个自然日的全市场 A 股 1D 日线回补；任务按交易日记录进度， 全部 Provider 请求完成后再一次性幂等写入 PostgreSQL。该任务同时拉取真实沪深300日线， 按证券行业成员构造等权行业对照，并把 sealed 市场证据 snapshot 与最新日 3/10/30 日异动 metrics 和股票历史在同一事务提交；任一步失败整体回滚。
  2. 系统保存来源与权限状态，执行覆盖率、一致性和完整性检查。
  3. 质量通过的数据分区封存为数据快照。
  4. 因子运行只读取封存快照，发布不可变因子值与诊断结果。
  5. 股票池根据显式规则和证据生成并封存。
  6. 策略版本绑定所需数据、因子、股票池、协议和成本模型。
  7. 回测任务异步运行并保存完整结果；探索性或快速结果不能冒充晋级证据。快速预检墙钟 3 秒；完整回测/Paper 回放可使用独立的 180 秒回放信封。完整结果按小页写入订单、成交和持仓，避免 SSH 隧道被单次大 INSERT 卡死。
  8. 通过验证的固定版本可创建 Paper 实例。
  9. 盯盘用于人工观察业务事件，监控用于判断系统和数据健康。
  10. 复盘工作区沉淀当日结论、风险和下一交易日计划。

6. A 股研究与执行规则

  • 股票使用明确交易所身份，不能只凭六位代码猜测市场。
  • 研究与执行遵循交易日历、早晚盘时段和午间休市。
  • 默认只做多；卖出受 T+1 可卖数量约束。
  • 委托数量按 100 股整数手处理，清仓零股规则单独表达。
  • 涨跌停、停牌、ST、退市和板块范围参与可交易性与股票池判断。
  • 信号用复权数据时，成交仍需与未复权可交易价格和公司行动一致。
  • 回测至少表达佣金、过户费、印花税、滑点和容量假设。
  • 日线策略在 D 日收盘后才能看到 D 日完整数据，不能在同一根收盘价上成交。

未定义或不可计算的指标保持 null 并显示原因，禁止用数值 0 伪装。

7. 数据来源与可信度

来源策略

  • TuShare：证券主数据、交易日历、日线、复权因子、估值、停复牌、涨跌停、财务、指数等稳定研究数据的主要来源。
  • A 股证券在页面统一显示为“中文简称 标准代码”，例如“贵州茅台 600519.SH”；中文名来自 stock_basic 持久化事实，名称优先、代码次级，禁止维护三只或其他硬编码演示清单。
  • AKShare：公开全市场快照、概念/行业、热榜、涨停生态、新闻、A 股分钟分时和其他 TuShare 不适配数据的补充来源。行情页分钟 K 线可以在本地分钟缓存空、不可用或过期时只读拉取 AKShare 分时接口，并在响应与页面中显式标注实际来源、状态和失败原因；该路径不写库。

回退必须按完整数据集/日期显式记录，不能把两类来源静默拼成一个看似一致的数据集。受限、无权限、超时、空响应、过期和质量失败是不同状态。

时间语义

  • trade_date：市场事实发生的交易日。
  • available_at：模拟研究中最早可以使用该事实的时间。
  • knowledge_cutoff_at：快照固定的知识截止时间。
  • collected_at / source_updated_at：采集或来源更新时间。
  • response_generated_at：API 生成时间，不能用于证明数据新鲜。

只读边界

打开页面、读取 API、健康检查和后端普通启动不得隐式触发 Provider 同步、迁移、bootstrap、Paper 恢复或策略执行。分钟 K 线的只读实时拉取属于页面证据补充，不是同步任务；所有写操作都必须由明确命令、任务或用户动作触发。

外部 CSV、JSON、XLSX 文件先进入隔离的扩展数据暂存表。单文件最多 5MB、10000 行、200 列；XLSX 公式在写库前拒绝。暂存数据可导出为 CSV、JSON、XLSX，但在存在独立映射、质量检查与封存合同前不能进入核心行情、因子、策略、回测或 Paper。

HTTP 扩展导入仅允许 EXTENSION_HTTP_ALLOWED_HOSTS 中精确配置的 HTTPS 主机，禁止重定向，并在请求前拒绝解析到私网、环回、链路本地或保留地址的主机。默认白名单为空。

8. 因子平台

  • 因子实现遵循 StockPro Factor API v1。
  • 定义包含名称、分类、研究假设、方向、依赖、回看期、代码和预处理。
  • 计算只读取已封存数据，发布长表因子值和不可变因子快照。
  • 诊断覆盖缺失、异常、覆盖率、IC/RankIC、分层收益、换手、衰减、暴露和相关性。
  • 因子数量只使用 PostgreSQL 实时口径，并区分注册定义、有效不可变版本、已物化实例和最新值； 目录存在不等于因子已计算、验证或可用于策略。
  • 因子研究状态区分探索、验证、拒绝和 Paper 候选，不表达投资适用性。
  • 研究任务只读取 sealed factor snapshot/value，Trial ledger 保留 coverage、OOS fold、成本压力和 hard gate 失败；任务不会创建策略、回测、Paper 或订单。

9. 策略与回测

策略运行时

  • 策略遵循 StockPro Strategy API v1，核心函数为 initialize(context) 和 handle_data(context, data)。
  • 平台负责数据、模拟时钟、订单 API、A 股撮合、风控、持久化和指标。
  • 用户代码不能直接访问 Provider、数据库、文件写入、网络或券商。
  • 每个版本固定内容哈希、API 版本、参数、依赖清单和 CPU/内存/时长/输出限制。
  • 策略详情必须从同一 strategy_versions 版本展示代码、参数、content hash、验证状态、标的池、入场、 退出、调仓和风险约束，并关联最近 sealed 回测与 Paper 实例。示例链路必须标记“样例/非投资建议”； 未实现的退出、止损或调仓必须作为缺口展示，不得生成看似完整的说明。
  • 策略与 Paper 实例名称统一为 [市场][周期][风格] 策略简称，例如 [A股][日线][打板] 首板放量隔日T。 市场仅 A股 / ETF，周期以 日线 为主；风格是 2–12 字分类（动量、打板、隔日T 等）。 页面已展示周期和资金，名称不得再写 Paper、模拟盘、100万、Sprint、验收、测试链或日期。
  • 回测和 Paper Replay 执行同一策略版本，不允许悄悄切换实现。
  • 预置打板 / 隔日 T 策略运行在 A 股日线 T+1 引擎上：用收盘涨幅 ≥ 9.5%、连板计数和收盘位置近似涨停生态，今日信号次日成交。这不是逐笔高频，也不是当日 T+0。
  • 当前可复现的多年日线宇宙是研究 20 动量池；大票涨停稀疏时，打板策略按同方向强度补齐，避免空仓被误读成系统故障。

回测证据

  • 快速回测用于诊断；完整回测才保存可晋级的完整证据。
  • 回测页统一提供因子验证入口、参数矩阵优化和 Walk-forward；因子入口复用现有 Factor API，不复制因子计算引擎。
  • 结果包括收益、基准、超额、回撤、Sharpe、风险指标、月度表现、持仓、订单、成交、成本、日志和参数。
  • 回测摘要与详情统一以 backtest_trades 行数表示成交数，以 metrics 的 completed_trades 表示闭合交易数， 以 backtest_orders 行数表示委托数；三个概念不得复用同一标签。金额使用 CNY/¥，证券代码统一为 600519.SH 形式。少于 2 天或没有闭合交易时，收益、回撤、Sharpe、胜率与研究判决固定为样本不足； 基准少于 2 根同区间有效日线时不得计算超额结论，并显示缺失原因。
  • 每笔信号、意图、订单与成交记录模拟时间、数据可用时间、最早成交时间、价格来源和拒绝原因。
  • 只有绑定研究协议、样本外结果、成本、流动性和容量检查的结果才可进入 Paper 候选。

10. Paper、盯盘、监控、复盘与实盘工作台

  • Paper 是唯一执行入口，使用隔离账户与模拟撮合；页面不展示真实交易入口。
  • /live、/watch、/monitor 必须使用同一 Paper 账户快照：权益、现金、持仓数量/市值、浮盈、 成交 ID/时间/费用可逐项对账，不允许某页把缺字段回退为 0 后否定另一页的真实持仓。
  • A 股持仓读合同同时返回统一代码和证券名称；持仓卡以名称为主标题、代码为副标题，名称缺失时回退代码。
  • sealed 日线缺少当前持仓标的时，盯盘可只读回退 positions.last_price，但必须显示 paper_position_mark 来源、更新时间和 fallback 状态；不得把回退价冒充实时 tick/L2。
  • 风控发生在订单接受前，并保留通过或拒绝的决策记录。
  • Watch 按策略和股票查看信号、订单、成交、持仓、风险、运行事件与股票池上下文；可配置策略信号、指标、价格和异动四类版本化规则。规则预览只读，只有管理员显式评估才生成站内告警，任何规则都不能创建订单或修改 Paper 账本。
  • Monitor 展示实例生命周期、心跳、最后处理日期、周期结果、异常、权益、回撤、账本差异和数据健康。
  • 运行实例心跳缺失或超过阈值时显示明确告警；响应生成时间不能刷新运行证据。
  • Review 顶部提供当日大盘 Snapshot：指数快照、市场宽度、情绪指标、涨停生态、板块资金与人气榜，全部来自封存/落库的真实数据源（TuShare/AKShare/东财/同花顺），并保留交易日绑定与结论、风险、次日计划编辑。
  • 回测复盘的 24H/7D/30D 窗口分别要求每策略至少 2/5/20 个交易日与权益点、1/3/10 笔闭合交易，并要求数据水位完整。样本健康度以这四项为分母；任一门槛未满足时状态为 insufficient_sample，评分为 null，不进入观察榜或复查榜，页面必须展示真实覆盖、采样点和诊断原因。
  • /live 是当前 Paper-only 模拟入口；数字资产实盘深链和真实券商委托不注册为产品页。旧 /paper 仅重定向到 /live，真实委托需要独立合同、券商通道和 LIVE_TRADING_ENABLED。

11. AI 与 Agent 接口

AI 策略研发闭环（BitPro 式多智能体）

  • 研发任务由 Planner（规格书）→ [Sprint 合约 → Strategist（LLM 生成代码）→ AST 沙箱 → Backtester（quick 诊断回测）→ Evaluator（多维评分）] × N 组成。
  • 生成代码必须通过 StockPro Strategy API v1 静态沙箱；诊断回测复用生产回测链路，不产生晋级证据。
  • 任务与每轮迭代全量落 PostgreSQL（agent_tasks / agent_iterations），服务重启自动恢复未完成任务。
  • 采纳（promote）只把已通过验证的策略版本暴露给策略工作台；不自动创建 Paper、不自动晋级。
  • Evaluator LLM 失败时退化为确定性评分，并在页面明示；未配置 QWEN_API_KEY 时任务快速失败并明示原因。
  • 目标准则（夏普/回撤/胜率/收益/交易数/盈亏比）由用户设定，达标判定只用回测指标，不用 LLM 主观判断。

AI 分析

  • AI 结论必须绑定研究对象、数据日期和可用证据。
  • 未配置 QWEN_API_KEY、Provider 不可用或证据不足时，页面明确显示限制。
  • AI 输出不自动晋级 Paper、不构成投资建议。

Agent

  • 稳定协议为 stockpro-mcp-v1，当前仅提供本地 stdio。
  • Token 仅保存 SHA-256 哈希，明文只在创建时返回一次。
  • 设置中心与 API 以 X-StockPro-MCP-Token / STOCKPRO_MCP_API_TOKEN 为主名称；迁移期仍接受 X-BitPro-MCP-Token / BITPRO_MCP_API_TOKEN，但不得在新 UI 中把旧名标成主配置。
  • R 为读取作用域；W 仅开放合同列出的研究/回测写操作。
  • 写请求需要唯一 Idempotency-Key，并写入审计记录。
  • MCP 不绕过数据来源、新鲜度、快照、权限或真实交易边界。

设置中心

  • AI、Agent Token、访客邀请码和通知配置读取/写入均要求管理员会话；访客返回 403，不返回空成功。
  • AI Provider 身份、Base URL 与 API Key 来源由服务端环境管理，浏览器不接收 Key 明文；模型名称/ 候选可写 PostgreSQL，未开放的 Provider 新增/编辑操作必须禁用而不是请求不存在的接口。
  • 飞书 Webhook 只接受 HTTPS 飞书机器人固定域名和路径，以认证密钥派生的密文存入 PostgreSQL； GET 只返回配置状态和掩码，通知发送器按 env → PostgreSQL → 旧 SQLite 的兼容顺序解析。
  • 模型连接测试使用固定 Provider 端点和服务端凭据，未配置返回 503、外部失败返回 502；响应和日志 不得包含 API Key、完整 Webhook 或 Provider 原始错误正文。

12. UI 合同

  • 所有一级、二级和三级页面使用统一金融操作台主题、组件和设计令牌。
  • 一级侧栏固定、简短、扁平；二级工作区使用下划线式标签，不使用整行按钮导航。
  • 中文优先；工程字段、UUID、数据库主键和哈希不直接暴露在主阅读层。
  • 页面保持紧凑信息密度，不使用营销 Hero、巨大留白、渐变装饰或无业务意义的大卡片。
  • 业务状态、筛选开关和导航必须有不同视觉层级。
  • 所有数据面板覆盖加载、空、过期、错误、部分缺失和权限不足状态。
  • 涨跌配色支持“红涨绿跌”和“绿涨红跌”，零值和缺失值保持中性。

13. 技术与运行边界

  • 前端：React + Vite，http://localhost:4444。
  • 后端：FastAPI，http://localhost:4445。
  • 数据库：本地服务与 ./scripts/check.sh 黄金路径固定使用隔离库 stockpro_bitpro_rebase_dev， 可用 ./scripts/setup_isolation_db.sh 在本机 Docker（127.0.0.1:55432）或已有 Postgres 上创建； start.sh / restart.sh 只连接本机隔离库（优先 127.0.0.1:55432，其次 Unix socket）， 拒绝远程 host、不继承环境里的 DATABASE_URL、不打开 SSH 隧道，并在健康检查后核对实际数据库名。 stockpro_dev / 生产库不得作为本地运行目标。
  • 调度：APScheduler，计划与执行状态持久化到 PostgreSQL。
  • Electron：可选壳层，不是核心产品架构或主要验收入口。
  • 本地 bootstrap、迁移、数据同步、Paper 恢复和数据备份均显式执行；停止或重启服务不得删除 数据库、Paper 历史或 data/local-backups/ 中的已验证备份。
  • 生产 Web 版本只接受 GitHub Actions 从 main 部署，并在迁移、服务重启和健康检查全部成功后记录部署 SHA。
  • 公开 MCP、真实券商接入和实盘订单不在当前产品范围；临时生产数据变更仍需单独明确授权。
  • OKX/Binance 实盘、合约 Paper、funding/arb 策略与 OKX 运维脚本已移出默认产品树（archive/bitpro-crypto/），A 股 Paper 不得导入。

14. 非目标

  • 荐股或收益保证。
  • 自动实盘交易。
  • 公网多租户 SaaS、注册、计费或团队权限系统。
  • 用 mock、随机数或硬编码值填充真实研究页面。
  • 在回测期间从外部 Provider 临时取数。
  • 从非 main 分支部署生产，或绕过健康检查记录部署成功。

15. 完成标准

一个功能切片只有在以下条件满足后才算完成：

  1. 用户可见行为符合产品和 Sprint 合同。
  2. 数据来源、时间、状态和缺失语义正确。
  3. 关键对象保留必要版本与审计证据。
  4. 相关自动化检查或人工验收已执行并记录。
  5. 本地前端、后端和健康检查可用（纯文档修改除外）。
  6. 已知缺口在 docs/progress.md 或对应合同中明确记录。

具体实现与历史验收见 开发进度 和 Sprint 合同。

16. 已批准的 BitPro-first 重建方向与当前 API 事实

2026-08-22 已批准在隔离分支中以 BitPro 完整应用为底座重建 StockPro； 2026-08-26 重开时的固定基线为 2e4b90c3f83672cb9c3fc2e31b772f6c52efacb1。 当前 main 与生产仍以本规格前 15 节为事实；新方向在完成全部验收并获得最终切换确认前， 不得被描述为已上线。

目标系统直接继承 BitPro 的完整页面与交互标准，使用 PostgreSQL 和 A股领域服务替换 SQLite 与数字资产运行时。当前运行路由由 backend/app/main.py 装配：健康检查与 Web 鉴权主入口 保留 /api/health、/api/health/storage、/api/auth/*；鉴权兼容入口同时注册 /api/v2/auth/*；行情、策略、回测、Paper、监控、数据同步、因子、设置、复盘和 AI 研究等业务域 统一在 /api/v2/*。历史文档中的 /api/paper/*、/api/backtest/*、/api/data/* 等旧业务路径不再作为当前合同。未来若要迁移掉 /api/v2，必须另立合同并在同一切片更新前端、 后端、测试和文档。

历史版本字段只作为只读审计证据。完整设计、数据连续性、期货预留和切换门禁见 BitPro-first A股整仓重建设计合同。