# tradehk 类型系统参考

> 返回：[tradehk 文档中心](./README.md)
> 源文件：`client/src/lib/types.ts`、`shared/types.ts`

## 概述

tradehk 使用 TypeScript 强类型系统，所有数据结构都有明确的类型定义。本文档列出所有核心类型，方便开发者理解数据流和接口规范。

---

## 基础类型

### TimeInterval（K线周期）

```typescript
type TimeInterval =
  | '1m' | '3m' | '5m' | '10m' | '15m' | '30m'
  | '1h' | '2h' | '4h' | '6h' | '12h'
  | '1d' | '3d' | '1w' | '1M';
```

**默认周期**：`10m`（10分钟）

---

### Candle（K线数据）

```typescript
interface Candle {
  time: number;    // Unix 时间戳（秒）
  open: number;    // 开盘价
  high: number;    // 最高价
  low: number;     // 最低价
  close: number;   // 收盘价
  volume: number;  // 成交量
}
```

---

### TradingSignal（交易信号）

```typescript
interface TradingSignal {
  id: string;                           // nanoid 唯一 ID
  timestamp: number;                    // 信号时间戳（毫秒）
  symbol: string;                       // 交易对（如 "BTCUSDT"）
  interval: TimeInterval;               // K线周期
  type: 'BUY' | 'SELL';                // 信号方向
  strength: 'STRONG' | 'MODERATE' | 'WEAK'; // 信号强度
  price: number;                        // 信号价格（收盘价）
  indicators: {                         // 当前指标值快照
    ma10?: number;
    ma100?: number;
    ewo?: number;
    macd?: number;
    macdSignal?: number;
    macdHistogram?: number;
    ao?: number;
  };
  reasons: string[];                    // 触发原因列表（中文）
  isActive: boolean;                    // 是否活跃
}
```

---

### IndicatorParams（指标参数配置）

```typescript
interface IndicatorParams {
  // 移动平均线
  maPeriod?: number;            // MA 短期周期（默认10）
  maLongPeriod?: number;        // MA 长期周期（默认100）
  emaPeriods?: number[];        // 叠加显示的 EMA 周期列表（默认[12,26]）

  // MACD
  macdFast?: number;            // MACD 快线周期（默认10）
  macdSlow?: number;            // MACD 慢线周期（默认20）
  macdSignal?: number;          // MACD 信号线周期（默认10）

  // RSI
  rsiPeriod?: number;           // RSI 周期（默认14）
  rsiOverbought?: number;       // RSI 超买线（默认70）
  rsiOversold?: number;         // RSI 超卖线（默认30）

  // KDJ
  kdjPeriod?: number;           // KDJ 周期（默认9）
  kdjKSmooth?: number;          // K 平滑（默认3）
  kdjDSmooth?: number;          // D 平滑（默认3）

  // Stoch
  stochPeriod?: number;         // Stoch 周期（默认14）
  stochSmooth?: number;         // Stoch 平滑（默认3）

  // StochRSI
  stochRsiRsiPeriod?: number;   // StochRSI 的 RSI 周期（默认14）
  stochRsiStochPeriod?: number; // StochRSI 的 Stoch 周期（默认14）
  stochRsiKSmooth?: number;     // K 平滑（默认3）
  stochRsiDSmooth?: number;     // D 平滑（默认3）

  // 布林带
  bollingerPeriod?: number;     // 布林带周期（默认20）
  bollingerStdDev?: number;     // 标准差倍数（默认2）

  // SuperTrend
  superTrendPeriod?: number;    // SuperTrend ATR 周期（默认10）
  superTrendMultiplier?: number; // SuperTrend 倍数（默认3）

  // DMI/ADX
  dmiPeriod?: number;           // DMI 周期（默认14）

  // ATR
  atrPeriod?: number;           // ATR 周期（默认14）

  // MFI
  mfiPeriod?: number;           // MFI 周期（默认14）

  // TTM Squeeze
  ttmBbPeriod?: number;         // 布林带周期（默认20）
  ttmKcPeriod?: number;         // 肯特纳通道周期（默认20）

  // 信号开关
  signalUseRsi?: boolean;       // 是否使用 RSI 评分（默认true）
  signalUseKdj?: boolean;       // 是否使用 KDJ 评分（默认false）
  signalUseStoch?: boolean;     // 是否使用 Stoch 评分（默认false）
  signalUseBollinger?: boolean; // 是否使用布林带评分（默认true）
  signalUseSuperTrend?: boolean; // 是否使用 SuperTrend 评分（默认false）
  signalUseDmi?: boolean;       // 是否使用 DMI 评分（默认false）
}
```

---

### AlertConfig（通知配置）

```typescript
interface AlertConfig {
  enabled: boolean;                    // 通知总开关
  browserNotification: boolean;        // 浏览器通知
  soundAlert: boolean;                 // 声音提醒
  alertOnBuySignal: boolean;           // 买入信号通知
  alertOnSellSignal: boolean;          // 卖出信号通知
  alertOnPriceBreakout: boolean;       // 价格突破通知
  alertOnVolumeContraction: boolean;   // 缩量提醒
  priceBreakoutPercent: number;        // 价格突破阈值（%）
  larkWebhookEnabled: boolean;         // 飞书 Webhook 开关
  larkSignalNotifyMode: 'ewo_only' | 'all_signals'; // 通知模式
  signalLarkThrottleMinutes: number;   // 信号推送频控（分钟）
  ewoTurnRules: EwoTurnAlertRule[];    // EWO 转换规则
}
```

---

### EwoTurnAlertRule（EWO 转换规则）

```typescript
interface EwoTurnAlertRule {
  id: string;                          // 规则 ID（nanoid）
  enabled: boolean;                    // 是否启用
  symbol: string;                      // 交易对（如 "BTCUSDT"）
  interval: TimeInterval;              // K线周期
  direction: EwoTurnDirection;         // 转换方向
}

type EwoTurnDirection = 'red_to_green' | 'green_to_red';
```

---

### TrendBiasConfig（大周期偏向配置）

```typescript
interface TrendBiasConfig {
  enabled: boolean;                    // 是否启用大周期过滤
  interval: '4h' | '12h';             // 大周期 K 线周期
  bias: TrendBias;                     // 当前大周期方向（自动计算）
  lastUpdated: number;                 // 最后更新时间戳
  autoRefreshMinutes: number;          // 自动刷新间隔（分钟）
}

type TrendBias = 'BEARISH' | 'BULLISH' | 'NEUTRAL' | null;
```

---

### UserConfig（用户配置）

```typescript
interface UserConfig {
  timezone: string;                    // 用户时区（如 "Asia/Shanghai"）
  symbolIntervals: Record<string, TimeInterval>; // 每个币对的 K 线周期
  indicatorParams: IndicatorParams;    // 指标参数
  showIndicators: ShowIndicatorsConfig; // 图表显示开关
  alerts: AlertConfig;                 // 通知配置
}
```

---

### ShowIndicatorsConfig（图表显示配置）

```typescript
interface ShowIndicatorsConfig {
  showEwo: boolean;        // 显示 EWO 子图
  showMacd: boolean;       // 显示 MACD 子图
  showAo: boolean;         // 显示 AO 子图
  showRsi: boolean;        // 显示 RSI 子图
  showKdj: boolean;        // 显示 KDJ 子图
  showStoch: boolean;      // 显示 Stoch 子图
  showStochRsi: boolean;   // 显示 StochRSI 子图
  showBollinger: boolean;  // 显示布林带（主图叠加）
  showMfi: boolean;        // 显示 MFI 子图
  showObv: boolean;        // 显示 OBV 子图
  showDmi: boolean;        // 显示 DMI 子图
  showSuperTrend: boolean; // 显示 SuperTrend（主图叠加）
  showAttr: boolean;       // 显示 ATR 子图
  showTtmSqueeze: boolean; // 显示 TTM Squeeze 子图
  showEma: boolean;        // 显示 EMA 叠加线
  showMa: boolean;         // 显示 MA 叠加线
}
```

---

## 数据库类型（shared/types.ts）

### Signal（数据库信号记录）

```typescript
// 对应 MySQL signals 表
interface Signal {
  id: number;              // 自增主键
  userId: number;          // 用户 ID
  symbol: string;          // 交易对
  interval: string;        // K线周期
  direction: 'long' | 'short'; // 信号方向
  strength: 'strong' | 'medium' | 'weak'; // 信号强度
  score: number;           // 信号评分（80/50/30）
  price: number;           // 信号价格
  ewo?: number;            // EWO 值
  macd?: number;           // MACD 值
  macdSignal?: number;     // MACD 信号线值
  macdHist?: number;       // MACD 柱状图值
  ao?: number;             // AO 值
  reasons?: string;        // JSON 字符串，原因列表
  signalAt: number;        // 信号时间戳（毫秒）
  createdAt: Date;         // 创建时间
}
```

---

## 类型常量

### 默认 EWO 监控规则

```typescript
const DEFAULT_EWO_RULE_SYMBOLS = [
  "BTCUSDT", "ETHUSDT", "BNBUSDT", "SOLUSDT", "DOGEUSDT"
];
const DEFAULT_EWO_RULE_INTERVAL: TimeInterval = "10m";
const DEFAULT_EWO_RULE_DIRECTION: EwoTurnDirection = "red_to_green";
```

### 默认信号周期

```typescript
const DEFAULT_SYMBOL_INTERVAL: TimeInterval = "10m";
```

### 缓存限制

```typescript
const CACHE_CANDLE_LIMIT = 300;  // 每对最多缓存300根K线
```

## 相关文档

- [指标引擎详解](./指标引擎详解.md) — 各指标函数签名
- [信号评分引擎](./信号评分引擎.md) — TradingSignal 生成逻辑
- [飞书通知格式规范](./飞书通知格式规范.md) — AlertConfig 使用说明