KuCoin Spread Monitor Architecture

用于规划或实现一个独立的 kucoin-spread-monitor 项目。该项目的目标是从现有交易主程序中抽离公有行情订阅与期现价差计算能力，避免继续和主程序共用目录、共用模块。

触发条件

当用户有以下任一诉求时使用本 skill：

• 要把 kucoin_spread_recorder.py 独立拆成单独项目
• 要部署期现价差监控到服务器
• 要支持配置文件热更新跟踪 symbol
• 要把最近 10 天价差写入 PostgreSQL 或 TimescaleDB
• 要在 Grafana 展示开仓价差、平仓价差、分位数、均值、极值
• 要设计数据库表结构、看板、部署方式

首先读取的源文件

优先读取当前项目中的以下文件：

• kucoin_spread_recorder.py
• KuCoinPublicWSManager.py

关注这些现有能力：

• 合约 symbol 归一化
• 现货 symbol 推导
• KuCoin spot/futures 公有 websocket 订阅
• 开仓价差、平仓价差计算
• 自动重连
• 当前 Excel 中已有的统计字段

不要复用以下内容：

• 交易下单
• 风控执行
• Excel 写入
• openpyxl 图表
• 与主程序主循环强耦合的逻辑

输出要求

默认输出 4 份内容：

1. 独立项目技术方案
2. 数据表结构
3. Grafana 面板清单
4. 部署拓扑图

具体内容必须覆盖：

• 独立项目目录结构
• 模块职责
• 数据流
• 热更新机制
• 10 天保留策略
• 重启续写方案
• PostgreSQL 或 TimescaleDB 表结构
• Grafana 总览页与详情页
• 服务器部署方式

方案约束

• 默认按独立项目设计，不与交易主程序共用代码目录
• 默认使用 PostgreSQL 5432；若用户明确支持 TimescaleDB，优先按 TimescaleDB 设计
• 默认使用 Grafana 直连 PostgreSQL/TimescaleDB
• 默认保留最近 10 天数据
• 默认支持配置文件 yaml
• 默认服务端持续运行
• 默认需要处理意外退出后的续写
• 默认用 UTC 处理和存储所有时间字段
• Grafana 负责本地时区展示
• 原始快照落库频率必须做成配置项，不能写死
• 默认要求数据库批量写入
• config_reload_sec 默认不低于 10 秒
• websocket 重连默认要求指数退避
• 未启用 TimescaleDB 时，分位数统计窗口必须支持降级为 1 天或 3 天

推荐架构

使用以下模块划分：

• config_loader: 加载 settings.yaml 和 symbols.yaml
• hot_reload: 监听配置文件变化，增删订阅 symbol
• symbol_mapper: 负责 futures/spot 映射与标准化
• ws_client: 负责 KuCoin 公有 websocket 连接、订阅、重连
• spread_service: 计算开仓价差和平仓价差
• storage_pg: 写入原始快照和统计快照
• aggregator: 生成滚动统计
• retention_job: 清理 10 天前旧数据
• api_health: 可选，暴露健康检查

设计原则

• 高频接收，低频落库，不要把每次盘口变化都直接写数据库
• 原始明细和统计快照分表存储
• 查询展示和写入链路解耦
• Grafana 优先展示决策信息，不照搬 Excel 页面布局
• 10 天趋势展示窗口和分位数统计窗口允许分离配置
• 标准 PostgreSQL 场景下优先采用较低落库频率和较短统计窗口

推荐交付结构

如果用户要生成独立项目骨架，建议使用：

• references/technical-plan.md
• references/schema.sql.md
• references/grafana-panels.md
• references/deployment-topology.md

读取顺序：

1. 先读 references/technical-plan.md
2. 若要落数据库，再读 references/schema.sql.md
3. 若要设计看板，再读 references/grafana-panels.md
4. 若要部署，再读 references/deployment-topology.md

交付风格

• 用中文说明
• 结构化输出
• 优先可执行方案
• 明确哪些内容来自当前项目，哪些是新项目新增能力
• 明确需要用户确认的环境变量、数据库账号、Grafana 地址