create-pardx-scaffold 0.1.0

package/template/apps/api/libs/infra/clients/internal/email/sendcloud.client.ts

@@ -0,0 +1,400 @@
+/**
+ * SendCloud Email Client
+ *
+ * 职责：仅负责与 SendCloud API 通信
+ * - 不访问数据库
+ * - 不包含业务逻辑
+ */
+import { Logger } from 'winston';
+import { HttpService } from '@nestjs/axios';
+import { firstValueFrom } from 'rxjs';
+import * as nodemailer from 'nodemailer';
+import smtpPool from 'nodemailer-sendcloud-transport';
+import * as _ from 'lodash';
+import { PardxEmailSender } from './dto/email.dto';
+import { SendCloudConfig } from '@/config/validation';
+
+// SendCloud API endpoints
+const SENDCLOUD_API = {
+  send: 'https://api.sendcloud.net/apiv2/mail/send',
+  send_template: 'https://api.sendcloud.net/apiv2/mail/sendtemplate',
+  list_get: 'https://api.sendcloud.net/apiv2/addresslist/list',
+  list_create: 'https://api.sendcloud.net/apiv2/addresslist/add',
+  list_update: 'https://api.sendcloud.net/apiv2/addresslist/update',
+  list_delete: 'https://api.sendcloud.net/apiv2/addresslist/delete',
+  member_get: 'https://api.sendcloud.net/apiv2/addressmember/get',
+  member_add: 'https://api.sendcloud.net/apiv2/addressmember/add',
+  member_update: 'https://api.sendcloud.net/apiv2/addressmember/update',
+  member_delete: 'https://api.sendcloud.net/apiv2/addressmember/delete',
+};
+
+interface SendOptions {
+  [key: string]: any;
+}
+
+interface EmailListOptions {
+  start?: number;
+  limit?: number;
+}
+
+interface CreateEmailListOptions {
+  address: string;
+  name: string;
+  description?: string;
+}
+
+interface UpdateEmailListOptions {
+  toAddress?: string;
+  name?: string;
+  description?: string;
+  address?: string;
+}
+
+interface UpdateListMemberOptions {
+  name?: string;
+  vars?: Record<string, any>;
+}
+
+export class SendCloudClient {
+  private transporter: nodemailer.Transporter;
+  private from: string;
+  private fromName: string;
+
+  constructor(
+    private readonly config: SendCloudConfig,
+    private readonly httpService: HttpService,
+    private readonly logger: Logger,
+  ) {
+    this.from = 'no-reply@' + config.domain;
+    this.fromName = config.name;
+
+    this.transporter = nodemailer.createTransport(
+      smtpPool({
+        auth: {
+          apiUser: config.apiUser,
+          apiKey: config.apiKey,
+        },
+      }),
+    );
+  }
+
+  /**
+   * 通用 POST 请求方法
+   */
+  private async postData(url: string, data: any): Promise<any> {
+    data.apiKey = this.config.apiKey;
+    data.apiUser = this.config.apiUser;
+    try {
+      const response = await firstValueFrom(this.httpService.post(url, data));
+      return response.data;
+    } catch (error) {
+      this.logger.error(`SendCloud API error: ${url}`, {
+        error: error.message,
+      });
+      throw error;
+    }
+  }
+
+  // ==================== Email Sending ====================
+
+  /**
+   * HTTP请求的方式发送Email
+   * @param to 收件人地址. 多个地址使用';'分隔
+   * @param subject 标题. 不能为空
+   * @param html 邮件的内容
+   * @param options 可选的参数
+   */
+  async send(
+    to: string,
+    subject: string,
+    html: string,
+    options?: SendOptions,
+  ): Promise<any> {
+    if (!to || !subject || !html) {
+      throw new Error('The params is missed!');
+    }
+    const data: any = {
+      apiUser: this.config.apiUser,
+      apiKey: this.config.apiKey,
+      from: this.from,
+      fromName: this.fromName,
+      to: to,
+      subject: subject,
+      html: html,
+    };
+
+    const finalData = _.assign({}, data, _.cloneDeep(options));
+
+    try {
+      const response = await firstValueFrom(
+        this.httpService.post(SENDCLOUD_API.send, finalData),
+      );
+      return response.data;
+    } catch (err) {
+      throw new Error('邮件发送失败: ' + err.message);
+    }
+  }
+
+  /**
+   * 使用 smtp 的方式发送邮件
+   */
+  async sendEmailSmtp(to: string, subject: string, data: string): Promise<any> {
+    try {
+      const mail = {
+        from: this.from,
+        fromName: this.fromName,
+        to: to || [],
+        subject: subject,
+        html: data,
+      };
+      const info = await new Promise((resolve, reject) => {
+        this.transporter.sendMail(mail, (err, info) => {
+          if (err) {
+            reject(new Error('邮件发送失败: ' + err.message));
+          } else {
+            resolve(info);
+          }
+        });
+      });
+      return info;
+    } catch (error) {
+      throw new Error('邮件发送过程中发生错误: ' + error.message);
+    }
+  }
+
+  /**
+   * 使用触发账号，发送邮件给某一个用户
+   */
+  async sendTemplateToOne(
+    to: string,
+    subject: string,
+    templateName: string,
+    sub: any,
+    options?: SendOptions,
+  ): Promise<any> {
+    try {
+      const data: any = {
+        apiUser: this.config.apiUser,
+        apiKey: this.config.apiKey,
+        from: this.from,
+        fromName: this.fromName,
+        templateInvokeName: templateName,
+        subject: subject,
+        xsmtpapi: JSON.stringify({
+          to: [to],
+          sub: sub || {},
+        }),
+      };
+      if (options) {
+        _.merge(data, options);
+      }
+      const response = await firstValueFrom(
+        this.httpService.post(SENDCLOUD_API.send_template, data, {
+          headers: {
+            'Content-Type': 'multipart/form-data',
+          },
+        }),
+      );
+
+      this.logger.info(`SendCloud email sent to ${to}`, {
+        template: templateName,
+        statusCode: response.data?.statusCode,
+      });
+
+      return response.data;
+    } catch (error) {
+      this.logger.error(`SendCloud email failed to ${to}`, {
+        template: templateName,
+        error: error.message,
+      });
+      throw new Error('发送模板邮件失败: ' + error.message);
+    }
+  }
+
+  /**
+   * 根据模板发送邮件
+   */
+  async sendByTemplate(
+    to: string[],
+    subject: string,
+    templateName: string,
+    sub: Record<string, any> = {},
+    options: SendOptions = {},
+  ): Promise<any> {
+    const data = {
+      apiUser: this.config.apiUser,
+      apiKey: this.config.apiKey,
+      from: this.from,
+      fromName: this.fromName,
+      templateInvokeName: templateName,
+      subject: subject,
+      xsmtpapi: JSON.stringify({
+        to: to,
+        sub: sub,
+      }),
+      ...options,
+    };
+
+    try {
+      const response = await firstValueFrom(
+        this.httpService.post(SENDCLOUD_API.send_template, data),
+      );
+      return response.data;
+    } catch (err) {
+      throw err;
+    }
+  }
+
+  /**
+   * 利用邮件模板给maillist中的用户发送邮件
+   */
+  async sendByMailList(
+    to: string,
+    subject: string,
+    templateName: string,
+    options: SendOptions = {},
+  ): Promise<any> {
+    const data = {
+      apiUser: this.config.apiUser,
+      apiKey: this.config.apiKey,
+      from: this.from,
+      fromName: this.fromName,
+      templateInvokeName: templateName,
+      subject: subject,
+      useAddressList: 'true',
+      to: to,
+      ...options,
+    };
+    try {
+      const response = await firstValueFrom(
+        this.httpService.post(SENDCLOUD_API.send_template, data),
+      );
+      return response.data;
+    } catch (err) {
+      throw err;
+    }
+  }
+
+  // ==================== Email List Management ====================
+
+  /**
+   * 获取邮件列表
+   */
+  async getEmailList(options: EmailListOptions = {}): Promise<any> {
+    return this.postData(SENDCLOUD_API.list_get, options);
+  }
+
+  /**
+   * 创建邮件列表
+   */
+  async createEmailList(options: CreateEmailListOptions): Promise<any> {
+    return this.postData(SENDCLOUD_API.list_create, options);
+  }
+
+  /**
+   * 更新邮件列表
+   */
+  async updateEmailList(
+    address: string,
+    options: UpdateEmailListOptions = {},
+  ): Promise<any> {
+    const data = { ...options, address };
+    return this.postData(SENDCLOUD_API.list_update, data);
+  }
+
+  // ==================== List Member Management ====================
+
+  /**
+   * 获取邮件列表成员
+   */
+  async getListMember(
+    mailListAddr: string,
+    options: EmailListOptions = {},
+  ): Promise<any> {
+    const data = { ...options, mail_list_addr: mailListAddr };
+    return this.postData(SENDCLOUD_API.member_get, data);
+  }
+
+  /**
+   * 添加邮件列表成员
+   */
+  async addListMember(
+    mailListAddr: string,
+    memberAddr: string,
+    name: string,
+    options: UpdateListMemberOptions = {},
+  ): Promise<any> {
+    const data: any = {
+      mail_list_addr: mailListAddr,
+      member_addr: memberAddr,
+      name: name,
+      ...options,
+    };
+    if (data.vars) {
+      data.vars = JSON.stringify(data.vars);
+    }
+    return this.postData(SENDCLOUD_API.member_add, data);
+  }
+
+  /**
+   * 更新邮件列表成员
+   */
+  async updateListMember(
+    mailListAddr: string,
+    memberAddr: string,
+    name: string,
+    options: UpdateListMemberOptions = {},
+  ): Promise<any> {
+    const data: any = {
+      mail_list_addr: mailListAddr,
+      member_addr: memberAddr,
+      name: name,
+      ...options,
+    };
+    if (data.vars) {
+      data.vars = JSON.stringify(data.vars);
+    }
+    return this.postData(SENDCLOUD_API.member_update, data);
+  }
+
+  /**
+   * 删除邮件列表成员
+   */
+  async deleteListMember(
+    mailListAddr: string,
+    memberAddr: string[],
+  ): Promise<any> {
+    return this.postData(SENDCLOUD_API.member_delete, {
+      mail_list_addr: mailListAddr,
+      member_addr: memberAddr.join(';'),
+    });
+  }
+
+  /**
+   * 复制成员到另一个列表
+   */
+  async addToOtherList(sourceList: string, targetList: string): Promise<any[]> {
+    const limitOptions = {
+      start: 0,
+      limit: 1000,
+    };
+    try {
+      const data = await this.getListMember(sourceList, limitOptions);
+      const wantList = data.members;
+      const promises = wantList.map((member: any) => {
+        const _name = member.vars['%name%'];
+        const options = {
+          vars: {
+            domain: member.vars['%domain%'],
+            avatar: member.vars['%avatar%'],
+          },
+        };
+        return this.addListMember(targetList, member.address, _name, options);
+      });
+      return Promise.all(promises);
+    } catch (err) {
+      this.logger.error('addToOtherList failed', { error: err.message });
+      throw err;
+    }
+  }
+}

package/template/apps/api/libs/infra/clients/internal/file-cdn/README.md

@@ -0,0 +1,255 @@
+# File CDN 客户端
+
+CDN URL 生成服务模块，支持多种 CDN 供应商和 URL 类型。
+
+## 目录结构
+
+```
+file-cdn/
+├── index.ts                    # 模块导出入口
+├── file-cdn.module.ts          # NestJS 模块配置
+├── file-cdn.client.ts          # CDN 客户端实现
+├── dto/
+│   └── file-cdn.dto.ts         # 类型定义
+└── README.md                   # 本文档
+```
+
+## 支持的 CDN 类型
+
+| 类型 | 方法 | 说明 |
+|------|------|------|
+| 图片 CDN (火山引擎) | `getImageVolcengineCdn` | 支持图片处理模板 |
+| 图片 CDN (CloudFlare) | `getImageCloudFlareCdnUrl` | 支持图片优化 |
+| 视频 CDN | `getVodUrl` | 视频点播 URL |
+| 下载 CDN | `getDownloaderUrl` | 文件下载 URL |
+
+## 快速开始
+
+### 1. 导入模块
+
+```typescript
+import { Module } from '@nestjs/common';
+import { FileCdnModule } from '@app/clients/internal/file-cdn';
+
+@Module({
+  imports: [FileCdnModule],
+})
+export class ImageModule {}
+```
+
+### 2. 注入使用
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { FileCdnClient } from '@app/clients/internal/file-cdn';
+import { FileBucketVendor } from '@prisma/client';
+
+@Injectable()
+export class ImageService {
+  constructor(private readonly cdnClient: FileCdnClient) {}
+
+  /**
+   * 获取图片缩略图 URL
+   */
+  async getThumbnailUrl(
+    vendor: FileBucketVendor,
+    bucket: string,
+    key: string,
+  ) {
+    return await this.cdnClient.getImageVolcengineCdn(
+      vendor,
+      bucket,
+      key,
+      'mini',
+    );
+  }
+
+  /**
+   * 获取视频播放 URL
+   */
+  async getVideoUrl(
+    vendor: FileBucketVendor,
+    bucket: string,
+    key: string,
+  ) {
+    return await this.cdnClient.getVodUrl(vendor, bucket, key);
+  }
+}
+```
+
+## API 参考
+
+### FileCdnClient
+
+#### `getDownloaderUrl(vendor, bucket, key)`
+
+生成文件下载 CDN URL。
+
+```typescript
+const url = await cdnClient.getDownloaderUrl('oss', 'my-bucket', 'files/doc.pdf');
+```
+
+#### `getVodUrl(vendor, bucket, key)`
+
+生成视频点播 CDN URL。
+
+```typescript
+const url = await cdnClient.getVodUrl('tos', 'video-bucket', 'videos/movie.mp4');
+```
+
+#### `getImageVolcengineCdn(vendor, bucket, key, templateId?)`
+
+生成火山引擎图片 CDN URL。
+
+**参数：**
+- `vendor` - 存储供应商
+- `bucket` - 存储桶名称
+- `key` - 图片文件键
+- `templateId` - 图片模板（可选）
+
+**支持的模板：**
+| 模板 ID | 说明 |
+|---------|------|
+| `origin` | 原图预览 |
+| `preview` | 预览图 |
+| `mini` | 缩略图 |
+| `183:103:360:360` | 自定义尺寸（默认） |
+
+```typescript
+// 获取缩略图
+const miniUrl = await cdnClient.getImageVolcengineCdn(
+  'tos',
+  'image-bucket',
+  'images/photo.jpg',
+  'mini',
+);
+
+// 获取自定义尺寸
+const customUrl = await cdnClient.getImageVolcengineCdn(
+  'tos',
+  'image-bucket',
+  'images/photo.jpg',
+  '640:480:640:480',
+);
+```
+
+#### `getImageCloudFlareCdnUrl(vendor, bucket, key, templateId?)`
+
+生成 CloudFlare 图片 CDN URL。
+
+**支持的模板：**
+| 模板 ID | 转换后 |
+|---------|--------|
+| `360:360:360:360` | `width=360,height=360,fit=crop` |
+| `183:103:360:360` | `width=320,height=180,fit=crop` |
+| `origin` | `fit=contain` |
+| `mini` | `width=360,height=360,fit=contain` |
+
+```typescript
+const url = await cdnClient.getImageCloudFlareCdnUrl(
+  'oss',
+  'image-bucket',
+  'images/photo.jpg',
+  'mini',
+);
+```
+
+#### `getCdnOriginImages(...)`
+
+获取原始 CDN 图片（带签名验证），用于 CDN 回源。
+
+```typescript
+const response = await cdnClient.getCdnOriginImages(
+  vendor,
+  bucket,
+  key,
+  auth,
+  expireIn,
+  signature,
+  signedHeaders,
+  signedId,
+  templateId,
+);
+
+if (response.code === 200) {
+  console.log('Origin URL:', response.url);
+} else {
+  console.error('Access denied:', response.message);
+}
+```
+
+## 配置
+
+### CDN 配置
+
+在 `config.yaml` 中配置 CDN：
+
+```yaml
+cdn:
+  cn:
+    url: https://cdn.example.com
+    downloaderUrl: https://download.example.com
+    vodUrl: https://vod.example.com
+    thumbTemplate: default
+  us:
+    url: https://cdn-us.example.com
+    downloaderUrl: https://download-us.example.com
+    vodUrl: https://vod-us.example.com
+    thumbTemplate: default
+```
+
+## 类型定义
+
+```typescript
+// CDN URL 响应
+interface CdnUrlResponse {
+  code: number;      // 200 = 成功, 403 = 禁止
+  message: string;   // 响应消息
+  url: string;       // CDN URL
+}
+
+// 图片模板类型
+type ImageTemplateId = 'origin' | 'preview' | 'mini' | string;
+
+// CloudFlare 模板类型
+type CloudFlareTemplate = '360:360:360:360' | '183:103:360:360' | 'origin' | 'mini' | string;
+
+// 签名 URL 参数
+interface SignedUrlParams {
+  auth?: string;
+  expireIn?: string | number;
+  signature?: string;
+  signedHeaders?: string;
+  signedId?: string;
+  templateId?: string;
+}
+```
+
+## 安全特性
+
+### URL 签名
+
+所有私有文件的 CDN URL 都会自动添加 AWS 签名 V4 认证：
+
+- `X-Amz-Algorithm`: 签名算法
+- `X-Amz-Credential`: 加密凭证
+- `X-Amz-Expires`: 过期时间（默认 30 天）
+- `X-Amz-Signature`: 签名哈希
+- `X-Amz-SignedHeaders`: 签名头
+
+### 签名验证
+
+`getCdnOriginImages` 方法会验证传入的签名参数，确保：
+1. 签名哈希正确
+2. 加密的 key 匹配
+3. 模板 ID 匹配
+
+## 更新日志
+
+### v2.0.0 (重构版本)
+
+- 提取常量到模块顶部
+- 添加完整的 TypeScript 类型定义
+- 添加详细的 JSDoc 文档注释
+- 重构辅助方法，减少代码重复
+- 添加 README 文档