# tradehk 飞书通知格式规范

> 返回：[tradehk 文档中心](./README.md)
> 源文件：`server/_core/marketEngine.ts`、`server/_core/lark.ts`

## 概述

tradehk 通过飞书（Lark）Webhook 推送三类通知：EWO 转换通知、信号通知、定期汇总通知。所有通知均有标题长度限制（120字符）和内容长度限制（4000字符）。

## 通知类型一览

| 类型 | 触发条件 | 开关 | 频控 |
|------|---------|------|------|
| EWO 转换通知 | EWO 颜色转换（已收线确认） | larkWebhookEnabled | 去重（同转换只推一次） |
| 信号通知 | 多指标评分超过阈值 | larkSignalNotifyMode="all_signals" | signalLarkThrottleMinutes（默认10分钟）|
| 定期汇总通知 | 每N小时（默认4小时） | larkWebhookEnabled | 固定间隔 |

---

## 类型一：EWO 转换通知

### 标题格式

```
EWO转换提醒 {币对/周期} {方向}
```

示例：
```
EWO转换提醒 BTC/10m EWO 红 -> 绿
EWO转换提醒 SOL/10m EWO 绿 -> 红
```

### 内容格式

```
触发规则: {方向文字}
币对: {币对/周期}
转换确认: 已收线确认
转换收线: {YYYY/MM/DD HH:mm:ss} ({时区})
EWO: {前值} -> {当前值}
上一阶段: {颜色}({含义})
持续: {时长} ({K线数}根{周期}K)
区间: {开始时间} ~ {结束时间}
当前: {颜色}({含义})
```

### 完整示例（BTC 红→绿）

```
标题：EWO转换提醒 BTC/10m EWO 红 -> 绿

内容：
触发规则: EWO 红 -> 绿
币对: BTC/10m
转换确认: 已收线确认
转换收线: 2026/03/06 10:10:00 (Asia/Shanghai)
EWO: -29.048617 -> 33.320837
上一阶段: 红(空头)
持续: 4小时30分钟 (27根10mK)
区间: 2026/03/06 05:30:00 ~ 2026/03/06 10:00:00
当前: 绿(多头)
```

### 完整示例（SOL 红→绿）

```
标题：EWO转换提醒 SOL/10m EWO 红 -> 绿

内容：
触发规则: EWO 红 -> 绿
币对: SOL/10m
转换确认: 已收线确认
转换收线: 2026/03/06 10:10:00 (Asia/Shanghai)
EWO: -0.037316 -> 0.006745
上一阶段: 红(空头)
持续: 4小时 (24根10mK)
区间: 2026/03/06 06:00:00 ~ 2026/03/06 10:00:00
当前: 绿(多头)
```

---

## 类型二：信号通知

### 标题格式

```
{方向}信号 {币对/周期} {强度代码}
```

强度代码：H（STRONG）/ M（MODERATE）/ L（WEAK）

示例：
```
做多信号 BTC/10m H
做空信号 ETH/4h M
```

### 内容格式

```
类型: {做多/做空} ({long/short})
强度: {H/M/L}
币对: {币对/周期}
时间: {YYYY/MM/DD HH:mm:ss} ({时区})
价格: {价格}
EWO: {值}
MACD: {值}
AO: {值}
Hist: {柱状图值}
依据:
- {原因1}
- {原因2}
...（最多8条）
```

### 完整示例

```
标题：做多信号 BTC/10m H

内容：
类型: 做多 (long)
强度: H
币对: BTC/10m
时间: 2026/03/06 10:10:00 (Asia/Shanghai)
价格: 85234.5
EWO: 33.320837
MACD: 12.456789
AO: 8.234567
Hist: 3.456789
依据:
- EWO 上穿零轴（看多信号）
- MACD 金叉（看多）
- MACD 柱状图扩大（多头增强）
- AO 上穿零轴
- 价格在MA10上方，MA10在MA100上方（多头排列）
- RSI(14)=42.3 超卖区（看多）
```

---

## 类型三：定期汇总通知

### 触发条件

每 N 小时（默认4小时，由 `MARKET_SUMMARY_INTERVAL_HOURS` 环境变量控制）自动推送。

### 内容格式

```
时间: {当前时间} ({时区})
窗口: {开始时间} ~ {结束时间}
币对(N): {币对列表}
图表指标(N): {指标列表}
信号指标(N): {指标列表}
{N}小时信号: 总={总数} 多={多头数} 空={空头数}
分币统计:
- {币对/周期} | 多:{数} 空:{数} | 高频:{原因代码} | 最近:{方向强度@价格}
...
```

---

## 通知配置结构

```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 转换规则列表
}
```

### 通知模式说明

| 模式 | 说明 |
|------|------|
| `ewo_only` | 只推送 EWO 转换通知（默认） |
| `all_signals` | 推送 EWO 转换 + 信号通知 + 定期汇总 |

## 频控机制

### 信号通知频控

```
throttleKey = "signal:{symbol}:{interval}:{buy/sell}"
冷却时间 = signalLarkThrottleMinutes × 60秒
```

同一币对同一方向，在冷却时间内只推送一次。

### EWO 转换去重

```
dedupeKey = "ewo_turn:{symbol}:{interval}:{direction}:{transitionBucketTs}"
```

同一根K线的同方向转换全局只推送一次（跨用户共享去重槽）。

## 环境变量配置

| 变量 | 说明 | 示例 |
|------|------|------|
| `LARK_WEBHOOK_URL` | 飞书 Webhook URL | https://open.feishu.cn/open-apis/bot/v2/hook/xxx |
| `MARKET_ENGINE_POLL_MS` | 引擎轮询间隔（毫秒） | 30000 |
| `MARKET_SUMMARY_INTERVAL_HOURS` | 汇总通知间隔（小时） | 4 |

## 相关文档

- [EWO转换检测机制](./EWO转换检测机制.md) — EWO 通知的检测逻辑
- [系统架构总览](./系统架构总览.md) — 通知在整体架构中的位置
- [部署运维指南](./部署运维指南.md) — 飞书 Webhook 配置方法