# zest-notify

**Repository Path**: zestcc/zest-notify

## Basic Information

- **Project Name**: zest-notify
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-11
- **Last Updated**: 2026-07-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ZestNotify — 统一消息通知中枢

> **通知即服务 (Notification as a Service)** — 将通知能力从业务系统中解耦，提供统一的路由、编排、分发和审计。

---

## 产品定位

ZestNotify 是一个**企业级统一消息通知中枢**，对标 PagerDuty / Opsgenie 的通知编排能力 + 发送通道聚合。核心差异化：

- **多通道聚合**：钉钉、企微、邮件、短信、Webhook、Push — 统一管理，一处配置全局生效
- **智能路由**：按严重度、时段、收件人偏好自动选择最优通道
- **升级策略**：通知未确认 → 自动升级到更高级别通道或负责人
- **排班管理**：时间轮转排班，确保通知触达正确的人
- **全链路可观测**：每条通知的发送/到达/已读/确认全程追踪
- **双模部署**：嵌入模式（Starter）零依赖集成 / 独立服务集中管理

---

## 功能矩阵

| 模块 | 功能 | 状态 |
|------|------|------|
| **渠道管理** | 钉钉机器人 / 企业微信 / 邮件 / 短信 / Webhook / Slack / Push | ✅ v1.0 |
| **通知模板** | FreeMarker 模板引擎 / 变量注入 / 多格式 (Text/Markdown/HTML) | ✅ v1.0 |
| **分发引擎** | 令牌桶限流 / 重试 / 熔断 / 异步批量 | ✅ v1.0 |
| **收件人管理** | 用户组 / ALL / RANDOM / ROUND_ROBIN 策略 | ✅ v1.0 |
| **升级策略** | 时间轮转 / 升级链 / 超时未确认升级 | ✅ v1.0 |
| **静默规则** | 时间窗口 / 周期性 / 关键词匹配 | ✅ v1.0 |
| **排班管理** | 日/周/自定义轮转 / 换班 / 例外 | ✅ v1.0 |
| **通知历史** | 全量审计 / 重新发送 / 导出 / 统计分析 | ✅ v1.0 |
| **健康看板** | 渠道可用性 / 发送成功率 / 延迟分布 | ✅ v1.0 |
| **Webhook 接入** | 外部系统通过 API 接入通知 | ✅ v1.0 |
| **SPI 插件** | 自定义通知通道 / 身份认证 / 事件广播 | ✅ v1.0 |

---

## 架构设计

```
┌─────────────────────────────────────────────────────────┐
│                    业务系统 / 外部系统                     │
│  zest-scheduler  zest-auth  zestflow  zest-monitor  ... │
└──────────────┬──────────────────────────┬──────────────┘
               │ HTTP API                  │ SDK / Starter
               ▼                           ▼
┌─────────────────────────────────────────────────────────┐
│                   ZestNotify Server                       │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐   │
│  │ 渠道管理  │ │ 模板引擎  │ │ 分发引擎  │ │ 升级策略  │   │
│  ├──────────┤ ├──────────┤ ├──────────┤ ├──────────┤   │
│  │ 收件人    │ │ 静默规则  │ │ 排班管理  │ │ 通知历史  │   │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘   │
│                         │                                │
│  ┌──────────────────────┼──────────────────────────┐    │
│  │         Plugin SPI   │  通知通道插件               │    │
│  │  ┌──────┐┌──────┐┌──────┐┌──────┐┌──────┐┌────┐│    │
│  │  │钉钉  ││企微  ││邮件  ││短信  ││Slack ││Push││    │
│  │  └──────┘└──────┘└──────┘└──────┘└──────┘└────┘│    │
│  └──────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────────────────────┐
│  数据层                                                    │
│  MySQL (渠道/模板/历史) | Redis (限流/排班/缓存)          │
└─────────────────────────────────────────────────────────┘
```

### 双模部署

```
嵌入模式 (Starter)
  业务应用引入 zest-notify-spring-boot-starter
  → 自动配置 NotifyDispatchService + 渠道管理
  → 零网络开销，同进程调用
  → 适合单体/小规模

独立模式 (Server)
  部署 zest-notify-server
  → REST API 接收通知请求
  → 集中管理渠道/模板/策略
  → 适合微服务/大规模
```

---

## 快速开始

### 嵌入模式

```xml
<dependency>
    <groupId>com.zestcc.www</groupId>
    <artifactId>zest-notify-spring-boot-starter</artifactId>
    <version>1.0.0</version>
</dependency>
```

```yaml
zest-notify:
  enabled: true
  channel:
    jdbc:
      enabled: true
```

```java
@Autowired
private NotifyDispatchService notifyDispatchService;

// 发送通知
notifyDispatchService.send(NotifyRequest.builder()
    .title("订单异常告警")
    .content("订单 #12345 支付超时")
    .severity("CRITICAL")
    .channelCodes(Arrays.asList("dingtalk-team", "email-ops"))
    .build());
```

### 独立模式

```bash
# 启动服务
java -jar zest-notify-server.jar

# 调用 API
curl -X POST http://localhost:9010/api/v1/notify/send \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "订单异常",
    "content": "订单 #12345 支付超时",
    "severity": "CRITICAL",
    "channelCodes": ["dingtalk-team"]
  }'
```

---

## 模块说明

| 模块 | 说明 |
|------|------|
| `zest-notify-common` | 枚举、DTO、常量、模板引擎（零框架依赖） |
| `zest-notify-plugin-api` | Notifier SPI 接口定义 |
| `zest-notify-core` | 核心领域服务 + 持久层 |
| `zest-notify-server` | Spring Boot 独立服务 |
| `zest-notify-spring-boot-starter` | 嵌入模式自动配置 |
| `zest-notify-client` | Java SDK 客户端 |
| `plugins/` | 通知渠道 SPI 实现 |

---

## 通知通道一览

| 通道 | 类型 | 特性 |
|------|------|------|
| 钉钉机器人 | `DINGTALK_ROBOT` | Markdown / Text + 签名校验 |
| 企业微信机器人 | `WECOM_ROBOT` | Markdown / Text |
| 邮件 | `EMAIL` | HTML / Plain + SMTP / SSL |
| 短信 | `SMS` | 模板短信 / 验证码 |
| Webhook | `WEBHOOK` | POST JSON + Bearer Token |
| Slack | `SLACK` | Block Kit / Message |
| Push | `PUSH` | WebSocket / SSE |

---

## 配置说明

```yaml
zest-notify:
  enabled: true
  server:
    port: 9010
  dispatch:
    rate-limit: 120              # 每分钟最大发送量
    retry-max: 3                  # 失败重试次数
    timeout-ms: 10000             # 发送超时
    batch-size: 50                # 批量发送大小
  channel:
    jdbc:
      enabled: true               # 启用数据库存储
  cache:
    type: caffeine                # caffeine | redis
```

---

## 技术栈

| 层 | 技术 |
|----|------|
| 语言 | Java 17+ |
| 框架 | Spring Boot 3.2.x |
| 持久化 | MyBatis-Plus 3.5.x, MySQL 8.0 |
| 缓存 | Caffeine / Redis (Redisson) |
| 模板 | FreeMarker |
| 调度 | ShedLock |
| JWT | jjwt 0.12.x |
| 前端 | Vue 3.4 + Element Plus 2.7 + Vite 5 |
| 构建 | Maven |
| 部署 | Docker / Kubernetes |

---

## 生态集成

| 项目 | 集成方式 | 用途 |
|------|---------|------|
| zest-scheduler | AlertSPI → Notify API | 任务失败/超时告警 |
| zest-auth | AlertPublisher → Notify API | 安全事件通知 |
| zestflow | ChainGateway → Notify API | 流程异常通知 |
| zest-monitor | 告警引擎 → Notify API | 监控告警分发 |

---

## 开发计划

- [x] v1.0 — 渠道管理 + 模板引擎 + 分发引擎 + 收件人管理
- [x] v1.0 — 升级策略 + 静默规则 + 排班管理
- [x] v1.0 — 通知历史 + 统计看板 + 健康监控
- [x] v1.0 — SPI 插件机制 + 7 种通知通道
- [x] v1.0 — 双模部署 (嵌入 + 独立)
- [ ] v1.1 — 通知确认回执 + 用户偏好
- [ ] v1.2 — AI 智能通知合并 + 通知时段优化
- [ ] v1.3 — 多语言国际化模板

---

## License

Apache License 2.0