symbol_blacklist 表说明（代币黑名单）
1. 概述与用途
- 表名：
symbol_blacklist
- 用途：记录未通过相关系数 / Gate1 / Gate2 校验的代币，在配置的有效期（默认 24 小时）内跳过分析，避免重复失败。
2. 表结构（列定义）
| 列名 |
类型 |
约束/说明 |
id |
SERIAL |
主键，自增 |
symbol |
TEXT |
NOT NULL，代币符号（如 SOL/USDC:USDC） |
base_symbol |
TEXT |
NOT NULL，计价/基准币（如 BTC/USDC:USDC） |
failure_reason |
TEXT |
NOT NULL，失败原因（如 correlation / gate1 / gate2） |
corr_4h |
DOUBLE PRECISION |
可选，4h 相关系数 |
cointegration_count |
INTEGER |
可选，协整数量 |
health_passed |
BOOLEAN |
可选，健康检查是否通过 |
blacklisted_at |
TIMESTAMPTZ |
NOT NULL，默认 NOW()，加入黑名单时间 |
expires_at |
TIMESTAMPTZ |
NOT NULL，过期时间 |
created_at |
TIMESTAMPTZ |
默认 NOW()，创建时间 |
3. 唯一约束
- UNIQUE(symbol, base_symbol, failure_reason)
同一 (symbol, base_symbol, failure_reason) 组合只保留一条记录，避免重复插入。
4. 索引
| 索引名 |
列 |
用途 |
idx_blacklist_symbol_expires |
(symbol, base_symbol, expires_at DESC) |
按 symbol/base_symbol 查询未过期黑名单 |
idx_blacklist_expires |
(expires_at) |
按过期时间做批量清理 |
5. 清理函数
- 函数名：
cleanup_expired_blacklist()
- 作用：删除
expires_at < NOW() 的记录，并返回删除行数。
- 调用：由服务端按
BLACKLIST_CLEANUP_INTERVAL（默认 3600 秒）定时调用，或手动执行。
SELECT cleanup_expired_blacklist() AS cnt;
6. 抽样数据示例
以下为从 symbol_blacklist 表抽样的一条真实记录（按 blacklisted_at 取最新一条）：
| 字段 |
值 |
| id |
212 |
| symbol |
SOL/USDC:USDC |
| base_symbol |
BTC/USDC:USDC |
| failure_reason |
gate2 |
| corr_4h |
NULL |
| cointegration_count |
4 |
| health_passed |
False |
| blacklisted_at |
2026-02-17 20:00:58.167100+00:00 |
| expires_at |
2026-02-18 20:00:58.170971+00:00 |
| created_at |
2026-02-17 20:00:58.167100+00:00 |
含义简述：SOL/USDC:USDC 在以 BTC/USDC:USDC 为 base 的校验中因 gate2 未通过被加入黑名单；协整数量为 4，健康检查未通过；在 expires_at 之前该 symbol 会被跳过分析。
7. 相关配置（src/config.py）
| 配置项 |
默认值 |
说明 |
BLACKLIST_TTL_HOURS |
24 |
黑名单有效期（小时） |
BLACKLIST_CACHE_SIZE |
5000 |
黑名单缓存容量 |
BLACKLIST_CLEANUP_INTERVAL |
3600 |
过期记录清理间隔（秒） |
8. DDL 来源
表与索引、清理函数的定义见：database/init_timescaledb.sql（约 489–528 行）。
代码侧读写通过 src.utils.database.timescaledb.BlacklistRepository 与 TimescaleDBClient 完成。