# 通知引擎模块（Notification Engine）

> **负责人**: FFOA 开发团队  
> **模块标识**: `notification`  
> **状态**: ✅ 已完成  
> **最后更新**: 2025-12-25

---

## 📋 文档导航

| 文档 | 状态 | 最后更新 |
|------|------|---------|
| [架构设计](./03-architecture.md) | ✅ | 2024-11-15 |

**状态说明**:
- ✅ Completed/Approved - 已完成并通过评审
- 🚧 In Progress/Draft - 编写中
- ❌ Not Started - 未开始
- 📝 Need Update - 需要更新

---

## 📌 概述

通知引擎是 FFOA 平台的核心基础设施，提供统一的多渠道通知服务，支持邮件、Teams、短信等多种通知方式。

### 核心功能

1. **多渠道支持** - Email（已实现）、Teams、SMS、WebSocket、应用内通知（可扩展）
2. **模板化管理** - Handlebars 模板引擎，可视化变量管理
3. **异步发送** - 不阻塞主流程，提升性能
4. **失败重试** - 自动重试机制，确保送达
5. **批量发送** - 支持批量通知发送
6. **日志查询** - 完整的发送日志和统计功能
7. **模板管理** - 模板 CRUD、测试渲染

### 业务价值

- **统一通知**: 全平台统一的通知发送接口
- **高可靠性**: 自动重试、失败处理机制
- **易于扩展**: 适配器模式，轻松添加新渠道
- **模板化**: 统一管理通知模板，提高效率

---

## 🏗️ 技术信息

### 代码位置

- **后端**: `backend/src/notification/`
  - notification.module.ts - 模块定义（全局模块）
  - notification.service.ts - 核心服务
  - notification.controller.ts - API 控制器
  - adapters/email.adapter.ts - 邮件适配器
  - services/template.service.ts - 模板服务
  - dto/notification.dto.ts - DTO 定义
- **数据库**: `NotificationTemplate`, `NotificationLog` 表

### API 端点

- **Base URL**: `/api/v1/notifications`
- **权限前缀**: `notifications:`
- **主要接口**: 
  - 发送通知: POST `/send`
  - 批量发送: POST `/batch`
  - 查询日志: GET `/logs`
  - 重试失败: POST `/:id/retry`
  - 统计信息: GET `/statistics`
  - 模板管理: CRUD 操作（8个接口）
- **总计**: 11个接口

### 技术栈

- **邮件**: Nodemailer
- **模板引擎**: Handlebars
- **队列**: BullMQ
- **数据库**: PostgreSQL + Prisma

### 默认模板

系统预置 4 个默认模板：
- `APPROVAL_TASK_CREATED` - 审批任务创建通知
- `APPROVAL_TASK_APPROVED` - 审批通过通知
- `APPROVAL_TASK_REJECTED` - 审批驳回通知
- `SYSTEM_ALERT` - 系统告警通知

---

## 🔗 相关模块

### 核心依赖

- **PostgreSQL** - 数据存储
- **SMTP 服务器** - 邮件发送

### 被依赖模块

- **所有业务模块** - 都可以使用通知引擎发送通知
- [审批引擎](../approval-engine/README.md) - 审批流程通知
- [工单系统](../tickets/README.md) - 工单状态通知
- [用户反馈](../feedback/README.md) - 反馈处理通知

---

## 🚀 快速开始

### 配置 SMTP

在 `backend/.env` 中配置：

```env
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your-email@gmail.com
SMTP_PASSWORD=your-app-password
SMTP_FROM=FFOA System <noreply@example.com>
```

### 发送简单邮件

```typescript
await notificationService.send({
  channel: 'EMAIL',
  to: 'user@example.com',
  subject: '测试邮件',
  content: '<h1>Hello World</h1>',
});
```

### 使用模板发送

```typescript
await notificationService.send({
  channel: 'EMAIL',
  to: 'user@example.com',
  templateCode: 'APPROVAL_TASK_CREATED',
  variables: {
    approverName: '张三',
    taskName: '报销审批',
    taskUrl: 'https://example.com/approval/123',
    // ... 更多变量
  },
});
```

### 批量发送

```typescript
await notificationService.sendBatch([
  {
    channel: 'EMAIL',
    to: 'user1@example.com',
    subject: '通知1',
    content: '内容1',
  },
  {
    channel: 'EMAIL',
    to: 'user2@example.com',
    subject: '通知2',
    content: '内容2',
  },
]);
```

更多示例详见上方"快速开始"部分

---

## 📊 通知渠道

### 当前支持

- ✅ **Email** - 完整实现，生产就绪

### 可扩展渠道

- 📋 **Teams** - Microsoft Teams 通知
- 📋 **SMS** - 短信通知
- 📋 **WebSocket** - 实时推送
- 📋 **In-App** - 应用内通知

通过实现新的适配器即可扩展新渠道。

---

## 🧪 测试

### 初始化模板

```bash
npm run init:notification-templates
```

### 编译检查

```bash
npm run build
```

### 测试模板渲染

```bash
POST /api/v1/notifications/templates/test-render
{
  "templateCode": "APPROVAL_TASK_CREATED",
  "variables": {
    "approverName": "测试用户",
    "taskName": "测试任务"
  }
}
```

---

## 📚 详细文档

- [架构设计](./03-architecture.md) - 系统架构、数据模型、API设计

---

## 🎯 开发状态

### 已完成功能

- ✅ **邮件发送** - SMTP、HTML/文本、附件
- ✅ **模板管理** - Handlebars 模板、自定义辅助函数
- ✅ **异步处理** - 队列支持、不阻塞主流程
- ✅ **失败重试** - 自动重试机制
- ✅ **日志查询** - 完整的发送日志
- ✅ **统计分析** - 发送统计、成功率分析
- ✅ **批量发送** - 支持批量通知
- ✅ **模板测试** - 渲染测试功能
- ✅ **全局模块** - 可在整个应用中使用

### 系统状态

| 指标 | 状态 |
|------|------|
| **完成度** | ✅ 100% |
| **编译状态** | ✅ 成功 |
| **测试状态** | ✅ 通过 |
| **生产就绪** | ✅ 是 |
| **文档完整度** | ✅ 100% |

---

## 📊 模块统计

| 指标 | 数量 |
|------|------|
| **API 端点** | 11个 |
| **支持渠道** | 1个（Email，更多可扩展） |
| **默认模板** | 4个 |
| **核心服务** | 3个 |
| **适配器** | 1个 |

---

## 🔐 权限控制

通知引擎作为全局服务，权限由调用方控制。

---

## 💡 最佳实践

### 1. 使用模板

推荐使用模板而非硬编码内容，便于统一管理和修改。

### 2. 异步发送

通知发送是异步的，不会阻塞主业务流程。

### 3. 错误处理

通知发送失败会自动重试，业务代码无需处理重试逻辑。

### 4. 变量命名

模板变量使用驼峰命名，如 `approverName`、`taskUrl`。

---

## 👥 贡献者

- **创建者**: FFOA Team
- **维护者**: Backend Team
- **最后更新**: 2025-12-25

---

**创建时间**: 2024-11-15  
**更新时间**: 2025-12-25  
**状态**: ✅ 已完成（v1.0.0）  
**版本**: v1.0.0