@svton/cli 1.2.1 → 1.2.2

package/templates/examples/payment/README.md

@@ -0,0 +1,151 @@
+# 支付功能示例
+
+本示例展示如何使用 `@svton/nestjs-payment` 模块集成微信支付和支付宝。
+
+## 文件说明
+
+- `order.service.ts` - 订单服务，创建支付订单
+- `order.controller.ts` - 订单控制器，提供支付接口
+- `webhook.controller.ts` - 支付回调处理
+
+## 支持的支付方式
+
+### 微信支付
+- JSAPI 支付（公众号/小程序）
+- Native 支付（扫码支付）
+- APP 支付
+- H5 支付
+- 小程序支付
+
+### 支付宝
+- 电脑网站支付（PC）
+- 手机网站支付（H5）
+- APP 支付
+
+## 使用方式
+
+### 1. 创建支付订单
+
+```typescript
+// 微信 JSAPI 支付
+const result = await this.paymentService.wechat.createOrder({
+  outTradeNo: orderId,
+  totalAmount: amount,
+  description: '商品购买',
+  userId: openid,
+}, 'jsapi');
+
+// 支付宝电脑网站支付
+const result = await this.paymentService.alipay.createOrder({
+  outTradeNo: orderId,
+  totalAmount: amount,
+  description: '商品购买',
+}, 'page');
+```
+
+### 2. 查询订单状态
+
+```typescript
+const status = await this.paymentService.wechat.queryOrder(outTradeNo);
+```
+
+### 3. 申请退款
+
+```typescript
+const refund = await this.paymentService.wechat.refund({
+  outTradeNo: orderId,
+  outRefundNo: refundId,
+  refundAmount: amount,
+  totalAmount: totalAmount,
+});
+```
+
+### 4. 处理支付回调
+
+```typescript
+@Post('webhook/wechat')
+async wechatWebhook(@Req() req: Request) {
+  const result = await this.paymentService.wechat.handleNotify(req);
+  // 处理支付成功逻辑
+  return { code: 'SUCCESS', message: '成功' };
+}
+```
+
+## 测试接口
+
+```bash
+# 创建微信 JSAPI 支付订单
+curl -X POST http://localhost:3000/examples/orders/wechat/jsapi \
+  -H "Content-Type: application/json" \
+  -d '{
+    "orderId": "ORDER_001",
+    "amount": 100,
+    "openid": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o"
+  }'
+
+# 创建微信 Native 支付订单（扫码支付）
+curl -X POST http://localhost:3000/examples/orders/wechat/native \
+  -H "Content-Type: application/json" \
+  -d '{
+    "orderId": "ORDER_002",
+    "amount": 100
+  }'
+
+# 创建支付宝电脑网站支付订单
+curl -X POST http://localhost:3000/examples/orders/alipay/page \
+  -H "Content-Type: application/json" \
+  -d '{
+    "orderId": "ORDER_003",
+    "amount": 100
+  }'
+
+# 查询订单状态
+curl http://localhost:3000/examples/orders/ORDER_001/status
+
+# 申请退款
+curl -X POST http://localhost:3000/examples/orders/ORDER_001/refund \
+  -H "Content-Type: application/json" \
+  -d '{
+    "refundId": "REFUND_001",
+    "amount": 100,
+    "reason": "用户申请退款"
+  }'
+```
+
+## 环境变量配置
+
+在 `.env` 文件中配置：
+
+```env
+# 微信支付
+WECHAT_MCH_ID=商户号
+WECHAT_PRIVATE_KEY=./certs/apiclient_key.pem
+WECHAT_SERIAL_NO=证书序列号
+WECHAT_API_V3_KEY=APIv3密钥
+WECHAT_APP_ID=关联的AppID
+
+# 支付宝
+ALIPAY_APP_ID=应用ID
+ALIPAY_PRIVATE_KEY=./certs/alipay_private_key.pem
+ALIPAY_PUBLIC_KEY=./certs/alipay_public_key.pem
+```
+
+## 最佳实践
+
+1. **订单号唯一性**：确保 outTradeNo 全局唯一
+2. **金额单位**：统一使用分为单位
+3. **回调幂等性**：支付回调可能重复，需要幂等处理
+4. **异步通知**：优先使用异步通知，不依赖同步返回
+5. **安全验证**：验证回调签名，防止伪造
+6. **错误处理**：妥善处理支付失败、超时等异常情况
+
+## 回调地址配置
+
+需要在微信支付和支付宝后台配置回调地址：
+
+- 微信支付：`https://yourdomain.com/examples/webhooks/wechat`
+- 支付宝：`https://yourdomain.com/examples/webhooks/alipay`
+
+## 更多信息
+
+查看官方文档：https://751848178.github.io/svton/packages/nestjs-payment

package/templates/examples/payment/order.controller.ts

@@ -0,0 +1,56 @@
+import { Controller, Post, Get, Body, Param, Query } from '@nestjs/common';
+import { OrderService } from './order.service';
+
+@Controller('examples/orders')
+export class OrderController {
+  constructor(private readonly orderService: OrderService) {}
+
+  @Post('wechat/jsapi')
+  async createWechatJsapiOrder(
+    @Body() data: { orderId: string; amount: number; openid: string },
+  ) {
+    return this.orderService.createWechatJsapiOrder(
+      data.orderId,
+      data.amount,
+      data.openid,
+    );
+  }
+
+  @Post('wechat/native')
+  async createWechatNativeOrder(
+    @Body() data: { orderId: string; amount: number },
+  ) {
+    return this.orderService.createWechatNativeOrder(
+      data.orderId,
+      data.amount,
+    );
+  }
+
+  @Post('alipay/page')
+  async createAlipayPageOrder(
+    @Body() data: { orderId: string; amount: number },
+  ) {
+    return this.orderService.createAlipayPageOrder(
+      data.orderId,
+      data.amount,
+    );
+  }
+
+  @Get(':orderId/status')
+  async queryOrderStatus(@Param('orderId') orderId: string) {
+    return this.orderService.queryOrderStatus(orderId);
+  }
+
+  @Post(':orderId/refund')
+  async refundOrder(
+    @Param('orderId') orderId: string,
+    @Body() data: { refundId: string; amount: number; reason?: string },
+  ) {
+    return this.orderService.refundOrder(
+      orderId,
+      data.refundId,
+      data.amount,
+      data.reason,
+    );
+  }
+}

package/templates/examples/payment/order.service.ts

@@ -0,0 +1,132 @@
+import { Injectable } from '@nestjs/common';
+import { PaymentService } from '@svton/nestjs-payment';
+
+@Injectable()
+export class OrderService {
+  constructor(private readonly paymentService: PaymentService) {}
+
+  /**
+   * 创建微信 JSAPI 支付订单（公众号/小程序）
+   */
+  async createWechatJsapiOrder(
+    orderId: string,
+    amount: number,
+    openid: string,
+  ) {
+    const result = await this.paymentService.wechat.createOrder(
+      {
+        outTradeNo: orderId,
+        totalAmount: amount,
+        description: '商品购买',
+        userId: openid,
+      },
+      'jsapi',
+    );
+
+    return {
+      orderId,
+      paymentData: result,
+    };
+  }
+
+  /**
+   * 创建微信 Native 支付订单（扫码支付）
+   */
+  async createWechatNativeOrder(orderId: string, amount: number) {
+    const result = await this.paymentService.wechat.createOrder(
+      {
+        outTradeNo: orderId,
+        totalAmount: amount,
+        description: '商品购买',
+      },
+      'native',
+    );
+
+    return {
+      orderId,
+      qrCode: result.code_url, // 二维码链接
+    };
+  }
+
+  /**
+   * 创建支付宝电脑网站支付订单
+   */
+  async createAlipayPageOrder(orderId: string, amount: number) {
+    const result = await this.paymentService.alipay.createOrder(
+      {
+        outTradeNo: orderId,
+        totalAmount: amount,
+        description: '商品购买',
+      },
+      'page',
+    );
+
+    return {
+      orderId,
+      paymentUrl: result, // 支付页面 URL
+    };
+  }
+
+  /**
+   * 查询订单状态
+   */
+  async queryOrderStatus(orderId: string) {
+    try {
+      // 先尝试查询微信支付
+      const wechatStatus = await this.paymentService.wechat.queryOrder(orderId);
+      return {
+        orderId,
+        provider: 'wechat',
+        status: wechatStatus.trade_state,
+        data: wechatStatus,
+      };
+    } catch (wechatError) {
+      // 如果微信查询失败，尝试支付宝
+      try {
+        const alipayStatus = await this.paymentService.alipay.queryOrder(orderId);
+        return {
+          orderId,
+          provider: 'alipay',
+          status: alipayStatus.trade_status,
+          data: alipayStatus,
+        };
+      } catch (alipayError) {
+        // 两个都失败，返回详细错误信息
+        throw new Error(
+          `Failed to query order ${orderId}. ` +
+          `Wechat error: ${wechatError instanceof Error ? wechatError.message : 'Unknown'}. ` +
+          `Alipay error: ${alipayError instanceof Error ? alipayError.message : 'Unknown'}`,
+        );
+      }
+    }
+  }
+
+  /**
+   * 申请退款
+   */
+  async refundOrder(
+    orderId: string,
+    refundId: string,
+    amount: number,
+    reason?: string,
+  ) {
+    // TODO: 从数据库查询订单信息，确定支付方式和总金额
+    const totalAmount = amount; // 实际应从数据库获取
+
+    // 这里假设是微信支付，实际应根据订单信息判断
+    const result = await this.paymentService.wechat.refund({
+      outTradeNo: orderId,
+      outRefundNo: refundId,
+      refundAmount: amount,
+      totalAmount: totalAmount,
+      reason: reason || '用户申请退款',
+    });
+
+    return {
+      orderId,
+      refundId,
+      status: result.status,
+      data: result,
+    };
+  }
+}

package/templates/examples/payment/webhook.controller.ts

@@ -0,0 +1,73 @@
+import { Controller, Post, Req, Body, HttpCode } from '@nestjs/common';
+import { Request } from 'express';
+import { PaymentService } from '@svton/nestjs-payment';
+
+@Controller('examples/webhooks')
+export class WebhookController {
+  constructor(private readonly paymentService: PaymentService) {}
+
+  /**
+   * 微信支付回调
+   */
+  @Post('wechat')
+  @HttpCode(200)
+  async wechatWebhook(@Req() req: Request) {
+    try {
+      const result = await this.paymentService.wechat.handleNotify(req);
+
+      console.log('Wechat payment notification:', result);
+
+      // TODO: 处理支付成功逻辑
+      // 1. 验证订单状态
+      // 2. 更新订单状态
+      // 3. 发送通知给用户
+      // 4. 触发后续业务流程
+
+      const { out_trade_no, transaction_id, trade_state } = result;
+
+      if (trade_state === 'SUCCESS') {
+        console.log(`Order ${out_trade_no} paid successfully`);
+        // await this.orderService.markAsPaid(out_trade_no, transaction_id);
+      }
+
+      // 返回成功响应
+      return {
+        code: 'SUCCESS',
+        message: '成功',
+      };
+    } catch (error) {
+      console.error('Wechat webhook error:', error);
+      return {
+        code: 'FAIL',
+        message: error.message,
+      };
+    }
+  }
+
+  /**
+   * 支付宝支付回调
+   */
+  @Post('alipay')
+  @HttpCode(200)
+  async alipayWebhook(@Body() body: any) {
+    try {
+      const result = await this.paymentService.alipay.handleNotify(body);
+
+      console.log('Alipay payment notification:', result);
+
+      // TODO: 处理支付成功逻辑
+      const { out_trade_no, trade_no, trade_status } = result;
+
+      if (trade_status === 'TRADE_SUCCESS') {
+        console.log(`Order ${out_trade_no} paid successfully`);
+        // await this.orderService.markAsPaid(out_trade_no, trade_no);
+      }
+
+      // 返回成功响应（支付宝要求返回 success 字符串）
+      return 'success';
+    } catch (error) {
+      console.error('Alipay webhook error:', error);
+      return 'fail';
+    }
+  }
+}

package/templates/examples/queue/README.md

@@ -0,0 +1,134 @@
+# 消息队列示例
+
+本示例展示如何使用 `@svton/nestjs-queue` 模块处理异步任务。
+
+## 文件说明
+
+- `email.processor.ts` - 队列处理器，定义任务执行逻辑
+- `email.service.ts` - 服务层，添加任务到队列
+- `email.controller.ts` - 控制器，提供 API 接口
+
+## 核心概念
+
+- **Queue（队列）**：任务的容器
+- **Job（任务）**：具体的执行单元
+- **Processor（处理器）**：任务的执行逻辑
+- **Worker（工作进程）**：执行任务的进程
+
+## 使用方式
+
+### 1. 定义处理器
+
+```typescript
+@Processor({ name: 'email' })
+export class EmailProcessor {
+  @Process('send')
+  async handleSend(job: Job<EmailData>) {
+    // 处理任务
+  }
+}
+```
+
+### 2. 添加任务
+
+```typescript
+await this.queueService.addJob('email', 'send', {
+  to: 'user@example.com',
+  subject: 'Welcome',
+  body: 'Welcome to our platform!',
+});
+```
+
+## 任务选项
+
+### 延迟执行
+
+```typescript
+await this.queueService.addJob('email', 'send', data, {
+  delay: 60000, // 延迟 60 秒
+});
+```
+
+### 重试策略
+
+```typescript
+await this.queueService.addJob('email', 'send', data, {
+  attempts: 3,
+  backoff: {
+    type: 'exponential',
+    delay: 1000,
+  },
+});
+```
+
+### 定时任务
+
+```typescript
+await this.queueService.addJob('email', 'send', data, {
+  repeat: {
+    cron: '0 9 * * *', // 每天 9 点执行
+  },
+});
+```
+
+### 优先级
+
+```typescript
+await this.queueService.addJob('email', 'send', data, {
+  priority: 1, // 数字越小优先级越高
+});
+```
+
+## 测试接口
+
+```bash
+# 发送邮件
+curl -X POST http://localhost:3000/examples/emails/send \
+  -H "Content-Type: application/json" \
+  -d '{
+    "to": "user@example.com",
+    "subject": "Test Email",
+    "body": "This is a test email"
+  }'
+
+# 延迟发送
+curl -X POST http://localhost:3000/examples/emails/send-delayed \
+  -H "Content-Type: application/json" \
+  -d '{
+    "to": "user@example.com",
+    "subject": "Delayed Email",
+    "body": "This email will be sent after 10 seconds",
+    "delayMs": 10000
+  }'
+
+# 批量发送
+curl -X POST http://localhost:3000/examples/emails/send-batch \
+  -H "Content-Type: application/json" \
+  -d '{
+    "emails": [
+      {"to": "user1@example.com", "subject": "Test 1", "body": "Body 1"},
+      {"to": "user2@example.com", "subject": "Test 2", "body": "Body 2"}
+    ]
+  }'
+
+# 紧急邮件（高优先级）
+curl -X POST http://localhost:3000/examples/emails/send-urgent \
+  -H "Content-Type: application/json" \
+  -d '{
+    "to": "admin@example.com",
+    "subject": "Urgent",
+    "body": "This is urgent!"
+  }'
+```
+
+## 最佳实践
+
+1. **任务幂等性**：确保任务可以安全重试
+2. **合理设置重试**：根据业务场景设置重试次数和策略
+3. **任务拆分**：大任务拆分成小任务，提高并发度
+4. **监控告警**：监听失败事件，及时处理异常
+5. **资源限制**：控制并发数，避免资源耗尽
+
+## 更多信息
+
+查看官方文档：https://751848178.github.io/svton/packages/nestjs-queue

package/templates/examples/queue/email.controller.ts

@@ -0,0 +1,34 @@
+import { Controller, Post, Body } from '@nestjs/common';
+import { EmailService } from './email.service';
+import { EmailData } from './email.processor';
+
+@Controller('examples/emails')
+export class EmailController {
+  constructor(private readonly emailService: EmailService) {}
+
+  @Post('send')
+  async send(@Body() data: EmailData) {
+    await this.emailService.sendEmail(data);
+    return { message: 'Email queued successfully' };
+  }
+
+  @Post('send-delayed')
+  async sendDelayed(
+    @Body() data: EmailData & { delayMs: number },
+  ) {
+    await this.emailService.sendEmailDelayed(data, data.delayMs);
+    return { message: `Email will be sent after ${data.delayMs}ms` };
+  }
+
+  @Post('send-batch')
+  async sendBatch(@Body() data: { emails: EmailData[] }) {
+    await this.emailService.sendBatchEmails(data.emails);
+    return { message: `${data.emails.length} emails queued successfully` };
+  }
+
+  @Post('send-urgent')
+  async sendUrgent(@Body() data: EmailData) {
+    await this.emailService.sendUrgentEmail(data);
+    return { message: 'Urgent email queued successfully' };
+  }
+}

package/templates/examples/queue/email.processor.ts

@@ -0,0 +1,68 @@
+import { Injectable } from '@nestjs/common';
+import { Processor, Process, OnQueueCompleted, OnQueueFailed } from '@svton/nestjs-queue';
+import { Job } from 'bullmq';
+
+export interface EmailData {
+  to: string;
+  subject: string;
+  body: string;
+}
+
+@Processor({ name: 'email' })
+@Injectable()
+export class EmailProcessor {
+  /**
+   * 处理发送邮件任务
+   */
+  @Process('send')
+  async handleSend(job: Job<EmailData>) {
+    const { to, subject, body } = job.data;
+    
+    console.log(`Sending email to ${to}...`);
+    console.log(`Subject: ${subject}`);
+    console.log(`Body: ${body}`);
+    
+    // TODO: 实际项目中调用邮件服务
+    // await this.emailService.send(to, subject, body);
+    
+    // 模拟发送延迟
+    await new Promise(resolve => setTimeout(resolve, 2000));
+    
+    console.log(`Email sent successfully to ${to}`);
+    
+    return { success: true, to };
+  }
+
+  /**
+   * 处理批量发送任务
+   */
+  @Process('sendBatch')
+  async handleSendBatch(job: Job<{ emails: EmailData[] }>) {
+    const { emails } = job.data;
+    
+    console.log(`Sending ${emails.length} emails...`);
+    
+    for (const email of emails) {
+      await this.handleSend({ data: email } as Job<EmailData>);
+    }
+    
+    return { success: true, count: emails.length };
+  }
+
+  /**
+   * 任务完成回调
+   */
+  @OnQueueCompleted({ name: 'email' })
+  async onCompleted(job: Job) {
+    console.log(`Job ${job.id} completed successfully`);
+  }
+
+  /**
+   * 任务失败回调
+   */
+  @OnQueueFailed({ name: 'email' })
+  async onFailed(job: Job, error: Error) {
+    console.error(`Job ${job.id} failed:`, error.message);
+    // TODO: 发送告警通知
+  }
+}