# @lark-apaas/nestjs-trigger

为 NestJS 应用提供声明式自动化任务注册与执行能力的核心模块。

基于 TriggerClient 实现，提供 `@Automation`/`@BindTrigger` 装饰器、自动发现机制、REST 触发接口，以及与 trigger-server 的完整集成。

## 功能特性

- 🎯 **声明式 API** - 使用 `@Automation` 和 `@BindTrigger` 装饰器定义自动化任务
- 🔍 **自动发现** - 应用启动时自动扫描并注册所有自动化任务
- 📝 **强类型** - 完整的 TypeScript 类型定义与类型推断
- 🔒 **1:1 绑定** - 强制每个 triggerName 只能绑定一个方法，避免冲突
- 📡 **日志上报** - 集成观测系统，自动上报执行状态
- 📊 **日志跟踪** - 完整的执行生命周期日志记录

## 安装

```bash
npm install @lark-apaas/nestjs-trigger
# 或
yarn add @lark-apaas/nestjs-trigger
```

## 快速开始

### 1. 导入模块

在根模块中导入 `AutomationModule`：

```typescript
import { Module } from '@nestjs/common';
import { AutomationModule } from '@lark-apaas/nestjs-trigger';

@Module({
  imports: [AutomationModule.forRoot()],
})
export class AppModule {}
```

### 2. 定义自动化任务

使用 `@Automation()` 和 `@BindTrigger()` 装饰器定义任务：

```typescript
// xxx.automation.ts
import { Automation, BindTrigger } from '@lark-apaas/nestjs-trigger';

@Automation()
export class MyAutomationService {
  /**
   * 简单的问候任务
   */
  @BindTrigger('task-hello', { 
    actionName: 'HelloTask', 
    actionDesc: 'Print hello message' 
  })
  async hello(name: string) {
    return `Hello, ${name}!`;
  }

  /**
   * 定时任务示例 - 每周五15:00执行
   */
  @BindTrigger('cron1[0 15 * * Fri]', {
    actionName: 'SendWeeklyEmail',
    actionDesc: '每周五15:00发送邮件'
  })
  async sendWeeklyEmail() {
    // 每周五发送邮件逻辑
    return { success: true, sentAt: new Date() };
  }
}
```

### 3. 导入

在 `XXXModule` 中导入 `MyAutomationService`：

```typescript
import { Module } from '@nestjs/common';
import { XController } from './x.controller';
import { MyAutomationService } from './my.automation';

@Module({
  controllers: [XController],
  providers: [MyAutomationService],
})
export class XModule {}
```



## 核心概念

### @Automation()

类装饰器，标记一个类为自动化任务控制器。

```typescript
@Automation()
@Injectable()
export class EmailAutomation {
  // 任务方法定义
}
```

### @BindTrigger()

方法装饰器，将方法绑定到指定的 trigger。

**参数：**

```typescript
@BindTrigger(trigger: string, options?: {
  actionName?: string;    // 任务名称
  actionDesc?: string;    // 任务描述
})
```

**使用示例：**

```typescript
@Automation()
export class NotificationAutomation {
  @BindTrigger('cron1[0 15 * * Fri]', {
    actionName: 'SendWelcomeEmail',
    actionDesc: '每周五15:00发送欢迎邮件'
  })
  async sendWelcomeEmail(userId: string, email: string) {
    // 发送欢迎邮件逻辑
    return { success: true, userId };
  }

  @BindTrigger('process-payment', {
    actionName: 'ProcessPayment',
    actionDesc: 'Process user payment'
  })
  async processPayment(orderId: string, amount: number) {
    // 处理支付逻辑
    return { success: true, orderId, amount };
  }
}
```

**重要特性：**

- **1:1 绑定约束**：每个 trigger 只能绑定一个方法，重复绑定会抛出错误
- **自动注册**：应用启动时自动扫描并注册所有绑定的任务
- **类型安全**：支持完整的 TypeScript 类型推断

## API 参考

### AutomationController

提供 REST API 接口，用于接收 trigger-server 的请求。

**接口详情：**

```http
POST /innerapi/automation/invoke
```

**请求体：**

```typescript
export interface TriggerExecutionDto {
  trigger?: string;
  triggerID?: string;
  triggerType?: string; // cron
  instanceID?: string;
  startAt?: number;
  parameter?: string;
}
```

**响应：**

```json
{
  "code": 200,
  "message": ""
}
```

**状态码说明：**

- `200`: 接收成功，异步执行
- `400`: 缺少必填字段
- `404`: triggerID 未注册
- `500`: 内部错误

## 与 trigger-server 集成

### 集成架构

```
Trigger Server → HTTP POST /innerapi/automation/invoke
                    ↓
         AutomationController
                    ↓
         AutomationService.executeAction()
                    ↓
         TriggerClient.executeAction()
                    ↓
         实际任务方法执行
                    ↓
         TriggerClient.report() → 观测系统
```

## 开发与测试

### 本地开发

```bash
# 安装依赖
yarn install

# 构建
yarn build

```

### 本地调试接口

```bash
# 获取调试列表
curl -X GET /dev/logs/trace/trigger/list?trigger=xx&triggerID=xx

# 获取调试详情
curl -X GET /dev/logs/trace/trigger/:instanceID
```

## 许可证

MIT