# dingtalk-pusher

**Repository Path**: TTTTTTC/dingtalk-pusher

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-09
- **Last Updated**: 2025-12-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

# 🚀 DingTalk Pusher

**企业级钉钉消息推送中间件**

[![License](https://img.shields.io/badge/license-Apache%202-blue.svg)](LICENSE)
[![JDK](https://img.shields.io/badge/JDK-1.8+-green.svg)](https://www.oracle.com/java/technologies/javase-downloads.html)
[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-2.7.14-brightgreen.svg)](https://spring.io/projects/spring-boot)

[简体中文](README.md) | [English](README_EN.md)

</div>

---

## 📖 项目简介

DingTalk Pusher 是一个企业级的钉钉消息推送中间件，参考阿里巴巴 Druid 项目的模块化架构设计。它提供了灵活的消息推送能力，支持通过 SQL 查询动态生成消息内容，并定时推送到钉钉。

**适用场景：**
- 📊 定时数据报表推送（日报、周报、月报）
- ⚠️ 业务异常告警通知
- 📈 关键指标监控提醒
- 🔔 系统状态通知
- 📝 自动化运营消息

## ✨ 核心特性

- 🎯 **多种使用方式**
  - Spring Boot Starter - 快速集成到现有项目
  - 独立服务部署 - 作为独立中间件运行
  - Web 管理后台 - 可视化配置管理

- 💡 **灵活的消息生成**
  - 支持 SQL 查询动态生成消息
  - 支持消息模板变量替换
  - 支持多数据源查询

- 🔄 **强大的调度能力**
  - 基于 Quartz 的定时调度
  - 支持 CRON 表达式
  - 任务状态实时监控

- 🗄️ **多数据源支持**
  - MySQL、PostgreSQL、Oracle、SQL Server
  - 基于 Druid 连接池
  - 支持动态数据源配置

- 📱 **多种推送方式**
  - 钉钉机器人推送
  - 钉钉工作通知推送
  - 支持单用户/多用户/群组推送

- 🔌 **高度可扩展**
  - SPI 扩展机制
  - 自定义数据源提供者
  - 自定义消息生成器

## 🏗️ 模块架构

```
dingtalk-pusher
├── dingtalk-pusher-core                    # 核心模块 - 消息推送引擎
├── dingtalk-pusher-spring-boot-starter     # Spring Boot Starter - 快速集成
├── dingtalk-pusher-server                  # 独立服务 - 独立部署运行
└── dingtalk-pusher-admin                   # Web管理后台 - 可视化管理界面
```

## 🚀 快速开始

### 方式一：作为 SDK 集成（推荐）

#### 1. 添加依赖

```xml
<dependency>
    <groupId>com.miaoqu</groupId>
    <artifactId>dingtalk-pusher-spring-boot-starter</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>
```

#### 2. 配置文件

在 `application.yml` 中添加配置：

```yaml
dingtalk:
  pusher:
    enabled: true
    
    # 钉钉配置
    dingtalk:
      push-mode: ROBOT  # ROBOT(机器人) 或 WORK_NOTICE(工作通知)
      robot-webhook: https://oapi.dingtalk.com/robot/send?access_token=YOUR_TOKEN
      robot-secret: YOUR_SECRET
    
    # 数据源配置
    datasources:
      - name: primary
        url: jdbc:mysql://localhost:3306/your_database
        username: root
        password: password
        driver-class-name: com.mysql.cj.jdbc.Driver
    

```

#### 3. 启动应用

```java
@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}
```

### 方式二：使用 Web 管理后台

#### 1. 编译项目

```bash
git clone https://github.com/your-username/dingtalk-pusher.git
cd dingtalk-pusher
mvn clean package -DskipTests
```

#### 2. 启动管理后台

```bash
cd dingtalk-pusher-admin/target
java -jar dingtalk-pusher-admin-1.0.0-SNAPSHOT.jar
```

#### 3. 访问管理界面

打开浏览器访问：http://localhost:8080

默认账号：`admin` / `admin123`

#### 4. 在界面中配置

- 配置数据源
- 配置钉钉机器人
- 创建推送任务
- 启动任务

![管理界面](doc/images/2.png)

![任务列表](doc/images/6.png)

![数据源配置](doc/images/1.png)

![钉钉配置](doc/images/3.png)

![任务配置](doc/images/4.png)

![推送日志](doc/images/5.png)

![消息示例](doc/images/7.png)

### 方式三：独立服务部署

```bash
cd dingtalk-pusher-server/target
java -jar dingtalk-pusher-server-1.0.0-SNAPSHOT.jar
```

通过修改 `application.yml` 配置文件来管理任务。

## 📚 使用示例

### 示例 1：每日订单统计推送

```yaml
tasks:
  - name: daily-order-stats
    cron: "0 0 9 * * ?"
    datasource: primary
    sql: |
      SELECT 
        COUNT(*) as total_orders,
        SUM(amount) as total_amount,
        AVG(amount) as avg_amount
      FROM orders 
      WHERE DATE(create_time) = CURDATE()
    message-template: |
      📊 每日订单统计
      ━━━━━━━━━━━━━━━
      订单总数: ${total_orders}
      订单总额: ¥${total_amount}
      平均订单: ¥${avg_amount}
    receivers: ["manager001"]
```

### 示例 2：库存预警

```yaml
tasks:
  - name: inventory-alert
    cron: "0 0 10,16 * * ?"  # 每天10点和16点
    datasource: primary
    sql: |
      SELECT 
        product_name,
        current_stock,
        min_stock
      FROM products 
      WHERE current_stock < min_stock
    message-template: |
      ⚠️ 库存预警
      以下商品库存不足：
      ${product_name}: 当前 ${current_stock}，最低 ${min_stock}
    receivers: ["warehouse001"]
```

### 示例 3：编程式动态任务

```java
@Service
public class CustomTaskService {
    
    @Autowired
    private DingTalkPusherEngine engine;
    
    public void createDynamicTask() {
        TaskConfig task = new TaskConfig();
        task.setName("custom-task");
        task.setCron("0 */5 * * * ?");  // 每5分钟
        task.setDatasource("primary");
        task.setSql("SELECT COUNT(*) as count FROM users WHERE status = 'online'");
        task.setMessageTemplate("在线用户数: ${count}");
        task.setReceivers(Arrays.asList("admin001"));
        
        engine.addTask(task);
    }
    
    public void removeTask() {
        engine.removeTask("custom-task");
    }
}
```

## 📋 CRON 表达式参考

| 表达式 | 说明 |
|--------|------|
| `0 0 9 * * ?` | 每天 9:00 |
| `0 */10 * * * ?` | 每 10 分钟 |
| `0 0 12 * * MON-FRI` | 工作日中午 12:00 |
| `0 0 0 1 * ?` | 每月 1 号 0:00 |
| `0 0 9-18 * * ?` | 每天 9:00-18:00 每小时 |

## 🔧 配置说明

### 钉钉机器人配置

1. 在钉钉群中添加自定义机器人
2. 获取 Webhook 地址和加签密钥
3. 配置到系统中

详见：[钉钉配置指南](docs/DINGTALK_CONFIG.md)

### 数据源配置

支持多种数据库：

```yaml
datasources:
  - name: mysql-db
    url: jdbc:mysql://localhost:3306/db
    username: root
    password: password
    driver-class-name: com.mysql.cj.jdbc.Driver
  
  - name: postgres-db
    url: jdbc:postgresql://localhost:5432/db
    username: postgres
    password: password
    driver-class-name: org.postgresql.Driver
```

详见：[数据库配置指南](docs/DATABASE.md)

## 📖 文档

- [架构设计](docs/ARCHITECTURE.md)
- [使用指南](docs/USAGE.md)
- [管理后台使用](docs/ADMIN.md)
- [钉钉配置](docs/DINGTALK_CONFIG.md)
- [数据库配置](docs/DATABASE.md)
- [会话配置](docs/SESSION_CONFIG.md)
- [分页搜索](docs/PAGINATION_SEARCH.md)
- [故障排查](docs/TROUBLESHOOTING.md)
- [JDK 1.8 兼容性](docs/JDK8_COMPATIBILITY.md)

## 🛠️ 系统要求

- **JDK**: 1.8 或更高版本
- **Maven**: 3.3 或更高版本
- **数据库**（可选）: MySQL 5.7+ / PostgreSQL 9.6+ / Oracle 11g+ / SQL Server 2012+

## 🔌 扩展开发

### 自定义数据源提供者

```java
public class CustomDataSourceProvider implements DataSourceProvider {
    @Override
    public DataSource createDataSource(Map<String, Object> config) {
        // 实现自定义数据源创建逻辑
        return customDataSource;
    }
    
    @Override
    public String getName() {
        return "custom";
    }
}
```

在 `META-INF/services/com.miaoqu.dingtalk.core.spi.DataSourceProvider` 中注册。

### 自定义消息生成器

```java
public class CustomMessageGenerator implements MessageGenerator {
    @Override
    public String generate(Map<String, Object> context) {
        // 实现自定义消息生成逻辑
        return customMessage;
    }
    
    @Override
    public String getType() {
        return "custom";
    }
}
```

## 🤝 贡献指南

欢迎贡献代码、报告问题或提出建议！

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 提交 Pull Request

## 📄 开源协议

本项目采用 [Apache License 2.0](LICENSE) 开源协议。

## 💬 联系方式

- 提交 Issue: [GitHub Issues](https://github.com/your-username/dingtalk-pusher/issues)
- 提交 PR: [Pull Requests](https://github.com/your-username/dingtalk-pusher/pulls)

## 🙏 致谢

- 感谢 [Alibaba Druid](https://github.com/alibaba/druid) 项目提供的架构设计灵感
- 感谢 [Spring Boot](https://spring.io/projects/spring-boot) 提供的优秀框架
- 感谢 [Quartz](http://www.quartz-scheduler.org/) 提供的调度能力

## ⭐ Star History

如果这个项目对你有帮助，请给个 Star ⭐️

---

<div align="center">
Made with ❤️ by DingTalk Pusher Team
</div>