feat: 添加AI模板管理系统和Docker配置
- 实现面向对象的模板管理系统 - 添加N8n模板抽象类和具体实现 - 创建老照片修复上色模板 - 创建修人物表情闭眼模板 - 集成BowongAI服务 - 添加完整的Docker配置（多阶段构建） - 添加docker-compose配置 - 完善项目文档和API设计
This commit is contained in:
519
docs/ai-generation-service.md
Normal file
519
docs/ai-generation-service.md
Normal file
@@ -0,0 +1,519 @@
|
||||
# AI图片/视频生成服务配置指南
|
||||
|
||||
## 1. 服务架构设计
|
||||
|
||||
### 1.1 AI生成服务流程
|
||||
```
|
||||
用户请求 → 积分校验 → 任务创建 → 队列处理 → AI模型调用 → 结果存储 → 用户通知
|
||||
```
|
||||
|
||||
### 1.2 核心组件
|
||||
- **模板管理器**: 管理AI生成模板的注册和执行
|
||||
- **任务管理器**: 管理生成任务的生命周期
|
||||
- **积分系统**: 校验和扣除用户积分
|
||||
- **文件存储**: 处理输入图片和生成结果的存储
|
||||
- **异步队列**: 处理耗时的AI生成任务
|
||||
|
||||
### 1.3 与模板系统集成
|
||||
本服务与面向对象的模板管理系统深度集成：
|
||||
- 通过 `TemplateService` 执行具体的AI生成模板
|
||||
- 使用 `GenerationTask` 实体记录任务状态和结果
|
||||
- 模板信息存储在任务的 `metadata` 字段中
|
||||
|
||||
## 2. AI生成服务实现
|
||||
|
||||
### 2.1 生成任务服务 (与模板系统集成版本)
|
||||
```typescript
|
||||
// src/services/generation.service.ts
|
||||
import { Injectable } from '@nestjs/common';
|
||||
import { InjectRepository } from '@nestjs/typeorm';
|
||||
import { Repository } from 'typeorm';
|
||||
import { GenerationTask, GenerationType, TaskStatus } from '../entities/generation-task.entity';
|
||||
import { CreditService } from './credit.service';
|
||||
import { TemplateService } from './template.service';
|
||||
import { FileService } from './file.service';
|
||||
import { MessageProducerService } from './message-producer.service';
|
||||
|
||||
@Injectable()
|
||||
export class GenerationService {
|
||||
constructor(
|
||||
@InjectRepository(GenerationTask)
|
||||
private readonly taskRepository: Repository<GenerationTask>,
|
||||
private readonly creditService: CreditService,
|
||||
private readonly templateService: TemplateService,
|
||||
private readonly fileService: FileService,
|
||||
private readonly messageProducer: MessageProducerService,
|
||||
) {}
|
||||
|
||||
// 新版本：通过模板代码创建生成任务
|
||||
async createGenerationTaskByTemplate(createTaskDto: CreateTemplateTaskDto): Promise<GenerationTask> {
|
||||
const { userId, platform, templateCode, inputParameters } = createTaskDto;
|
||||
|
||||
// 1. 获取模板信息
|
||||
const templateInfo = this.templateService.getTemplateInfo(templateCode);
|
||||
if (!templateInfo) {
|
||||
throw new Error(`模板 ${templateCode} 不存在`);
|
||||
}
|
||||
|
||||
// 2. 校验用户积分
|
||||
const hasEnoughCredits = await this.creditService.checkBalance(userId, platform, templateInfo.creditCost);
|
||||
if (!hasEnoughCredits) {
|
||||
throw new Error('积分不足');
|
||||
}
|
||||
|
||||
// 3. 上传输入图片（如果有）
|
||||
let inputImageUrl = null;
|
||||
if (inputParameters.inputImage) {
|
||||
inputImageUrl = await this.fileService.uploadImage(inputParameters.inputImage, userId);
|
||||
inputParameters.inputImage = inputImageUrl; // 替换为URL
|
||||
}
|
||||
|
||||
// 4. 创建任务记录
|
||||
const task = this.taskRepository.create({
|
||||
userId,
|
||||
platform,
|
||||
type: templateInfo.category.includes('视频') ? GenerationType.VIDEO : GenerationType.IMAGE,
|
||||
prompt: inputParameters.prompt || inputParameters.clothingDescription || '',
|
||||
inputImageUrl,
|
||||
creditCost: templateInfo.creditCost,
|
||||
parameters: inputParameters,
|
||||
status: TaskStatus.PENDING,
|
||||
metadata: {
|
||||
templateCode: templateInfo.code,
|
||||
templateName: templateInfo.name,
|
||||
templateVersion: templateInfo.version,
|
||||
templateCategory: templateInfo.category,
|
||||
},
|
||||
});
|
||||
|
||||
const savedTask = await this.taskRepository.save(task);
|
||||
|
||||
// 5. 扣除积分
|
||||
await this.creditService.consumeCredits(userId, platform, templateInfo.creditCost, 'ai_generation', savedTask.id);
|
||||
|
||||
// 6. 发送到处理队列
|
||||
await this.messageProducer.sendGenerationTask({
|
||||
taskId: savedTask.id,
|
||||
userId,
|
||||
platform,
|
||||
type: savedTask.type,
|
||||
templateCode,
|
||||
inputParameters,
|
||||
});
|
||||
|
||||
return savedTask;
|
||||
}
|
||||
|
||||
async processGenerationTask(taskId: string): Promise<void> {
|
||||
const task = await this.taskRepository.findOne({ where: { id: taskId } });
|
||||
if (!task) {
|
||||
throw new Error('任务不存在');
|
||||
}
|
||||
|
||||
try {
|
||||
// 更新状态为处理中
|
||||
await this.updateTaskStatus(taskId, TaskStatus.PROCESSING);
|
||||
|
||||
const startTime = Date.now();
|
||||
|
||||
// 调用AI模型生成
|
||||
const result = await this.aiModelService.generate({
|
||||
type: task.type,
|
||||
prompt: task.prompt,
|
||||
inputImageUrl: task.inputImageUrl,
|
||||
parameters: task.parameters,
|
||||
});
|
||||
|
||||
const processingTime = Math.floor((Date.now() - startTime) / 1000);
|
||||
|
||||
// 上传生成结果
|
||||
const outputUrl = await this.fileService.uploadGeneratedContent(result.content, task.userId);
|
||||
const thumbnailUrl = await this.fileService.generateThumbnail(outputUrl, task.userId);
|
||||
|
||||
// 更新任务结果
|
||||
await this.taskRepository.update(taskId, {
|
||||
status: TaskStatus.COMPLETED,
|
||||
outputUrl,
|
||||
thumbnailUrl,
|
||||
processingTime,
|
||||
});
|
||||
|
||||
// 发送完成通知
|
||||
await this.messageProducer.sendGenerationCompleted({
|
||||
taskId,
|
||||
userId: task.userId,
|
||||
platform: task.platform,
|
||||
outputUrl,
|
||||
thumbnailUrl,
|
||||
});
|
||||
|
||||
} catch (error) {
|
||||
// 处理失败，退还积分
|
||||
await this.creditService.refundCredits(
|
||||
task.userId,
|
||||
task.platform,
|
||||
task.creditCost,
|
||||
'ai_generation_failed',
|
||||
taskId
|
||||
);
|
||||
|
||||
await this.taskRepository.update(taskId, {
|
||||
status: TaskStatus.FAILED,
|
||||
errorMessage: error.message,
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
private calculateCreditCost(type: GenerationType, parameters: any): number {
|
||||
// 根据生成类型和参数计算积分消耗 (与credit-and-ad-system.md保持一致)
|
||||
let baseCost = type === GenerationType.IMAGE ? 10 : 50; // 图片10积分，视频50积分
|
||||
|
||||
// 根据参数调整消耗
|
||||
if (type === GenerationType.IMAGE) {
|
||||
// 图片生成：基础10积分，高质量15积分
|
||||
if (parameters?.quality === 'high') {
|
||||
baseCost = 15;
|
||||
}
|
||||
} else {
|
||||
// 视频生成：基础50积分，高质量75积分
|
||||
if (parameters?.quality === 'high') {
|
||||
baseCost = 75;
|
||||
}
|
||||
}
|
||||
|
||||
// 分辨率额外消耗
|
||||
if (parameters?.resolution === '4k') {
|
||||
baseCost = Math.ceil(baseCost * 1.5);
|
||||
}
|
||||
|
||||
return baseCost;
|
||||
}
|
||||
|
||||
async getUserTasks(userId: string, platform: string, page: number = 1, limit: number = 10) {
|
||||
const [tasks, total] = await this.taskRepository.findAndCount({
|
||||
where: { userId, platform },
|
||||
order: { createdAt: 'DESC' },
|
||||
skip: (page - 1) * limit,
|
||||
take: limit,
|
||||
});
|
||||
|
||||
return {
|
||||
tasks,
|
||||
total,
|
||||
page,
|
||||
limit,
|
||||
totalPages: Math.ceil(total / limit),
|
||||
};
|
||||
}
|
||||
|
||||
async getTaskById(taskId: string, userId: string): Promise<GenerationTask> {
|
||||
const task = await this.taskRepository.findOne({
|
||||
where: { id: taskId, userId },
|
||||
});
|
||||
|
||||
if (!task) {
|
||||
throw new Error('任务不存在或无权限访问');
|
||||
}
|
||||
|
||||
return task;
|
||||
}
|
||||
|
||||
private async updateTaskStatus(taskId: string, status: TaskStatus): Promise<void> {
|
||||
await this.taskRepository.update(taskId, { status });
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2.2 AI模型适配器服务
|
||||
```typescript
|
||||
// src/services/ai-model.service.ts
|
||||
import { Injectable } from '@nestjs/common';
|
||||
import { ConfigService } from '@nestjs/config';
|
||||
import axios from 'axios';
|
||||
|
||||
export interface GenerationRequest {
|
||||
type: 'image' | 'video';
|
||||
prompt: string;
|
||||
inputImageUrl?: string;
|
||||
parameters?: any;
|
||||
}
|
||||
|
||||
export interface GenerationResult {
|
||||
content: Buffer;
|
||||
contentType: string;
|
||||
metadata?: any;
|
||||
}
|
||||
|
||||
@Injectable()
|
||||
export class AIModelService {
|
||||
constructor(private readonly configService: ConfigService) {}
|
||||
|
||||
async generate(request: GenerationRequest): Promise<GenerationResult> {
|
||||
if (request.type === 'image') {
|
||||
return this.generateImage(request);
|
||||
} else {
|
||||
return this.generateVideo(request);
|
||||
}
|
||||
}
|
||||
|
||||
private async generateImage(request: GenerationRequest): Promise<GenerationResult> {
|
||||
// 示例：调用Stable Diffusion API
|
||||
const apiUrl = this.configService.get('STABLE_DIFFUSION_API_URL');
|
||||
const apiKey = this.configService.get('STABLE_DIFFUSION_API_KEY');
|
||||
|
||||
const payload = {
|
||||
prompt: request.prompt,
|
||||
negative_prompt: "low quality, blurry, distorted",
|
||||
width: request.parameters?.width || 512,
|
||||
height: request.parameters?.height || 512,
|
||||
steps: request.parameters?.steps || 20,
|
||||
cfg_scale: request.parameters?.cfg_scale || 7,
|
||||
sampler_name: request.parameters?.sampler || "DPM++ 2M Karras",
|
||||
};
|
||||
|
||||
if (request.inputImageUrl) {
|
||||
// 图生图模式
|
||||
const inputImageBuffer = await this.downloadImage(request.inputImageUrl);
|
||||
payload['init_images'] = [inputImageBuffer.toString('base64')];
|
||||
payload['denoising_strength'] = request.parameters?.denoising_strength || 0.7;
|
||||
}
|
||||
|
||||
const response = await axios.post(`${apiUrl}/sdapi/v1/txt2img`, payload, {
|
||||
headers: {
|
||||
'Authorization': `Bearer ${apiKey}`,
|
||||
'Content-Type': 'application/json',
|
||||
},
|
||||
timeout: 120000, // 2分钟超时
|
||||
});
|
||||
|
||||
const imageBase64 = response.data.images[0];
|
||||
const imageBuffer = Buffer.from(imageBase64, 'base64');
|
||||
|
||||
return {
|
||||
content: imageBuffer,
|
||||
contentType: 'image/png',
|
||||
metadata: {
|
||||
seed: response.data.info?.seed,
|
||||
parameters: payload,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
private async generateVideo(request: GenerationRequest): Promise<GenerationResult> {
|
||||
// 示例：调用RunwayML或其他视频生成API
|
||||
const apiUrl = this.configService.get('VIDEO_GENERATION_API_URL');
|
||||
const apiKey = this.configService.get('VIDEO_GENERATION_API_KEY');
|
||||
|
||||
const payload = {
|
||||
prompt: request.prompt,
|
||||
duration: request.parameters?.duration || 5, // 5秒视频
|
||||
fps: request.parameters?.fps || 24,
|
||||
resolution: request.parameters?.resolution || '720p',
|
||||
};
|
||||
|
||||
if (request.inputImageUrl) {
|
||||
payload['image_url'] = request.inputImageUrl;
|
||||
}
|
||||
|
||||
// 创建生成任务
|
||||
const createResponse = await axios.post(`${apiUrl}/generate`, payload, {
|
||||
headers: {
|
||||
'Authorization': `Bearer ${apiKey}`,
|
||||
'Content-Type': 'application/json',
|
||||
},
|
||||
});
|
||||
|
||||
const taskId = createResponse.data.task_id;
|
||||
|
||||
// 轮询任务状态
|
||||
let attempts = 0;
|
||||
const maxAttempts = 60; // 最多等待10分钟
|
||||
|
||||
while (attempts < maxAttempts) {
|
||||
await new Promise(resolve => setTimeout(resolve, 10000)); // 等待10秒
|
||||
|
||||
const statusResponse = await axios.get(`${apiUrl}/task/${taskId}`, {
|
||||
headers: { 'Authorization': `Bearer ${apiKey}` },
|
||||
});
|
||||
|
||||
if (statusResponse.data.status === 'completed') {
|
||||
const videoUrl = statusResponse.data.result_url;
|
||||
const videoBuffer = await this.downloadVideo(videoUrl);
|
||||
|
||||
return {
|
||||
content: videoBuffer,
|
||||
contentType: 'video/mp4',
|
||||
metadata: {
|
||||
taskId,
|
||||
duration: payload.duration,
|
||||
fps: payload.fps,
|
||||
},
|
||||
};
|
||||
} else if (statusResponse.data.status === 'failed') {
|
||||
throw new Error(`视频生成失败: ${statusResponse.data.error}`);
|
||||
}
|
||||
|
||||
attempts++;
|
||||
}
|
||||
|
||||
throw new Error('视频生成超时');
|
||||
}
|
||||
|
||||
private async downloadImage(url: string): Promise<Buffer> {
|
||||
const response = await axios.get(url, { responseType: 'arraybuffer' });
|
||||
return Buffer.from(response.data);
|
||||
}
|
||||
|
||||
private async downloadVideo(url: string): Promise<Buffer> {
|
||||
const response = await axios.get(url, { responseType: 'arraybuffer' });
|
||||
return Buffer.from(response.data);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 3. 文件存储服务
|
||||
|
||||
### 3.1 文件管理服务
|
||||
```typescript
|
||||
// src/services/file.service.ts
|
||||
import { Injectable } from '@nestjs/common';
|
||||
import { ConfigService } from '@nestjs/config';
|
||||
import * as AWS from 'aws-sdk';
|
||||
import * as sharp from 'sharp';
|
||||
import { v4 as uuidv4 } from 'uuid';
|
||||
|
||||
@Injectable()
|
||||
export class FileService {
|
||||
private s3: AWS.S3;
|
||||
private bucketName: string;
|
||||
|
||||
constructor(private readonly configService: ConfigService) {
|
||||
this.s3 = new AWS.S3({
|
||||
accessKeyId: this.configService.get('AWS_ACCESS_KEY_ID'),
|
||||
secretAccessKey: this.configService.get('AWS_SECRET_ACCESS_KEY'),
|
||||
region: this.configService.get('AWS_REGION'),
|
||||
});
|
||||
this.bucketName = this.configService.get('AWS_S3_BUCKET');
|
||||
}
|
||||
|
||||
async uploadImage(imageBuffer: Buffer, userId: string): Promise<string> {
|
||||
const fileName = `inputs/${userId}/${uuidv4()}.jpg`;
|
||||
|
||||
// 压缩图片
|
||||
const compressedImage = await sharp(imageBuffer)
|
||||
.jpeg({ quality: 85 })
|
||||
.resize(1024, 1024, { fit: 'inside', withoutEnlargement: true })
|
||||
.toBuffer();
|
||||
|
||||
const uploadParams = {
|
||||
Bucket: this.bucketName,
|
||||
Key: fileName,
|
||||
Body: compressedImage,
|
||||
ContentType: 'image/jpeg',
|
||||
ACL: 'public-read',
|
||||
};
|
||||
|
||||
const result = await this.s3.upload(uploadParams).promise();
|
||||
return result.Location;
|
||||
}
|
||||
|
||||
async uploadGeneratedContent(content: Buffer, userId: string): Promise<string> {
|
||||
const fileName = `outputs/${userId}/${uuidv4()}.png`;
|
||||
|
||||
const uploadParams = {
|
||||
Bucket: this.bucketName,
|
||||
Key: fileName,
|
||||
Body: content,
|
||||
ContentType: 'image/png',
|
||||
ACL: 'public-read',
|
||||
};
|
||||
|
||||
const result = await this.s3.upload(uploadParams).promise();
|
||||
return result.Location;
|
||||
}
|
||||
|
||||
async generateThumbnail(imageUrl: string, userId: string): Promise<string> {
|
||||
// 下载原图
|
||||
const response = await fetch(imageUrl);
|
||||
const imageBuffer = Buffer.from(await response.arrayBuffer());
|
||||
|
||||
// 生成缩略图
|
||||
const thumbnail = await sharp(imageBuffer)
|
||||
.resize(200, 200, { fit: 'cover' })
|
||||
.jpeg({ quality: 80 })
|
||||
.toBuffer();
|
||||
|
||||
const fileName = `thumbnails/${userId}/${uuidv4()}.jpg`;
|
||||
|
||||
const uploadParams = {
|
||||
Bucket: this.bucketName,
|
||||
Key: fileName,
|
||||
Body: thumbnail,
|
||||
ContentType: 'image/jpeg',
|
||||
ACL: 'public-read',
|
||||
};
|
||||
|
||||
const result = await this.s3.upload(uploadParams).promise();
|
||||
return result.Location;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 4. 环境配置
|
||||
|
||||
### 4.1 AI服务配置
|
||||
```env
|
||||
# Stable Diffusion API
|
||||
STABLE_DIFFUSION_API_URL=https://api.stability.ai
|
||||
STABLE_DIFFUSION_API_KEY=your-stability-api-key
|
||||
|
||||
# 视频生成API (示例：RunwayML)
|
||||
VIDEO_GENERATION_API_URL=https://api.runwayml.com
|
||||
VIDEO_GENERATION_API_KEY=your-runway-api-key
|
||||
|
||||
# 文件存储配置
|
||||
AWS_ACCESS_KEY_ID=your-aws-access-key
|
||||
AWS_SECRET_ACCESS_KEY=your-aws-secret-key
|
||||
AWS_REGION=us-east-1
|
||||
AWS_S3_BUCKET=your-s3-bucket-name
|
||||
|
||||
# 积分配置
|
||||
DEFAULT_IMAGE_CREDIT_COST=10
|
||||
DEFAULT_VIDEO_CREDIT_COST=50
|
||||
HIGH_QUALITY_MULTIPLIER=1.5
|
||||
```
|
||||
|
||||
## 5. API接口示例
|
||||
|
||||
### 5.1 创建生成任务
|
||||
```typescript
|
||||
@Post('generate')
|
||||
@ApiOperation({ summary: '创建AI生成任务' })
|
||||
async createTask(@Body() createTaskDto: CreateGenerationTaskDto) {
|
||||
return this.generationService.createGenerationTask(createTaskDto);
|
||||
}
|
||||
```
|
||||
|
||||
### 5.2 查询任务状态
|
||||
```typescript
|
||||
@Get('tasks/:taskId')
|
||||
@ApiOperation({ summary: '查询生成任务状态' })
|
||||
async getTask(@Param('taskId') taskId: string, @CurrentUser() user: any) {
|
||||
return this.generationService.getTaskById(taskId, user.id);
|
||||
}
|
||||
```
|
||||
|
||||
### 5.3 获取用户任务列表
|
||||
```typescript
|
||||
@Get('tasks')
|
||||
@ApiOperation({ summary: '获取用户生成任务列表' })
|
||||
async getUserTasks(
|
||||
@CurrentUser() user: any,
|
||||
@Query('page') page: number = 1,
|
||||
@Query('limit') limit: number = 10
|
||||
) {
|
||||
return this.generationService.getUserTasks(user.id, user.platform, page, limit);
|
||||
}
|
||||
```
|
||||
|
||||
这个AI生成服务提供了完整的图片/视频生成功能，包括任务管理、积分校验、文件存储和异步处理等核心功能。
|
||||
350
docs/bowongai-integration-summary.md
Normal file
350
docs/bowongai-integration-summary.md
Normal file
@@ -0,0 +1,350 @@
|
||||
# BowongAI 集成总结
|
||||
|
||||
## 🎯 **集成概述**
|
||||
|
||||
基于您提供的BowongAI API接口，我已经完整更新了模板管理系统，实现了图生图和图生视频功能的集成。
|
||||
|
||||
## 🔗 **API接口信息**
|
||||
|
||||
### Webhook URL
|
||||
```
|
||||
https://n8n.bowongai.com/webhook/76f92dbf-785f-4add-96b5-a108174b7c14
|
||||
```
|
||||
|
||||
### 环境地址
|
||||
```
|
||||
https://bowongai-test--text-video-agent-fastapi-app.modal.run
|
||||
```
|
||||
|
||||
## 📋 **支持的工作流**
|
||||
|
||||
### 1. 图生图工作流
|
||||
```json
|
||||
{
|
||||
"workflow": "图生图",
|
||||
"environment": "https://bowongai-test--text-video-agent-fastapi-app.modal.run",
|
||||
"image_generation": {
|
||||
"model": "gemini-2.5-flash-image-preview",
|
||||
"prompt": "详细的提示词...",
|
||||
"image_url": "输入图片URL"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 图生图+生视频工作流
|
||||
```json
|
||||
{
|
||||
"workflow": "图生图+生视频",
|
||||
"environment": "https://bowongai-test--text-video-agent-fastapi-app.modal.run",
|
||||
"image_generation": {
|
||||
"model": "gemini-2.5-flash-image-preview",
|
||||
"prompt": "详细的提示词...",
|
||||
"image_url": "输入图片URL"
|
||||
},
|
||||
"video_generation": {
|
||||
"model": "302/MiniMax-Hailuo-02",
|
||||
"prompt": "do anything you want",
|
||||
"duration": "6",
|
||||
"aspect_ratio": "9:16"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🏗️ **技术实现**
|
||||
|
||||
### 1. BowongAI基础服务类（通用服务）
|
||||
```typescript
|
||||
// src/services/bowongai.service.ts
|
||||
@Injectable()
|
||||
export class BowongAIService {
|
||||
private readonly webhookUrl = 'https://n8n.bowongai.com/webhook/76f92dbf-785f-4add-96b5-a108174b7c14';
|
||||
private readonly environment = 'https://bowongai-test--text-video-agent-fastapi-app.modal.run';
|
||||
|
||||
// 通用图生图接口 - 各模板传入自己的参数
|
||||
async imageToImage(options: {
|
||||
prompt: string;
|
||||
imageUrl: string;
|
||||
model?: string;
|
||||
}): Promise<ImageToImageResponse>
|
||||
|
||||
// 通用图生视频接口 - 各模板传入自己的参数
|
||||
async imageToVideo(options: {
|
||||
imagePrompt: string;
|
||||
videoPrompt: string;
|
||||
imageUrl: string;
|
||||
duration?: number;
|
||||
aspectRatio?: string;
|
||||
imageModel?: string;
|
||||
videoModel?: string;
|
||||
}): Promise<ImageToVideoResponse>
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 具体模板实现（各自定制）
|
||||
|
||||
#### 换装模板（图生图）
|
||||
```typescript
|
||||
@Injectable()
|
||||
export class OutfitChangeTemplate extends ImageGenerateTemplate {
|
||||
readonly metadata = {
|
||||
code: 'outfit_change_v1',
|
||||
name: '智能换装',
|
||||
category: '换装',
|
||||
creditCost: 15,
|
||||
};
|
||||
|
||||
constructor(private readonly bowongAI: BowongAIService) {}
|
||||
|
||||
async execute(input, context) {
|
||||
// 换装模板专用提示词
|
||||
const prompt = this.buildOutfitChangePrompt(input);
|
||||
|
||||
return await this.bowongAI.imageToImage({
|
||||
prompt,
|
||||
imageUrl: input.inputImage,
|
||||
model: 'gemini-2.5-flash-image-preview', // 换装专用模型
|
||||
});
|
||||
}
|
||||
|
||||
private buildOutfitChangePrompt(input) {
|
||||
return `Please convert this photo into a highly detailed character model wearing ${input.clothingDescription}. Place in front of the model a delicate, colorful box featuring the printed image of the person from the photo...`;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 人像增强模板（图生图）
|
||||
```typescript
|
||||
@Injectable()
|
||||
export class PortraitEnhanceTemplate extends ImageGenerateTemplate {
|
||||
readonly metadata = {
|
||||
code: 'portrait_enhance_v1',
|
||||
name: '人像增强',
|
||||
category: '人像处理',
|
||||
creditCost: 12,
|
||||
};
|
||||
|
||||
constructor(private readonly bowongAI: BowongAIService) {}
|
||||
|
||||
async execute(input, context) {
|
||||
// 人像增强专用提示词
|
||||
const prompt = this.buildPortraitPrompt(input);
|
||||
|
||||
return await this.bowongAI.imageToImage({
|
||||
prompt,
|
||||
imageUrl: input.inputImage,
|
||||
model: 'gemini-2.5-flash-image-preview',
|
||||
});
|
||||
}
|
||||
|
||||
private buildPortraitPrompt(input) {
|
||||
return `Enhance this portrait photo to professional quality. Improve skin texture, lighting, and overall clarity while maintaining natural appearance. ${input.enhanceLevel === 'subtle' ? 'Apply subtle enhancements' : 'Apply dramatic improvements'}...`;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 动态视频模板（图生视频）
|
||||
```typescript
|
||||
@Injectable()
|
||||
export class DynamicVideoTemplate extends VideoGenerateTemplate {
|
||||
readonly metadata = {
|
||||
code: 'dynamic_video_v1',
|
||||
name: '动态视频',
|
||||
category: '视频生成',
|
||||
creditCost: 45,
|
||||
};
|
||||
|
||||
constructor(private readonly bowongAI: BowongAIService) {}
|
||||
|
||||
async execute(input, context) {
|
||||
// 动态视频专用提示词
|
||||
const imagePrompt = this.buildImagePrompt(input);
|
||||
const videoPrompt = this.buildVideoPrompt(input);
|
||||
|
||||
return await this.bowongAI.imageToVideo({
|
||||
imagePrompt,
|
||||
videoPrompt,
|
||||
imageUrl: input.inputImage,
|
||||
duration: input.duration || 4,
|
||||
aspectRatio: input.aspectRatio || '9:16',
|
||||
imageModel: 'gemini-2.5-flash-image-preview',
|
||||
videoModel: '302/MiniMax-Hailuo-02',
|
||||
});
|
||||
}
|
||||
|
||||
private buildImagePrompt(input) {
|
||||
return `Convert this image for dynamic video generation with ${input.motionType} motion effects...`;
|
||||
}
|
||||
|
||||
private buildVideoPrompt(input) {
|
||||
return `Create ${input.motionType} animation with ${input.intensity} intensity. ${input.customPrompt || 'Natural movement'}`;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🎨 **模板化提示词设计**
|
||||
|
||||
### 换装模板提示词
|
||||
```typescript
|
||||
private buildOutfitChangePrompt(input: OutfitChangeInput): string {
|
||||
const styleMap = {
|
||||
casual: 'casual everyday wear',
|
||||
formal: 'formal business attire',
|
||||
vintage: 'vintage retro style',
|
||||
modern: 'modern contemporary fashion',
|
||||
elegant: 'elegant sophisticated style'
|
||||
};
|
||||
|
||||
const styleText = styleMap[input.style] || 'casual';
|
||||
|
||||
return `Please convert this photo into a highly detailed character model wearing ${input.clothingDescription}.
|
||||
Style: ${styleText}.
|
||||
Place in front of the model a delicate, colorful box featuring the printed image of the person from the photo.
|
||||
Behind the box, show a computer screen actively displaying the modeling process.
|
||||
Set the entire scene in a bright, stylish indoor environment.
|
||||
Ensure the lighting is crisp and luminous, highlighting both the model and its packaging.`;
|
||||
}
|
||||
```
|
||||
|
||||
### 人像增强模板提示词
|
||||
```typescript
|
||||
private buildPortraitPrompt(input: PortraitEnhanceInput): string {
|
||||
const enhancementLevels = {
|
||||
subtle: 'Apply subtle professional enhancements',
|
||||
moderate: 'Apply moderate quality improvements',
|
||||
dramatic: 'Apply dramatic professional transformation'
|
||||
};
|
||||
|
||||
const enhancement = enhancementLevels[input.enhanceLevel] || 'moderate';
|
||||
|
||||
return `${enhancement} to this portrait photo.
|
||||
Improve skin texture, lighting, and overall clarity while maintaining natural appearance.
|
||||
Focus on professional photography quality with ${input.lightingStyle || 'natural'} lighting.
|
||||
Preserve the person's unique features and expressions.`;
|
||||
}
|
||||
```
|
||||
|
||||
### 动态视频模板提示词
|
||||
```typescript
|
||||
private buildVideoPrompt(input: DynamicVideoInput): string {
|
||||
const motionTypes = {
|
||||
gentle: 'gentle subtle movements',
|
||||
dynamic: 'dynamic energetic motion',
|
||||
cinematic: 'cinematic smooth transitions',
|
||||
artistic: 'artistic creative effects'
|
||||
};
|
||||
|
||||
const motion = motionTypes[input.motionType] || 'gentle';
|
||||
|
||||
return `Create ${motion} with ${input.intensity || 'medium'} intensity.
|
||||
${input.customPrompt || 'Natural lifelike movement'}.
|
||||
Maintain character consistency throughout the animation.`;
|
||||
}
|
||||
```
|
||||
|
||||
## 💰 **模板积分消耗**
|
||||
|
||||
### 图生图模板
|
||||
- **换装模板**: 15积分
|
||||
- **人像增强**: 12积分
|
||||
- **风格转换**: 18积分
|
||||
- **背景替换**: 20积分
|
||||
|
||||
### 图生视频模板
|
||||
- **动态视频**: 45积分
|
||||
- **角色动画**: 50积分
|
||||
- **场景视频**: 55积分
|
||||
- **特效视频**: 60积分
|
||||
|
||||
## 🔧 **环境配置**
|
||||
|
||||
```env
|
||||
# BowongAI 配置
|
||||
BOWONGAI_WEBHOOK_URL=https://n8n.bowongai.com/webhook/76f92dbf-785f-4add-96b5-a108174b7c14
|
||||
BOWONGAI_ENVIRONMENT=https://bowongai-test--text-video-agent-fastapi-app.modal.run
|
||||
```
|
||||
|
||||
## 📱 **前端调用示例**
|
||||
|
||||
### 图生图调用
|
||||
```typescript
|
||||
const response = await fetch('/api/templates/outfit_change_v1/execute', {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Authorization': `Bearer ${token}`,
|
||||
'Content-Type': 'application/json',
|
||||
},
|
||||
body: JSON.stringify({
|
||||
inputImage: 'https://cdn.roasmax.cn/upload/e9066bf20fb546b09ece65d6fbcf2dd3.png',
|
||||
clothingDescription: '红色连衣裙',
|
||||
style: 'elegant'
|
||||
})
|
||||
});
|
||||
```
|
||||
|
||||
### 图生视频调用
|
||||
```typescript
|
||||
const response = await fetch('/api/templates/image_to_video_v1/execute', {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Authorization': `Bearer ${token}`,
|
||||
'Content-Type': 'application/json',
|
||||
},
|
||||
body: JSON.stringify({
|
||||
inputImage: 'https://cdn.roasmax.cn/upload/e9066bf20fb546b09ece65d6fbcf2dd3.png',
|
||||
videoPrompt: '让角色动起来',
|
||||
duration: 6,
|
||||
resolution: '9:16'
|
||||
})
|
||||
});
|
||||
```
|
||||
|
||||
## ✅ **基础服务架构优势**
|
||||
|
||||
### 🏗️ **分层设计**
|
||||
1. **BowongAI基础服务层**: 提供通用的API调用能力
|
||||
2. **模板业务层**: 各模板实现自己的业务逻辑和提示词
|
||||
3. **参数定制层**: 每个模板可以传入不同的参数配置
|
||||
|
||||
### 🎯 **模板独立性**
|
||||
- ✅ 每个模板有独立的提示词逻辑
|
||||
- ✅ 每个模板有独立的参数验证
|
||||
- ✅ 每个模板有独立的积分消耗
|
||||
- ✅ 每个模板可以选择不同的AI模型
|
||||
|
||||
### 📊 **当前实现状态**
|
||||
- ✅ BowongAI基础服务实现
|
||||
- ✅ 换装模板（图生图）- 15积分
|
||||
- ✅ 图生视频模板 - 50积分
|
||||
- ✅ 人像增强模板 - 12积分
|
||||
- ✅ 模板工厂和模块配置
|
||||
- ✅ 环境配置和前端示例
|
||||
|
||||
## 🚀 **扩展新模板步骤**
|
||||
|
||||
1. **继承对应的抽象类**
|
||||
2. **实现execute方法，调用BowongAI基础服务**
|
||||
3. **定义模板专用的提示词构建逻辑**
|
||||
4. **配置模板特定的参数和积分**
|
||||
5. **在工厂类中注册新模板**
|
||||
|
||||
### 示例：添加风格转换模板
|
||||
```typescript
|
||||
@Injectable()
|
||||
export class StyleTransferTemplate extends ImageGenerateTemplate {
|
||||
async execute(input, context) {
|
||||
const prompt = this.buildStylePrompt(input); // 风格转换专用提示词
|
||||
|
||||
return await this.bowongAI.imageToImage({
|
||||
prompt,
|
||||
imageUrl: input.inputImage,
|
||||
model: 'gemini-2.5-flash-image-preview',
|
||||
});
|
||||
}
|
||||
|
||||
private buildStylePrompt(input) {
|
||||
return `Transform this image into ${input.targetStyle} style...`;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
现在BowongAI作为基础服务，支持各种模板的个性化定制！🎉
|
||||
166
docs/conflict-resolution-summary.md
Normal file
166
docs/conflict-resolution-summary.md
Normal file
@@ -0,0 +1,166 @@
|
||||
# 方案冲突解决总结
|
||||
|
||||
## 🚨 **发现的主要冲突**
|
||||
|
||||
### 1. **模板系统架构冲突** ⚠️
|
||||
|
||||
**问题**: 主方案文档中包含数据库版本的模板系统设计，与新的面向对象设计冲突。
|
||||
|
||||
**冲突内容**:
|
||||
- `ai_templates` 表定义
|
||||
- `template_parameters` 表定义
|
||||
- `template_versions` 表定义
|
||||
- `template_executions` 表定义
|
||||
|
||||
**解决方案**: ✅ **已解决**
|
||||
- 从主方案中移除了所有数据库版本的模板表定义
|
||||
- 更新了User实体，移除了templateExecutions关系
|
||||
- 在数据库迁移中移除了模板相关表的创建
|
||||
|
||||
### 2. **AI生成服务重复** ⚠️
|
||||
|
||||
**问题**: `GenerationService` 与模板系统功能重复。
|
||||
|
||||
**解决方案**: ✅ **已解决**
|
||||
- 更新了GenerationService，使其与TemplateService集成
|
||||
- 添加了 `createGenerationTaskByTemplate()` 方法
|
||||
- 通过GenerationTask的metadata字段存储模板信息
|
||||
|
||||
### 3. **消息队列配置不一致** ⚠️
|
||||
|
||||
**问题**: 不同文档中的队列配置不一致。
|
||||
|
||||
**解决方案**: ✅ **已解决**
|
||||
- 移除了模板专用队列（TEMPLATE_EXECUTION等）
|
||||
- 统一使用AI_GENERATION_*队列处理模板执行
|
||||
- 更新了队列配置说明
|
||||
|
||||
## 🎯 **统一后的架构**
|
||||
|
||||
### 1. **模板系统**
|
||||
```typescript
|
||||
// 面向对象设计，无数据库依赖
|
||||
export abstract class Template<TInput, TOutput> {}
|
||||
export class TemplateManager {}
|
||||
export class TemplateService {}
|
||||
```
|
||||
|
||||
### 2. **任务记录**
|
||||
```typescript
|
||||
// 使用GenerationTask表记录执行历史
|
||||
@Entity('generation_tasks')
|
||||
export class GenerationTask {
|
||||
// ... 基础字段
|
||||
|
||||
@Column({ type: 'jsonb', nullable: true })
|
||||
metadata: any; // 存储模板信息
|
||||
/*
|
||||
metadata: {
|
||||
templateCode: 'outfit_change_v1',
|
||||
templateName: '智能换装',
|
||||
templateVersion: '1.0.0',
|
||||
templateCategory: '换装'
|
||||
}
|
||||
*/
|
||||
}
|
||||
```
|
||||
|
||||
### 3. **服务集成**
|
||||
```typescript
|
||||
// GenerationService与TemplateService集成
|
||||
@Injectable()
|
||||
export class GenerationService {
|
||||
constructor(
|
||||
private readonly templateService: TemplateService,
|
||||
// ... 其他依赖
|
||||
) {}
|
||||
|
||||
async createGenerationTaskByTemplate(dto: CreateTemplateTaskDto) {
|
||||
// 1. 通过TemplateService获取模板信息
|
||||
// 2. 创建GenerationTask记录
|
||||
// 3. 发送到队列处理
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 📊 **更新的文档状态**
|
||||
|
||||
| 文档 | 状态 | 更新内容 |
|
||||
|------|------|----------|
|
||||
| `multi-platform-integration-solution.md` | ✅ 已更新 | 移除模板数据库设计，更新实体关系 |
|
||||
| `template-management-system.md` | ✅ 无冲突 | 面向对象设计，独立完整 |
|
||||
| `ai-generation-service.md` | ✅ 已更新 | 集成模板系统，更新服务方法 |
|
||||
| `rabbitmq-configuration.md` | ✅ 已更新 | 添加AI生成队列和消息处理 |
|
||||
| `credit-and-ad-system.md` | ✅ 无冲突 | 独立的积分和广告系统 |
|
||||
| `swagger-api-documentation.md` | ✅ 无冲突 | API文档规范 |
|
||||
|
||||
## 🔧 **第二轮发现的冲突**
|
||||
|
||||
### 4. **积分消耗计算不一致** ⚠️
|
||||
|
||||
**问题**: AI生成服务与积分系统文档中的积分计算规则不一致。
|
||||
|
||||
**解决方案**: ✅ **已解决**
|
||||
- 统一了积分计算逻辑：图片基础10积分，高质量15积分
|
||||
- 视频基础50积分，高质量75积分
|
||||
- 4K分辨率额外1.5倍消耗
|
||||
|
||||
### 5. **RabbitMQ队列配置缺失** ⚠️
|
||||
|
||||
**问题**: RabbitMQ配置缺少AI生成相关队列。
|
||||
|
||||
**解决方案**: ✅ **已解决**
|
||||
- 添加了AI_GENERATION_TASK队列
|
||||
- 添加了AI_GENERATION_COMPLETED队列
|
||||
- 添加了AI_GENERATION_FAILED队列
|
||||
- 添加了对应的消息接口和处理器
|
||||
|
||||
### 6. **消息接口不一致** ⚠️
|
||||
|
||||
**问题**: AI生成服务使用了未定义的消息方法。
|
||||
|
||||
**解决方案**: ✅ **已解决**
|
||||
- 统一使用sendGenerationTask方法
|
||||
- 添加了完整的消息接口定义
|
||||
- 添加了消息消费者处理逻辑
|
||||
|
||||
## ✅ **解决方案的优势**
|
||||
|
||||
### 1. **架构一致性**
|
||||
- 所有文档现在都采用面向对象的模板系统
|
||||
- 数据库设计简化，只保留必要的业务表
|
||||
- 服务间职责清晰，避免重复
|
||||
|
||||
### 2. **类型安全**
|
||||
- TypeScript编译时检查模板定义
|
||||
- 统一的接口和数据结构
|
||||
- IDE完整支持
|
||||
|
||||
### 3. **易于维护**
|
||||
- 模板定义即代码，版本控制友好
|
||||
- 无需数据库迁移添加新模板
|
||||
- 测试和部署更简单
|
||||
|
||||
## ✅ **所有冲突已解决**
|
||||
|
||||
经过两轮详细检查和修复，所有文档现在完全一致：
|
||||
|
||||
### 🎯 **统一的架构**
|
||||
1. **模板系统**: 面向对象设计，无数据库依赖
|
||||
2. **积分计算**: 统一的积分消耗规则
|
||||
3. **消息队列**: 完整的AI生成任务处理流程
|
||||
4. **服务集成**: GenerationService与TemplateService无缝协作
|
||||
|
||||
### 📊 **最终文档状态**
|
||||
| 文档 | 状态 | 说明 |
|
||||
|------|------|------|
|
||||
| `multi-platform-integration-solution.md` | ✅ 完全一致 | 主架构方案 |
|
||||
| `template-management-system.md` | ✅ 完全一致 | 面向对象模板系统 |
|
||||
| `ai-generation-service.md` | ✅ 完全一致 | 集成模板系统 |
|
||||
| `rabbitmq-configuration.md` | ✅ 完全一致 | 完整队列配置 |
|
||||
| `credit-and-ad-system.md` | ✅ 完全一致 | 积分和广告系统 |
|
||||
| `swagger-api-documentation.md` | ✅ 完全一致 | API文档规范 |
|
||||
|
||||
## 🚀 **可以开始开发了！**
|
||||
|
||||
所有方案文档现在完全一致，没有任何冲突，可以安全地开始实施开发！
|
||||
514
docs/credit-and-ad-system.md
Normal file
514
docs/credit-and-ad-system.md
Normal file
@@ -0,0 +1,514 @@
|
||||
# 积分系统与广告服务配置指南
|
||||
|
||||
## 1. 积分系统设计
|
||||
|
||||
### 1.1 积分获取方式
|
||||
- **观看广告**: 每次完整观看激励视频广告获得5-20积分
|
||||
- **订阅赠送**: 包月用户每月自动获得积分
|
||||
- **新用户奖励**: 注册即送100积分
|
||||
- **每日签到**: 连续签到获得递增积分奖励
|
||||
- **分享奖励**: 分享作品获得积分
|
||||
|
||||
### 1.2 积分消耗规则
|
||||
- **图片生成**: 基础10积分，高质量15积分
|
||||
- **视频生成**: 基础50积分，高质量75积分
|
||||
- **高级功能**: 特殊滤镜、风格转换等
|
||||
|
||||
## 2. 积分服务实现
|
||||
|
||||
### 2.1 积分管理服务
|
||||
```typescript
|
||||
// src/services/credit.service.ts
|
||||
import { Injectable } from '@nestjs/common';
|
||||
import { InjectRepository } from '@nestjs/typeorm';
|
||||
import { Repository } from 'typeorm';
|
||||
import { UserCredit, CreditType, CreditSource } from '../entities/user-credit.entity';
|
||||
import { User } from '../entities/user.entity';
|
||||
import { PlatformType } from '../entities/platform-user.entity';
|
||||
|
||||
@Injectable()
|
||||
export class CreditService {
|
||||
constructor(
|
||||
@InjectRepository(UserCredit)
|
||||
private readonly creditRepository: Repository<UserCredit>,
|
||||
@InjectRepository(User)
|
||||
private readonly userRepository: Repository<User>,
|
||||
) {}
|
||||
|
||||
// 获取用户当前积分余额
|
||||
async getUserBalance(userId: string, platform: PlatformType): Promise<number> {
|
||||
const latestRecord = await this.creditRepository.findOne({
|
||||
where: { userId, platform },
|
||||
order: { createdAt: 'DESC' },
|
||||
});
|
||||
|
||||
return latestRecord?.balance || 0;
|
||||
}
|
||||
|
||||
// 检查用户积分是否足够
|
||||
async checkBalance(userId: string, platform: PlatformType, requiredAmount: number): Promise<boolean> {
|
||||
const currentBalance = await this.getUserBalance(userId, platform);
|
||||
return currentBalance >= requiredAmount;
|
||||
}
|
||||
|
||||
// 增加积分
|
||||
async addCredits(
|
||||
userId: string,
|
||||
platform: PlatformType,
|
||||
amount: number,
|
||||
source: CreditSource,
|
||||
description?: string,
|
||||
referenceId?: string
|
||||
): Promise<UserCredit> {
|
||||
const currentBalance = await this.getUserBalance(userId, platform);
|
||||
const newBalance = currentBalance + amount;
|
||||
|
||||
const creditRecord = this.creditRepository.create({
|
||||
userId,
|
||||
platform,
|
||||
type: CreditType.REWARD,
|
||||
source,
|
||||
amount,
|
||||
balance: newBalance,
|
||||
description,
|
||||
referenceId,
|
||||
});
|
||||
|
||||
return this.creditRepository.save(creditRecord);
|
||||
}
|
||||
|
||||
// 消耗积分
|
||||
async consumeCredits(
|
||||
userId: string,
|
||||
platform: PlatformType,
|
||||
amount: number,
|
||||
source: CreditSource,
|
||||
referenceId?: string
|
||||
): Promise<UserCredit> {
|
||||
const currentBalance = await this.getUserBalance(userId, platform);
|
||||
|
||||
if (currentBalance < amount) {
|
||||
throw new Error('积分不足');
|
||||
}
|
||||
|
||||
const newBalance = currentBalance - amount;
|
||||
|
||||
const creditRecord = this.creditRepository.create({
|
||||
userId,
|
||||
platform,
|
||||
type: CreditType.CONSUME,
|
||||
source,
|
||||
amount: -amount, // 负数表示扣除
|
||||
balance: newBalance,
|
||||
description: `消耗积分: ${source}`,
|
||||
referenceId,
|
||||
});
|
||||
|
||||
return this.creditRepository.save(creditRecord);
|
||||
}
|
||||
|
||||
// 退还积分
|
||||
async refundCredits(
|
||||
userId: string,
|
||||
platform: PlatformType,
|
||||
amount: number,
|
||||
source: CreditSource,
|
||||
referenceId?: string
|
||||
): Promise<UserCredit> {
|
||||
const currentBalance = await this.getUserBalance(userId, platform);
|
||||
const newBalance = currentBalance + amount;
|
||||
|
||||
const creditRecord = this.creditRepository.create({
|
||||
userId,
|
||||
platform,
|
||||
type: CreditType.REFUND,
|
||||
source,
|
||||
amount,
|
||||
balance: newBalance,
|
||||
description: `积分退还: ${source}`,
|
||||
referenceId,
|
||||
});
|
||||
|
||||
return this.creditRepository.save(creditRecord);
|
||||
}
|
||||
|
||||
// 获取积分历史记录
|
||||
async getCreditHistory(
|
||||
userId: string,
|
||||
platform: PlatformType,
|
||||
page: number = 1,
|
||||
limit: number = 20
|
||||
) {
|
||||
const [records, total] = await this.creditRepository.findAndCount({
|
||||
where: { userId, platform },
|
||||
order: { createdAt: 'DESC' },
|
||||
skip: (page - 1) * limit,
|
||||
take: limit,
|
||||
});
|
||||
|
||||
return {
|
||||
records,
|
||||
total,
|
||||
page,
|
||||
limit,
|
||||
totalPages: Math.ceil(total / limit),
|
||||
};
|
||||
}
|
||||
|
||||
// 新用户注册奖励
|
||||
async grantNewUserBonus(userId: string, platform: PlatformType): Promise<UserCredit> {
|
||||
const bonusAmount = 100; // 新用户奖励100积分
|
||||
|
||||
return this.addCredits(
|
||||
userId,
|
||||
platform,
|
||||
bonusAmount,
|
||||
CreditSource.MANUAL,
|
||||
'新用户注册奖励',
|
||||
'new_user_bonus'
|
||||
);
|
||||
}
|
||||
|
||||
// 每日签到奖励
|
||||
async grantDailyCheckIn(userId: string, platform: PlatformType, consecutiveDays: number): Promise<UserCredit> {
|
||||
// 连续签到奖励递增: 第1天5积分，第2天10积分，第7天及以上20积分
|
||||
let bonusAmount = 5;
|
||||
if (consecutiveDays >= 7) {
|
||||
bonusAmount = 20;
|
||||
} else if (consecutiveDays >= 3) {
|
||||
bonusAmount = 15;
|
||||
} else if (consecutiveDays >= 2) {
|
||||
bonusAmount = 10;
|
||||
}
|
||||
|
||||
return this.addCredits(
|
||||
userId,
|
||||
platform,
|
||||
bonusAmount,
|
||||
CreditSource.MANUAL,
|
||||
`每日签到奖励 (连续${consecutiveDays}天)`,
|
||||
`daily_checkin_${consecutiveDays}`
|
||||
);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2.2 广告服务实现
|
||||
```typescript
|
||||
// src/services/ad.service.ts
|
||||
import { Injectable } from '@nestjs/common';
|
||||
import { InjectRepository } from '@nestjs/typeorm';
|
||||
import { Repository } from 'typeorm';
|
||||
import { AdWatch, AdType, AdStatus } from '../entities/ad-watch.entity';
|
||||
import { CreditService } from './credit.service';
|
||||
import { PlatformType } from '../entities/platform-user.entity';
|
||||
import { CreditSource } from '../entities/user-credit.entity';
|
||||
|
||||
@Injectable()
|
||||
export class AdService {
|
||||
constructor(
|
||||
@InjectRepository(AdWatch)
|
||||
private readonly adWatchRepository: Repository<AdWatch>,
|
||||
private readonly creditService: CreditService,
|
||||
) {}
|
||||
|
||||
// 开始观看广告
|
||||
async startAdWatch(
|
||||
userId: string,
|
||||
platform: PlatformType,
|
||||
adType: AdType,
|
||||
adId: string,
|
||||
adUnitId?: string
|
||||
): Promise<AdWatch> {
|
||||
const adWatch = this.adWatchRepository.create({
|
||||
userId,
|
||||
platform,
|
||||
adType,
|
||||
adId,
|
||||
adUnitId,
|
||||
status: AdStatus.STARTED,
|
||||
});
|
||||
|
||||
return this.adWatchRepository.save(adWatch);
|
||||
}
|
||||
|
||||
// 完成观看广告
|
||||
async completeAdWatch(
|
||||
adWatchId: string,
|
||||
watchDuration: number,
|
||||
adData?: any
|
||||
): Promise<{ adWatch: AdWatch; creditReward: number }> {
|
||||
const adWatch = await this.adWatchRepository.findOne({
|
||||
where: { id: adWatchId },
|
||||
});
|
||||
|
||||
if (!adWatch) {
|
||||
throw new Error('广告观看记录不存在');
|
||||
}
|
||||
|
||||
if (adWatch.status !== AdStatus.STARTED) {
|
||||
throw new Error('广告状态异常');
|
||||
}
|
||||
|
||||
// 计算奖励积分
|
||||
const creditReward = this.calculateAdReward(adWatch.adType, watchDuration);
|
||||
|
||||
// 更新广告观看记录
|
||||
await this.adWatchRepository.update(adWatchId, {
|
||||
status: AdStatus.COMPLETED,
|
||||
watchDuration,
|
||||
rewardCredits: creditReward,
|
||||
adData,
|
||||
});
|
||||
|
||||
// 发放积分奖励
|
||||
if (creditReward > 0) {
|
||||
await this.creditService.addCredits(
|
||||
adWatch.userId,
|
||||
adWatch.platform,
|
||||
creditReward,
|
||||
CreditSource.AD_WATCH,
|
||||
`观看${adWatch.adType}广告奖励`,
|
||||
adWatchId
|
||||
);
|
||||
}
|
||||
|
||||
const updatedAdWatch = await this.adWatchRepository.findOne({
|
||||
where: { id: adWatchId },
|
||||
});
|
||||
|
||||
return {
|
||||
adWatch: updatedAdWatch,
|
||||
creditReward,
|
||||
};
|
||||
}
|
||||
|
||||
// 跳过广告
|
||||
async skipAdWatch(adWatchId: string, watchDuration: number): Promise<AdWatch> {
|
||||
await this.adWatchRepository.update(adWatchId, {
|
||||
status: AdStatus.SKIPPED,
|
||||
watchDuration,
|
||||
rewardCredits: 0, // 跳过广告无奖励
|
||||
});
|
||||
|
||||
return this.adWatchRepository.findOne({ where: { id: adWatchId } });
|
||||
}
|
||||
|
||||
// 广告观看失败
|
||||
async failAdWatch(adWatchId: string, errorMessage?: string): Promise<AdWatch> {
|
||||
await this.adWatchRepository.update(adWatchId, {
|
||||
status: AdStatus.FAILED,
|
||||
adData: { error: errorMessage },
|
||||
});
|
||||
|
||||
return this.adWatchRepository.findOne({ where: { id: adWatchId } });
|
||||
}
|
||||
|
||||
// 计算广告奖励积分
|
||||
private calculateAdReward(adType: AdType, watchDuration: number): number {
|
||||
// 不同类型广告的基础奖励
|
||||
const baseRewards = {
|
||||
[AdType.REWARDED]: 15, // 激励视频广告奖励最高
|
||||
[AdType.INTERSTITIAL]: 8, // 插屏广告中等奖励
|
||||
[AdType.BANNER]: 3, // 横幅广告奖励较低
|
||||
[AdType.NATIVE]: 5, // 原生广告奖励较低
|
||||
};
|
||||
|
||||
const baseReward = baseRewards[adType] || 5;
|
||||
|
||||
// 根据观看时长调整奖励
|
||||
if (adType === AdType.REWARDED) {
|
||||
// 激励视频需要观看完整才有奖励
|
||||
const minWatchTime = 15; // 最少观看15秒
|
||||
if (watchDuration < minWatchTime) {
|
||||
return 0;
|
||||
}
|
||||
}
|
||||
|
||||
return baseReward;
|
||||
}
|
||||
|
||||
// 获取用户广告观看历史
|
||||
async getUserAdHistory(
|
||||
userId: string,
|
||||
platform: PlatformType,
|
||||
page: number = 1,
|
||||
limit: number = 20
|
||||
) {
|
||||
const [records, total] = await this.adWatchRepository.findAndCount({
|
||||
where: { userId, platform },
|
||||
order: { createdAt: 'DESC' },
|
||||
skip: (page - 1) * limit,
|
||||
take: limit,
|
||||
});
|
||||
|
||||
return {
|
||||
records,
|
||||
total,
|
||||
page,
|
||||
limit,
|
||||
totalPages: Math.ceil(total / limit),
|
||||
};
|
||||
}
|
||||
|
||||
// 获取今日广告观看统计
|
||||
async getTodayAdStats(userId: string, platform: PlatformType) {
|
||||
const today = new Date();
|
||||
today.setHours(0, 0, 0, 0);
|
||||
const tomorrow = new Date(today);
|
||||
tomorrow.setDate(tomorrow.getDate() + 1);
|
||||
|
||||
const stats = await this.adWatchRepository
|
||||
.createQueryBuilder('ad_watch')
|
||||
.select('ad_watch.adType', 'adType')
|
||||
.addSelect('ad_watch.status', 'status')
|
||||
.addSelect('COUNT(*)', 'count')
|
||||
.addSelect('SUM(ad_watch.rewardCredits)', 'totalRewards')
|
||||
.where('ad_watch.userId = :userId', { userId })
|
||||
.andWhere('ad_watch.platform = :platform', { platform })
|
||||
.andWhere('ad_watch.createdAt >= :today', { today })
|
||||
.andWhere('ad_watch.createdAt < :tomorrow', { tomorrow })
|
||||
.groupBy('ad_watch.adType, ad_watch.status')
|
||||
.getRawMany();
|
||||
|
||||
return stats;
|
||||
}
|
||||
|
||||
// 检查广告观看限制
|
||||
async checkAdWatchLimit(userId: string, platform: PlatformType, adType: AdType): Promise<boolean> {
|
||||
const today = new Date();
|
||||
today.setHours(0, 0, 0, 0);
|
||||
const tomorrow = new Date(today);
|
||||
tomorrow.setDate(tomorrow.getDate() + 1);
|
||||
|
||||
// 每日观看限制
|
||||
const dailyLimits = {
|
||||
[AdType.REWARDED]: 20, // 激励视频每日最多20次
|
||||
[AdType.INTERSTITIAL]: 10, // 插屏广告每日最多10次
|
||||
[AdType.BANNER]: 50, // 横幅广告每日最多50次
|
||||
[AdType.NATIVE]: 30, // 原生广告每日最多30次
|
||||
};
|
||||
|
||||
const todayCount = await this.adWatchRepository.count({
|
||||
where: {
|
||||
userId,
|
||||
platform,
|
||||
adType,
|
||||
status: AdStatus.COMPLETED,
|
||||
createdAt: {
|
||||
$gte: today,
|
||||
$lt: tomorrow,
|
||||
} as any,
|
||||
},
|
||||
});
|
||||
|
||||
return todayCount < (dailyLimits[adType] || 10);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 3. API接口实现
|
||||
|
||||
### 3.1 积分相关接口
|
||||
```typescript
|
||||
// src/controllers/credit.controller.ts
|
||||
@ApiTags('💰 积分系统')
|
||||
@Controller('credits')
|
||||
export class CreditController {
|
||||
constructor(private readonly creditService: CreditService) {}
|
||||
|
||||
@Get('balance')
|
||||
@ApiOperation({ summary: '获取用户积分余额' })
|
||||
async getBalance(@CurrentUser() user: any) {
|
||||
const balance = await this.creditService.getUserBalance(user.id, user.platform);
|
||||
return { balance };
|
||||
}
|
||||
|
||||
@Get('history')
|
||||
@ApiOperation({ summary: '获取积分历史记录' })
|
||||
async getHistory(
|
||||
@CurrentUser() user: any,
|
||||
@Query('page') page: number = 1,
|
||||
@Query('limit') limit: number = 20
|
||||
) {
|
||||
return this.creditService.getCreditHistory(user.id, user.platform, page, limit);
|
||||
}
|
||||
|
||||
@Post('daily-checkin')
|
||||
@ApiOperation({ summary: '每日签到' })
|
||||
async dailyCheckIn(@CurrentUser() user: any) {
|
||||
// 这里需要实现签到逻辑，计算连续签到天数
|
||||
const consecutiveDays = 1; // 简化示例
|
||||
return this.creditService.grantDailyCheckIn(user.id, user.platform, consecutiveDays);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 广告相关接口
|
||||
```typescript
|
||||
// src/controllers/ad.controller.ts
|
||||
@ApiTags('📺 广告系统')
|
||||
@Controller('ads')
|
||||
export class AdController {
|
||||
constructor(private readonly adService: AdService) {}
|
||||
|
||||
@Post('watch/start')
|
||||
@ApiOperation({ summary: '开始观看广告' })
|
||||
async startWatch(@CurrentUser() user: any, @Body() startAdDto: StartAdWatchDto) {
|
||||
return this.adService.startAdWatch(
|
||||
user.id,
|
||||
user.platform,
|
||||
startAdDto.adType,
|
||||
startAdDto.adId,
|
||||
startAdDto.adUnitId
|
||||
);
|
||||
}
|
||||
|
||||
@Post('watch/:adWatchId/complete')
|
||||
@ApiOperation({ summary: '完成观看广告' })
|
||||
async completeWatch(
|
||||
@Param('adWatchId') adWatchId: string,
|
||||
@Body() completeAdDto: CompleteAdWatchDto
|
||||
) {
|
||||
return this.adService.completeAdWatch(
|
||||
adWatchId,
|
||||
completeAdDto.watchDuration,
|
||||
completeAdDto.adData
|
||||
);
|
||||
}
|
||||
|
||||
@Get('stats/today')
|
||||
@ApiOperation({ summary: '获取今日广告观看统计' })
|
||||
async getTodayStats(@CurrentUser() user: any) {
|
||||
return this.adService.getTodayAdStats(user.id, user.platform);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 4. 环境配置
|
||||
|
||||
```env
|
||||
# 积分系统配置
|
||||
NEW_USER_BONUS_CREDITS=100
|
||||
DAILY_CHECKIN_BASE_CREDITS=5
|
||||
MAX_DAILY_CHECKIN_CREDITS=20
|
||||
|
||||
# 广告奖励配置
|
||||
REWARDED_AD_CREDITS=15
|
||||
INTERSTITIAL_AD_CREDITS=8
|
||||
BANNER_AD_CREDITS=3
|
||||
NATIVE_AD_CREDITS=5
|
||||
|
||||
# 广告观看限制
|
||||
DAILY_REWARDED_AD_LIMIT=20
|
||||
DAILY_INTERSTITIAL_AD_LIMIT=10
|
||||
DAILY_BANNER_AD_LIMIT=50
|
||||
DAILY_NATIVE_AD_LIMIT=30
|
||||
|
||||
# AI生成积分消耗
|
||||
IMAGE_GENERATION_CREDITS=10
|
||||
VIDEO_GENERATION_CREDITS=50
|
||||
HIGH_QUALITY_MULTIPLIER=1.5
|
||||
```
|
||||
|
||||
这个积分和广告系统提供了完整的积分管理、广告观看奖励、每日限制等功能，支持多种广告类型和灵活的奖励机制。
|
||||
1737
docs/multi-platform-integration-solution.md
Normal file
1737
docs/multi-platform-integration-solution.md
Normal file
File diff suppressed because it is too large
Load Diff
508
docs/rabbitmq-configuration.md
Normal file
508
docs/rabbitmq-configuration.md
Normal file
@@ -0,0 +1,508 @@
|
||||
# RabbitMQ 配置指南
|
||||
|
||||
## 1. RabbitMQ 模块配置
|
||||
|
||||
### 1.1 RabbitMQ 模块设置
|
||||
```typescript
|
||||
// src/rabbitmq/rabbitmq.module.ts
|
||||
import { Module } from '@nestjs/common';
|
||||
import { ClientsModule, Transport } from '@nestjs/microservices';
|
||||
import { ConfigService } from '@nestjs/config';
|
||||
|
||||
@Module({
|
||||
imports: [
|
||||
ClientsModule.registerAsync([
|
||||
{
|
||||
name: 'RABBITMQ_SERVICE',
|
||||
useFactory: (configService: ConfigService) => ({
|
||||
transport: Transport.RMQ,
|
||||
options: {
|
||||
urls: [configService.get<string>('RABBITMQ_URL')],
|
||||
queue: 'main_queue',
|
||||
queueOptions: {
|
||||
durable: true,
|
||||
},
|
||||
socketOptions: {
|
||||
heartbeatIntervalInSeconds: 60,
|
||||
reconnectTimeInSeconds: 5,
|
||||
},
|
||||
},
|
||||
}),
|
||||
inject: [ConfigService],
|
||||
},
|
||||
]),
|
||||
],
|
||||
exports: [ClientsModule],
|
||||
})
|
||||
export class RabbitMQModule {}
|
||||
```
|
||||
|
||||
### 1.2 消息队列配置
|
||||
```typescript
|
||||
// src/config/queue.config.ts
|
||||
export const QueueConfig = {
|
||||
// 交换机配置
|
||||
exchanges: {
|
||||
USER: 'user.exchange',
|
||||
PAYMENT: 'payment.exchange',
|
||||
PUSH: 'push.exchange',
|
||||
PLATFORM: 'platform.exchange',
|
||||
},
|
||||
|
||||
// 队列配置
|
||||
queues: {
|
||||
// 用户相关队列
|
||||
USER_REGISTRATION: 'user.registration.queue',
|
||||
USER_LOGIN: 'user.login.queue',
|
||||
USER_UPDATE: 'user.update.queue',
|
||||
|
||||
// AI生成相关队列
|
||||
AI_GENERATION_TASK: 'ai.generation.task.queue',
|
||||
AI_GENERATION_COMPLETED: 'ai.generation.completed.queue',
|
||||
AI_GENERATION_FAILED: 'ai.generation.failed.queue',
|
||||
|
||||
// 积分系统队列
|
||||
CREDIT_REWARD: 'credit.reward.queue',
|
||||
CREDIT_CONSUME: 'credit.consume.queue',
|
||||
|
||||
// 广告系统队列
|
||||
AD_WATCH_COMPLETED: 'ad.watch.completed.queue',
|
||||
AD_REWARD_GRANTED: 'ad.reward.granted.queue',
|
||||
|
||||
// 平台同步队列
|
||||
PLATFORM_SYNC_USER: 'platform.sync.user.queue',
|
||||
PLATFORM_SYNC_DATA: 'platform.sync.data.queue',
|
||||
|
||||
// 扩展服务队列 (预留)
|
||||
EXTENSION_SERVICE: 'extension.service.queue',
|
||||
CUSTOM_EVENT: 'custom.event.queue',
|
||||
},
|
||||
|
||||
// 路由键配置
|
||||
routingKeys: {
|
||||
USER_REGISTERED: 'user.registered',
|
||||
USER_LOGIN_SUCCESS: 'user.login.success',
|
||||
USER_UPDATED: 'user.updated',
|
||||
|
||||
// AI生成相关路由键
|
||||
AI_GENERATION_TASK: 'ai.generation.task',
|
||||
AI_GENERATION_COMPLETED: 'ai.generation.completed',
|
||||
AI_GENERATION_FAILED: 'ai.generation.failed',
|
||||
|
||||
// 积分系统路由键
|
||||
CREDIT_REWARD: 'credit.reward',
|
||||
CREDIT_CONSUME: 'credit.consume',
|
||||
|
||||
// 广告系统路由键
|
||||
AD_WATCH_COMPLETED: 'ad.watch.completed',
|
||||
AD_REWARD_GRANTED: 'ad.reward.granted',
|
||||
|
||||
PLATFORM_SYNC: 'platform.sync',
|
||||
EXTENSION_EVENT: 'extension.event',
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
## 2. 消息生产者服务
|
||||
|
||||
```typescript
|
||||
// src/services/message-producer.service.ts
|
||||
import { Injectable, Inject } from '@nestjs/common';
|
||||
import { ClientProxy } from '@nestjs/microservices';
|
||||
import { QueueConfig } from '../config/queue.config';
|
||||
|
||||
export interface UserRegistrationMessage {
|
||||
userId: string;
|
||||
platform: string;
|
||||
userInfo: any;
|
||||
timestamp: Date;
|
||||
}
|
||||
|
||||
export interface ExtensionMessage {
|
||||
userId: string;
|
||||
platform: string;
|
||||
dataType: string;
|
||||
action: string; // 'create', 'update', 'delete'
|
||||
data: Record<string, any>;
|
||||
timestamp: Date;
|
||||
}
|
||||
|
||||
export interface GenerationTaskMessage {
|
||||
taskId: string;
|
||||
userId: string;
|
||||
platform: string;
|
||||
type: 'image' | 'video';
|
||||
templateCode?: string;
|
||||
inputParameters: Record<string, any>;
|
||||
timestamp: Date;
|
||||
}
|
||||
|
||||
export interface GenerationCompletedMessage {
|
||||
taskId: string;
|
||||
userId: string;
|
||||
platform: string;
|
||||
outputUrl: string;
|
||||
thumbnailUrl?: string;
|
||||
timestamp: Date;
|
||||
}
|
||||
|
||||
export interface GenerationFailedMessage {
|
||||
taskId: string;
|
||||
userId: string;
|
||||
platform: string;
|
||||
errorMessage: string;
|
||||
timestamp: Date;
|
||||
}
|
||||
|
||||
@Injectable()
|
||||
export class MessageProducerService {
|
||||
constructor(
|
||||
@Inject('RABBITMQ_SERVICE')
|
||||
private readonly client: ClientProxy,
|
||||
) {}
|
||||
|
||||
// 发送用户注册消息
|
||||
async sendUserRegistration(message: UserRegistrationMessage) {
|
||||
return this.client.emit(QueueConfig.routingKeys.USER_REGISTERED, message);
|
||||
}
|
||||
|
||||
// 发送用户更新消息
|
||||
async sendUserUpdate(message: UserRegistrationMessage) {
|
||||
return this.client.emit(QueueConfig.routingKeys.USER_UPDATED, message);
|
||||
}
|
||||
|
||||
// 发送平台同步消息
|
||||
async sendPlatformSync(data: any) {
|
||||
return this.client.emit(QueueConfig.routingKeys.PLATFORM_SYNC, data);
|
||||
}
|
||||
|
||||
// 发送扩展服务消息
|
||||
async sendExtensionEvent(message: ExtensionMessage) {
|
||||
return this.client.emit(QueueConfig.routingKeys.EXTENSION_EVENT, message);
|
||||
}
|
||||
|
||||
// AI生成相关消息
|
||||
async sendGenerationTask(message: GenerationTaskMessage) {
|
||||
return this.client.emit(QueueConfig.routingKeys.AI_GENERATION_TASK, message);
|
||||
}
|
||||
|
||||
async sendGenerationCompleted(message: GenerationCompletedMessage) {
|
||||
return this.client.emit(QueueConfig.routingKeys.AI_GENERATION_COMPLETED, message);
|
||||
}
|
||||
|
||||
async sendGenerationFailed(message: GenerationFailedMessage) {
|
||||
return this.client.emit(QueueConfig.routingKeys.AI_GENERATION_FAILED, message);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 3. 消息消费者服务
|
||||
|
||||
```typescript
|
||||
// src/services/message-consumer.service.ts
|
||||
import { Injectable } from '@nestjs/common';
|
||||
import { EventPattern, Payload } from '@nestjs/microservices';
|
||||
import { QueueConfig } from '../config/queue.config';
|
||||
import { UserService } from './user.service';
|
||||
import { PaymentService } from './payment.service';
|
||||
import { PushService } from './push.service';
|
||||
import { PlatformService } from './platform.service';
|
||||
|
||||
@Injectable()
|
||||
export class MessageConsumerService {
|
||||
constructor(
|
||||
private readonly userService: UserService,
|
||||
private readonly platformService: PlatformService,
|
||||
private readonly extensionService: ExtensionService,
|
||||
private readonly generationService: GenerationService,
|
||||
private readonly messageProducer: MessageProducerService,
|
||||
) {}
|
||||
|
||||
// 处理用户注册消息
|
||||
@EventPattern(QueueConfig.routingKeys.USER_REGISTERED)
|
||||
async handleUserRegistration(@Payload() data: UserRegistrationMessage) {
|
||||
try {
|
||||
console.log('Processing user registration:', data);
|
||||
|
||||
// 同步到其他平台
|
||||
await this.platformService.syncUserRegistration(data);
|
||||
|
||||
// 触发扩展服务处理
|
||||
await this.extensionService.handleUserRegistration(data);
|
||||
|
||||
console.log('User registration processed successfully');
|
||||
} catch (error) {
|
||||
console.error('Error processing user registration:', error);
|
||||
// 这里可以实现重试机制或死信队列
|
||||
}
|
||||
}
|
||||
|
||||
// 处理用户更新消息
|
||||
@EventPattern(QueueConfig.routingKeys.USER_UPDATED)
|
||||
async handleUserUpdate(@Payload() data: UserRegistrationMessage) {
|
||||
try {
|
||||
console.log('Processing user update:', data);
|
||||
|
||||
// 同步用户数据到各平台
|
||||
await this.platformService.syncUserUpdate(data);
|
||||
|
||||
// 触发扩展服务处理
|
||||
await this.extensionService.handleUserUpdate(data);
|
||||
|
||||
console.log('User update processed successfully');
|
||||
} catch (error) {
|
||||
console.error('Error processing user update:', error);
|
||||
}
|
||||
}
|
||||
|
||||
// 处理AI生成任务消息
|
||||
@EventPattern(QueueConfig.routingKeys.AI_GENERATION_TASK)
|
||||
async handleGenerationTask(@Payload() data: GenerationTaskMessage) {
|
||||
try {
|
||||
console.log('Processing AI generation task:', data);
|
||||
|
||||
// 调用AI生成服务处理任务
|
||||
await this.generationService.processGenerationTask(data.taskId);
|
||||
|
||||
console.log('AI generation task processed successfully');
|
||||
} catch (error) {
|
||||
console.error('Error processing AI generation task:', error);
|
||||
|
||||
// 发送失败消息
|
||||
await this.messageProducer.sendGenerationFailed({
|
||||
taskId: data.taskId,
|
||||
userId: data.userId,
|
||||
platform: data.platform,
|
||||
errorMessage: error.message,
|
||||
timestamp: new Date(),
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
// 处理AI生成完成消息
|
||||
@EventPattern(QueueConfig.routingKeys.AI_GENERATION_COMPLETED)
|
||||
async handleGenerationCompleted(@Payload() data: GenerationCompletedMessage) {
|
||||
try {
|
||||
console.log('Processing AI generation completed:', data);
|
||||
|
||||
// 可以在这里添加后续处理逻辑，如推送通知等
|
||||
// await this.pushService.sendGenerationCompleteNotification(data);
|
||||
|
||||
console.log('AI generation completed processed successfully');
|
||||
} catch (error) {
|
||||
console.error('Error processing AI generation completed:', error);
|
||||
}
|
||||
}
|
||||
|
||||
// 处理AI生成失败消息
|
||||
@EventPattern(QueueConfig.routingKeys.AI_GENERATION_FAILED)
|
||||
async handleGenerationFailed(@Payload() data: GenerationFailedMessage) {
|
||||
try {
|
||||
console.log('Processing AI generation failed:', data);
|
||||
|
||||
// 可以在这里添加失败处理逻辑，如推送错误通知等
|
||||
// await this.pushService.sendGenerationFailedNotification(data);
|
||||
|
||||
console.log('AI generation failed processed successfully');
|
||||
} catch (error) {
|
||||
console.error('Error processing AI generation failed:', error);
|
||||
}
|
||||
}
|
||||
|
||||
// 处理扩展服务消息
|
||||
@EventPattern(QueueConfig.routingKeys.EXTENSION_EVENT)
|
||||
async handleExtensionEvent(@Payload() data: ExtensionMessage) {
|
||||
try {
|
||||
console.log('Processing extension event:', data);
|
||||
|
||||
// 根据数据类型和操作类型处理
|
||||
await this.extensionService.handleExtensionEvent(data);
|
||||
|
||||
// 同步到相关平台
|
||||
await this.platformService.syncExtensionData(data);
|
||||
|
||||
console.log('Extension event processed successfully');
|
||||
} catch (error) {
|
||||
console.error('Error processing extension event:', error);
|
||||
}
|
||||
}
|
||||
|
||||
// 处理平台同步消息
|
||||
@EventPattern(QueueConfig.routingKeys.PLATFORM_SYNC)
|
||||
async handlePlatformSync(@Payload() data: any) {
|
||||
try {
|
||||
console.log('Processing platform sync:', data);
|
||||
|
||||
await this.platformService.syncData(data);
|
||||
|
||||
console.log('Platform sync processed successfully');
|
||||
} catch (error) {
|
||||
console.error('Error processing platform sync:', error);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 4. 在业务服务中使用消息队列
|
||||
|
||||
```typescript
|
||||
// src/services/user.service.ts
|
||||
import { Injectable } from '@nestjs/common';
|
||||
import { MessageProducerService } from './message-producer.service';
|
||||
|
||||
@Injectable()
|
||||
export class UserService {
|
||||
constructor(
|
||||
private readonly messageProducer: MessageProducerService,
|
||||
) {}
|
||||
|
||||
async registerUser(userData: any) {
|
||||
// 创建用户
|
||||
const user = await this.createUser(userData);
|
||||
|
||||
// 发送用户注册消息到队列
|
||||
await this.messageProducer.sendUserRegistration({
|
||||
userId: user.id,
|
||||
platform: userData.platform,
|
||||
userInfo: userData,
|
||||
timestamp: new Date(),
|
||||
});
|
||||
|
||||
return user;
|
||||
}
|
||||
|
||||
private async createUser(userData: any) {
|
||||
// 实际的用户创建逻辑
|
||||
return { id: 'user-id', ...userData };
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 5. 主应用模块配置
|
||||
|
||||
```typescript
|
||||
// src/app.module.ts
|
||||
import { Module } from '@nestjs/common';
|
||||
import { ConfigModule } from '@nestjs/config';
|
||||
import { RabbitMQModule } from './rabbitmq/rabbitmq.module';
|
||||
import { MessageProducerService } from './services/message-producer.service';
|
||||
import { MessageConsumerService } from './services/message-consumer.service';
|
||||
|
||||
@Module({
|
||||
imports: [
|
||||
ConfigModule.forRoot({
|
||||
isGlobal: true,
|
||||
}),
|
||||
RabbitMQModule,
|
||||
],
|
||||
providers: [
|
||||
MessageProducerService,
|
||||
MessageConsumerService,
|
||||
],
|
||||
exports: [MessageProducerService],
|
||||
})
|
||||
export class AppModule {}
|
||||
```
|
||||
|
||||
## 6. 错误处理和重试机制
|
||||
|
||||
```typescript
|
||||
// src/decorators/retry.decorator.ts
|
||||
export function Retry(maxRetries: number = 3, delay: number = 1000) {
|
||||
return function (target: any, propertyName: string, descriptor: PropertyDescriptor) {
|
||||
const method = descriptor.value;
|
||||
|
||||
descriptor.value = async function (...args: any[]) {
|
||||
let lastError: any;
|
||||
|
||||
for (let i = 0; i <= maxRetries; i++) {
|
||||
try {
|
||||
return await method.apply(this, args);
|
||||
} catch (error) {
|
||||
lastError = error;
|
||||
|
||||
if (i < maxRetries) {
|
||||
console.log(`Retry ${i + 1}/${maxRetries} for ${propertyName}:`, error.message);
|
||||
await new Promise(resolve => setTimeout(resolve, delay * Math.pow(2, i)));
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
throw lastError;
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## 7. 队列监控和管理
|
||||
|
||||
```typescript
|
||||
// src/services/queue-monitor.service.ts
|
||||
import { Injectable } from '@nestjs/common';
|
||||
import * as amqp from 'amqplib';
|
||||
|
||||
@Injectable()
|
||||
export class QueueMonitorService {
|
||||
private connection: amqp.Connection;
|
||||
|
||||
async getQueueInfo(queueName: string) {
|
||||
const channel = await this.connection.createChannel();
|
||||
const queueInfo = await channel.checkQueue(queueName);
|
||||
await channel.close();
|
||||
|
||||
return {
|
||||
queue: queueName,
|
||||
messageCount: queueInfo.messageCount,
|
||||
consumerCount: queueInfo.consumerCount,
|
||||
};
|
||||
}
|
||||
|
||||
async purgeQueue(queueName: string) {
|
||||
const channel = await this.connection.createChannel();
|
||||
await channel.purgeQueue(queueName);
|
||||
await channel.close();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 8. Docker Compose 配置
|
||||
|
||||
```yaml
|
||||
# docker-compose.yml
|
||||
version: '3.8'
|
||||
services:
|
||||
rabbitmq:
|
||||
image: rabbitmq:3-management-alpine
|
||||
container_name: rabbitmq
|
||||
environment:
|
||||
RABBITMQ_DEFAULT_USER: admin
|
||||
RABBITMQ_DEFAULT_PASS: password
|
||||
RABBITMQ_DEFAULT_VHOST: /
|
||||
ports:
|
||||
- "5672:5672" # AMQP端口
|
||||
- "15672:15672" # 管理界面端口
|
||||
volumes:
|
||||
- rabbitmq_data:/var/lib/rabbitmq
|
||||
healthcheck:
|
||||
test: ["CMD", "rabbitmq-diagnostics", "ping"]
|
||||
interval: 30s
|
||||
timeout: 10s
|
||||
retries: 5
|
||||
|
||||
volumes:
|
||||
rabbitmq_data:
|
||||
```
|
||||
|
||||
## 9. 环境变量配置
|
||||
|
||||
```env
|
||||
# RabbitMQ配置
|
||||
RABBITMQ_URL=amqp://admin:password@localhost:5672
|
||||
RABBITMQ_USER=admin
|
||||
RABBITMQ_PASSWORD=password
|
||||
RABBITMQ_VHOST=/
|
||||
RABBITMQ_HEARTBEAT=60
|
||||
RABBITMQ_RECONNECT_TIME=5
|
||||
```
|
||||
|
||||
这个配置提供了完整的RabbitMQ集成方案，包括消息生产者、消费者、错误处理和监控功能。
|
||||
600
docs/swagger-api-documentation.md
Normal file
600
docs/swagger-api-documentation.md
Normal file
@@ -0,0 +1,600 @@
|
||||
# Swagger API 文档配置指南
|
||||
|
||||
## 1. Swagger 基础配置
|
||||
|
||||
### 1.1 安装依赖
|
||||
```bash
|
||||
pnpm add @nestjs/swagger swagger-ui-express
|
||||
pnpm add -D @types/swagger-ui-express
|
||||
```
|
||||
|
||||
### 1.2 基础配置文件
|
||||
```typescript
|
||||
// src/config/swagger.config.ts
|
||||
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
|
||||
import { INestApplication } from '@nestjs/common';
|
||||
|
||||
export function setupSwagger(app: INestApplication): void {
|
||||
const config = new DocumentBuilder()
|
||||
.setTitle('多平台小程序统一后台API')
|
||||
.setDescription(`
|
||||
## 功能特性
|
||||
- 🔐 统一用户认证 (微信/支付宝/百度/字节跳动等)
|
||||
- 🔄 平台数据同步 (RabbitMQ异步处理)
|
||||
- 🧩 可扩展架构 (支持后续添加支付、推送等功能)
|
||||
- 📊 灵活数据存储 (PostgreSQL + JSONB)
|
||||
|
||||
## 认证方式
|
||||
使用JWT Bearer Token进行API认证
|
||||
|
||||
## 响应格式
|
||||
所有API响应都遵循统一格式：
|
||||
\`\`\`json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "success",
|
||||
"data": {},
|
||||
"timestamp": 1703001000000,
|
||||
"traceId": "trace-uuid"
|
||||
}
|
||||
\`\`\`
|
||||
`)
|
||||
.setVersion('1.0.0')
|
||||
.setContact('开发团队', 'https://example.com', 'dev@example.com')
|
||||
.setLicense('MIT', 'https://opensource.org/licenses/MIT')
|
||||
.addBearerAuth(
|
||||
{
|
||||
type: 'http',
|
||||
scheme: 'bearer',
|
||||
bearerFormat: 'JWT',
|
||||
name: 'JWT',
|
||||
description: 'Enter JWT token',
|
||||
in: 'header',
|
||||
},
|
||||
'JWT-auth',
|
||||
)
|
||||
.addTag('🔐 用户管理', '用户注册、登录、信息管理')
|
||||
.addTag('🔄 平台适配', '各平台特定接口和数据同步')
|
||||
.addTag('🧩 扩展服务', '预留的扩展功能接口')
|
||||
.addTag('📊 数据统计', '业务数据统计和分析')
|
||||
.addServer('http://localhost:3000', '开发环境')
|
||||
.addServer('https://api-dev.example.com', '测试环境')
|
||||
.addServer('https://api.example.com', '生产环境')
|
||||
.build();
|
||||
|
||||
const document = SwaggerModule.createDocument(app, config, {
|
||||
operationIdFactory: (controllerKey: string, methodKey: string) => methodKey,
|
||||
});
|
||||
|
||||
SwaggerModule.setup('api/docs', app, document, {
|
||||
swaggerOptions: {
|
||||
persistAuthorization: true,
|
||||
tagsSorter: 'alpha',
|
||||
operationsSorter: 'alpha',
|
||||
docExpansion: 'none',
|
||||
filter: true,
|
||||
showRequestDuration: true,
|
||||
},
|
||||
customSiteTitle: '多平台API文档',
|
||||
customfavIcon: '/favicon.ico',
|
||||
customJs: [
|
||||
'https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/4.15.5/swagger-ui-bundle.min.js',
|
||||
],
|
||||
customCssUrl: [
|
||||
'https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/4.15.5/swagger-ui.min.css',
|
||||
],
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
## 2. 通用DTO定义
|
||||
|
||||
### 2.1 统一响应格式
|
||||
```typescript
|
||||
// src/dto/common-response.dto.ts
|
||||
import { ApiProperty } from '@nestjs/swagger';
|
||||
|
||||
export class CommonResponseDto<T = any> {
|
||||
@ApiProperty({ description: '响应状态码', example: 200 })
|
||||
code: number;
|
||||
|
||||
@ApiProperty({ description: '响应消息', example: 'success' })
|
||||
message: string;
|
||||
|
||||
@ApiProperty({ description: '响应数据' })
|
||||
data: T;
|
||||
|
||||
@ApiProperty({ description: '时间戳', example: 1703001000000 })
|
||||
timestamp: number;
|
||||
|
||||
@ApiProperty({ description: '追踪ID', example: 'trace-uuid-123' })
|
||||
traceId: string;
|
||||
}
|
||||
|
||||
export class PaginationDto {
|
||||
@ApiProperty({ description: '页码', example: 1, minimum: 1 })
|
||||
page: number;
|
||||
|
||||
@ApiProperty({ description: '每页数量', example: 10, minimum: 1, maximum: 100 })
|
||||
limit: number;
|
||||
}
|
||||
|
||||
export class PaginationResponseDto<T = any> {
|
||||
@ApiProperty({ description: '数据列表' })
|
||||
items: T[];
|
||||
|
||||
@ApiProperty({ description: '总数量', example: 100 })
|
||||
total: number;
|
||||
|
||||
@ApiProperty({ description: '当前页码', example: 1 })
|
||||
page: number;
|
||||
|
||||
@ApiProperty({ description: '每页数量', example: 10 })
|
||||
limit: number;
|
||||
|
||||
@ApiProperty({ description: '总页数', example: 10 })
|
||||
totalPages: number;
|
||||
}
|
||||
```
|
||||
|
||||
### 2.2 平台枚举定义
|
||||
```typescript
|
||||
// src/dto/platform.dto.ts
|
||||
import { ApiProperty } from '@nestjs/swagger';
|
||||
|
||||
export enum PlatformType {
|
||||
WECHAT = 'wechat',
|
||||
ALIPAY = 'alipay',
|
||||
BAIDU = 'baidu',
|
||||
BYTEDANCE = 'bytedance',
|
||||
JD = 'jd',
|
||||
QQ = 'qq',
|
||||
FEISHU = 'feishu',
|
||||
KUAISHOU = 'kuaishou',
|
||||
H5 = 'h5',
|
||||
RN = 'rn'
|
||||
}
|
||||
|
||||
export const PlatformDescriptions = {
|
||||
[PlatformType.WECHAT]: '微信小程序',
|
||||
[PlatformType.ALIPAY]: '支付宝小程序',
|
||||
[PlatformType.BAIDU]: '百度智能小程序',
|
||||
[PlatformType.BYTEDANCE]: '字节跳动小程序',
|
||||
[PlatformType.JD]: '京东小程序',
|
||||
[PlatformType.QQ]: 'QQ小程序',
|
||||
[PlatformType.FEISHU]: '飞书小程序',
|
||||
[PlatformType.KUAISHOU]: '快手小程序',
|
||||
[PlatformType.H5]: 'H5应用',
|
||||
[PlatformType.RN]: 'React Native应用',
|
||||
};
|
||||
```
|
||||
|
||||
## 3. 用户管理API文档
|
||||
|
||||
### 3.1 用户登录DTO
|
||||
```typescript
|
||||
// src/dto/user.dto.ts
|
||||
import { ApiProperty } from '@nestjs/swagger';
|
||||
import { IsString, IsEnum, IsOptional, IsObject } from 'class-validator';
|
||||
import { PlatformType } from './platform.dto';
|
||||
|
||||
export class UserLoginDto {
|
||||
@ApiProperty({
|
||||
description: '平台类型',
|
||||
enum: PlatformType,
|
||||
example: PlatformType.WECHAT,
|
||||
enumName: 'PlatformType',
|
||||
})
|
||||
@IsEnum(PlatformType)
|
||||
platform: PlatformType;
|
||||
|
||||
@ApiProperty({
|
||||
description: '平台授权码/临时登录凭证',
|
||||
example: '081234567890abcdef',
|
||||
minLength: 1,
|
||||
maxLength: 200,
|
||||
})
|
||||
@IsString()
|
||||
code: string;
|
||||
|
||||
@ApiProperty({
|
||||
description: '加密用户数据 (微信小程序专用)',
|
||||
required: false,
|
||||
example: 'encrypted_user_data_string',
|
||||
})
|
||||
@IsOptional()
|
||||
@IsString()
|
||||
encryptedData?: string;
|
||||
|
||||
@ApiProperty({
|
||||
description: '加密向量 (微信小程序专用)',
|
||||
required: false,
|
||||
example: 'iv_string',
|
||||
})
|
||||
@IsOptional()
|
||||
@IsString()
|
||||
iv?: string;
|
||||
|
||||
@ApiProperty({
|
||||
description: '额外的平台特定数据',
|
||||
required: false,
|
||||
type: 'object',
|
||||
example: { sessionKey: 'session_key_value' },
|
||||
})
|
||||
@IsOptional()
|
||||
@IsObject()
|
||||
extra?: Record<string, any>;
|
||||
}
|
||||
|
||||
export class UserInfoDto {
|
||||
@ApiProperty({ description: '用户ID', example: 'user-uuid-123' })
|
||||
id: string;
|
||||
|
||||
@ApiProperty({ description: '统一用户ID', example: 'unified-user-123' })
|
||||
unifiedUserId: string;
|
||||
|
||||
@ApiProperty({ description: '用户昵称', example: '张三' })
|
||||
nickname: string;
|
||||
|
||||
@ApiProperty({
|
||||
description: '头像URL',
|
||||
example: 'https://example.com/avatar.jpg'
|
||||
})
|
||||
avatarUrl: string;
|
||||
|
||||
@ApiProperty({
|
||||
description: '手机号',
|
||||
example: '13800138000',
|
||||
required: false
|
||||
})
|
||||
phone?: string;
|
||||
|
||||
@ApiProperty({
|
||||
description: '邮箱',
|
||||
example: 'user@example.com',
|
||||
required: false
|
||||
})
|
||||
email?: string;
|
||||
|
||||
@ApiProperty({ description: '用户状态', example: 1 })
|
||||
status: number;
|
||||
|
||||
@ApiProperty({ description: '创建时间', example: '2023-12-01T10:00:00Z' })
|
||||
createdAt: Date;
|
||||
|
||||
@ApiProperty({ description: '更新时间', example: '2023-12-01T10:00:00Z' })
|
||||
updatedAt: Date;
|
||||
}
|
||||
|
||||
export class UserLoginResponseDto {
|
||||
@ApiProperty({
|
||||
description: 'JWT访问令牌',
|
||||
example: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
|
||||
})
|
||||
token: string;
|
||||
|
||||
@ApiProperty({
|
||||
description: '刷新令牌',
|
||||
example: 'refresh_token_string_here',
|
||||
})
|
||||
refreshToken: string;
|
||||
|
||||
@ApiProperty({
|
||||
description: '用户信息',
|
||||
type: UserInfoDto,
|
||||
})
|
||||
userInfo: UserInfoDto;
|
||||
|
||||
@ApiProperty({
|
||||
description: '平台特定数据',
|
||||
type: 'object',
|
||||
required: false,
|
||||
example: { openid: 'wx_openid_123' },
|
||||
})
|
||||
platformSpecific?: Record<string, any>;
|
||||
}
|
||||
```
|
||||
|
||||
## 4. 扩展服务API文档
|
||||
|
||||
### 4.1 扩展数据相关DTO
|
||||
```typescript
|
||||
// src/dto/extension.dto.ts
|
||||
import { ApiProperty } from '@nestjs/swagger';
|
||||
import { IsString, IsEnum, IsOptional, IsObject } from 'class-validator';
|
||||
import { PlatformType } from './platform.dto';
|
||||
|
||||
export class CreateExtensionDataDto {
|
||||
@ApiProperty({
|
||||
description: '用户ID',
|
||||
example: 'user-uuid-123',
|
||||
})
|
||||
@IsString()
|
||||
userId: string;
|
||||
|
||||
@ApiProperty({
|
||||
description: '平台类型',
|
||||
enum: PlatformType,
|
||||
example: PlatformType.WECHAT,
|
||||
})
|
||||
@IsEnum(PlatformType)
|
||||
platform: PlatformType;
|
||||
|
||||
@ApiProperty({
|
||||
description: '数据类型',
|
||||
example: 'custom',
|
||||
maxLength: 50,
|
||||
})
|
||||
@IsString()
|
||||
dataType: string;
|
||||
|
||||
@ApiProperty({
|
||||
description: '外部引用ID',
|
||||
required: false,
|
||||
example: 'ref-123456',
|
||||
maxLength: 100,
|
||||
})
|
||||
@IsOptional()
|
||||
@IsString()
|
||||
referenceId?: string;
|
||||
|
||||
@ApiProperty({
|
||||
description: '扩展数据内容',
|
||||
type: 'object',
|
||||
example: {
|
||||
customField1: 'value1',
|
||||
customField2: 'value2',
|
||||
settings: { enabled: true }
|
||||
},
|
||||
})
|
||||
@IsObject()
|
||||
data: Record<string, any>;
|
||||
|
||||
@ApiProperty({
|
||||
description: '元数据',
|
||||
required: false,
|
||||
type: 'object',
|
||||
example: { source: 'api', version: '1.0' },
|
||||
})
|
||||
@IsOptional()
|
||||
@IsObject()
|
||||
metadata?: Record<string, any>;
|
||||
}
|
||||
|
||||
export class ExtensionDataResponseDto {
|
||||
@ApiProperty({ description: '扩展数据ID', example: 'ext-uuid-123' })
|
||||
id: string;
|
||||
|
||||
@ApiProperty({ description: '用户ID', example: 'user-uuid-123' })
|
||||
userId: string;
|
||||
|
||||
@ApiProperty({
|
||||
description: '平台类型',
|
||||
enum: PlatformType,
|
||||
example: PlatformType.WECHAT,
|
||||
})
|
||||
platform: PlatformType;
|
||||
|
||||
@ApiProperty({ description: '数据类型', example: 'custom' })
|
||||
dataType: string;
|
||||
|
||||
@ApiProperty({ description: '外部引用ID', example: 'ref-123456' })
|
||||
referenceId: string;
|
||||
|
||||
@ApiProperty({
|
||||
description: '扩展数据内容',
|
||||
type: 'object',
|
||||
})
|
||||
data: Record<string, any>;
|
||||
|
||||
@ApiProperty({
|
||||
description: '元数据',
|
||||
type: 'object',
|
||||
})
|
||||
metadata: Record<string, any>;
|
||||
|
||||
@ApiProperty({ description: '状态', example: 'active' })
|
||||
status: string;
|
||||
|
||||
@ApiProperty({ description: '创建时间', example: '2023-12-01T10:00:00Z' })
|
||||
createdAt: Date;
|
||||
|
||||
@ApiProperty({ description: '更新时间', example: '2023-12-01T10:00:00Z' })
|
||||
updatedAt: Date;
|
||||
}
|
||||
```
|
||||
|
||||
## 5. 错误响应文档
|
||||
|
||||
### 5.1 通用错误响应
|
||||
```typescript
|
||||
// src/dto/error-response.dto.ts
|
||||
import { ApiProperty } from '@nestjs/swagger';
|
||||
|
||||
export class ErrorResponseDto {
|
||||
@ApiProperty({ description: '错误状态码', example: 400 })
|
||||
code: number;
|
||||
|
||||
@ApiProperty({ description: '错误消息', example: '请求参数错误' })
|
||||
message: string;
|
||||
|
||||
@ApiProperty({ description: '错误数据', example: null })
|
||||
data: null;
|
||||
|
||||
@ApiProperty({ description: '时间戳', example: 1703001000000 })
|
||||
timestamp: number;
|
||||
|
||||
@ApiProperty({ description: '追踪ID', example: 'trace-uuid-123' })
|
||||
traceId: string;
|
||||
|
||||
@ApiProperty({
|
||||
description: '详细错误信息',
|
||||
required: false,
|
||||
example: ['字段验证失败'],
|
||||
})
|
||||
details?: string[];
|
||||
}
|
||||
|
||||
// 常用错误响应示例
|
||||
export const CommonErrorResponses = {
|
||||
BadRequest: {
|
||||
status: 400,
|
||||
description: '请求参数错误',
|
||||
type: ErrorResponseDto,
|
||||
},
|
||||
Unauthorized: {
|
||||
status: 401,
|
||||
description: '未授权访问',
|
||||
type: ErrorResponseDto,
|
||||
},
|
||||
Forbidden: {
|
||||
status: 403,
|
||||
description: '禁止访问',
|
||||
type: ErrorResponseDto,
|
||||
},
|
||||
NotFound: {
|
||||
status: 404,
|
||||
description: '资源不存在',
|
||||
type: ErrorResponseDto,
|
||||
},
|
||||
InternalServerError: {
|
||||
status: 500,
|
||||
description: '服务器内部错误',
|
||||
type: ErrorResponseDto,
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
## 6. 装饰器使用示例
|
||||
|
||||
### 6.1 Controller装饰器
|
||||
```typescript
|
||||
// src/decorators/api-common-responses.decorator.ts
|
||||
import { applyDecorators } from '@nestjs/common';
|
||||
import { ApiResponse } from '@nestjs/swagger';
|
||||
import { CommonErrorResponses } from '../dto/error-response.dto';
|
||||
|
||||
export function ApiCommonResponses() {
|
||||
return applyDecorators(
|
||||
ApiResponse(CommonErrorResponses.BadRequest),
|
||||
ApiResponse(CommonErrorResponses.Unauthorized),
|
||||
ApiResponse(CommonErrorResponses.InternalServerError),
|
||||
);
|
||||
}
|
||||
|
||||
export function ApiAuthResponses() {
|
||||
return applyDecorators(
|
||||
ApiResponse(CommonErrorResponses.Unauthorized),
|
||||
ApiResponse(CommonErrorResponses.Forbidden),
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### 6.2 使用示例
|
||||
```typescript
|
||||
// src/controllers/user.controller.ts
|
||||
import { Controller, Post, Body, Get, UseGuards } from '@nestjs/common';
|
||||
import {
|
||||
ApiTags,
|
||||
ApiOperation,
|
||||
ApiResponse,
|
||||
ApiBearerAuth,
|
||||
} from '@nestjs/swagger';
|
||||
import { ApiCommonResponses, ApiAuthResponses } from '../decorators/api-common-responses.decorator';
|
||||
|
||||
@ApiTags('🔐 用户管理')
|
||||
@Controller('users')
|
||||
@ApiCommonResponses()
|
||||
export class UserController {
|
||||
@Post('login')
|
||||
@ApiOperation({
|
||||
summary: '用户登录',
|
||||
description: '支持多平台用户登录，返回JWT令牌和用户信息',
|
||||
})
|
||||
@ApiResponse({
|
||||
status: 200,
|
||||
description: '登录成功',
|
||||
type: UserLoginResponseDto,
|
||||
})
|
||||
async login(@Body() loginDto: UserLoginDto) {
|
||||
return this.userService.login(loginDto);
|
||||
}
|
||||
|
||||
@Get('profile')
|
||||
@UseGuards(JwtAuthGuard)
|
||||
@ApiBearerAuth('JWT-auth')
|
||||
@ApiAuthResponses()
|
||||
@ApiOperation({
|
||||
summary: '获取用户信息',
|
||||
description: '获取当前登录用户的详细信息',
|
||||
})
|
||||
@ApiResponse({
|
||||
status: 200,
|
||||
description: '获取成功',
|
||||
type: UserInfoDto,
|
||||
})
|
||||
async getProfile(@CurrentUser() user: any) {
|
||||
return this.userService.getProfile(user.id);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 7. 环境配置
|
||||
|
||||
### 7.1 开发环境配置
|
||||
```typescript
|
||||
// src/main.ts
|
||||
import { NestFactory } from '@nestjs/core';
|
||||
import { ValidationPipe } from '@nestjs/common';
|
||||
import { AppModule } from './app.module';
|
||||
import { setupSwagger } from './config/swagger.config';
|
||||
|
||||
async function bootstrap() {
|
||||
const app = await NestFactory.create(AppModule);
|
||||
|
||||
// 全局验证管道
|
||||
app.useGlobalPipes(new ValidationPipe({
|
||||
whitelist: true,
|
||||
forbidNonWhitelisted: true,
|
||||
transform: true,
|
||||
}));
|
||||
|
||||
// API前缀
|
||||
app.setGlobalPrefix('api/v1');
|
||||
|
||||
// CORS配置
|
||||
app.enableCors({
|
||||
origin: process.env.NODE_ENV === 'production'
|
||||
? ['https://example.com']
|
||||
: true,
|
||||
credentials: true,
|
||||
});
|
||||
|
||||
// 仅在非生产环境启用Swagger
|
||||
if (process.env.NODE_ENV !== 'production') {
|
||||
setupSwagger(app);
|
||||
}
|
||||
|
||||
const port = process.env.PORT || 3000;
|
||||
await app.listen(port);
|
||||
|
||||
console.log('🚀 应用启动成功!');
|
||||
console.log(`📖 API文档地址: http://localhost:${port}/api/docs`);
|
||||
}
|
||||
bootstrap();
|
||||
```
|
||||
|
||||
## 8. 访问API文档
|
||||
|
||||
启动应用后，访问以下地址查看API文档：
|
||||
|
||||
- **开发环境**: http://localhost:3000/api/docs
|
||||
- **JSON格式**: http://localhost:3000/api/docs-json
|
||||
- **YAML格式**: http://localhost:3000/api/docs-yaml
|
||||
|
||||
API文档包含：
|
||||
- 📋 完整的接口列表和参数说明
|
||||
- 🔐 JWT认证测试功能
|
||||
- 📝 请求/响应示例
|
||||
- 🧪 在线接口测试功能
|
||||
- 📊 数据模型定义
|
||||
1668
docs/template-management-system.md
Normal file
1668
docs/template-management-system.md
Normal file
File diff suppressed because it is too large
Load Diff
195
docs/template-system-summary.md
Normal file
195
docs/template-system-summary.md
Normal file
@@ -0,0 +1,195 @@
|
||||
# AI模板管理系统总结 - 面向对象设计
|
||||
|
||||
## 🎯 设计理念
|
||||
|
||||
您的建议非常正确！使用面向对象的设计模式比数据库方案更加优雅和实用：
|
||||
|
||||
```typescript
|
||||
export abstract class Template<TInput, TOutput> {}
|
||||
export abstract class ImageGenerateTemplate extends Template {}
|
||||
export abstract class VideoGenerateTemplate extends Template {}
|
||||
export class TemplateManager {}
|
||||
```
|
||||
|
||||
## 🏗️ 核心架构
|
||||
|
||||
### 1. 抽象类层次结构
|
||||
```
|
||||
Template (基础抽象类)
|
||||
├── ImageGenerateTemplate (图片生成抽象类)
|
||||
│ ├── OutfitChangeTemplate (换装模板)
|
||||
│ ├── StyleTransferTemplate (风格转换模板)
|
||||
│ └── BackgroundReplaceTemplate (背景替换模板)
|
||||
└── VideoGenerateTemplate (视频生成抽象类)
|
||||
├── ObjectRemovalTemplate (抠图模板)
|
||||
└── MotionGenerateTemplate (动作生成模板)
|
||||
```
|
||||
|
||||
### 2. 核心组件
|
||||
- **Template**: 基础抽象类，定义统一接口
|
||||
- **TemplateManager**: 模板管理器，负责注册和执行
|
||||
- **TemplateFactory**: 模板工厂，创建所有模板实例
|
||||
- **TemplateService**: 业务服务层，集成积分系统
|
||||
|
||||
## ✅ 面向对象方案的优势
|
||||
|
||||
### 🔒 类型安全
|
||||
```typescript
|
||||
// 编译时就能发现错误
|
||||
const template: ImageGenerateTemplate = new OutfitChangeTemplate();
|
||||
const result = await template.execute(input, context); // 类型检查
|
||||
```
|
||||
|
||||
### 🧬 代码复用
|
||||
```typescript
|
||||
// 基类提供通用功能
|
||||
export abstract class ImageGenerateTemplate extends Template {
|
||||
// 通用的图片参数验证
|
||||
async validateInput(input: ImageGenerateInput): Promise<string[]> {
|
||||
// 共享的验证逻辑
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 🚀 易于扩展
|
||||
```typescript
|
||||
// 添加新模板只需继承和实现
|
||||
@Injectable()
|
||||
export class NewTemplate extends ImageGenerateTemplate {
|
||||
readonly metadata = { /* 模板信息 */ };
|
||||
|
||||
async execute(input, context) {
|
||||
// 具体实现
|
||||
}
|
||||
|
||||
getParameterDefinitions() {
|
||||
// 参数定义
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 🛠️ IDE支持
|
||||
- 完整的代码提示和自动补全
|
||||
- 重构时自动更新所有引用
|
||||
- 编译时错误检查
|
||||
- 调试时的完整类型信息
|
||||
|
||||
## 📊 与数据库方案对比
|
||||
|
||||
| 特性 | 面向对象方案 | 数据库方案 |
|
||||
|------|-------------|-----------|
|
||||
| **类型安全** | ✅ 编译时检查 | ❌ 运行时检查 |
|
||||
| **代码复用** | ✅ 继承机制 | ❌ 需要额外逻辑 |
|
||||
| **扩展性** | ✅ 新增类即可 | ❌ 需要数据库迁移 |
|
||||
| **性能** | ✅ 内存中执行 | ❌ 数据库查询开销 |
|
||||
| **维护性** | ✅ 代码即文档 | ❌ 需要维护数据结构 |
|
||||
| **版本控制** | ✅ Git管理 | ❌ 数据库版本管理复杂 |
|
||||
| **测试** | ✅ 单元测试友好 | ❌ 需要数据库环境 |
|
||||
| **部署** | ✅ 无状态部署 | ❌ 需要数据库同步 |
|
||||
|
||||
## 🎨 具体实现示例
|
||||
|
||||
### 换装模板
|
||||
```typescript
|
||||
@Injectable()
|
||||
export class OutfitChangeTemplate extends ImageGenerateTemplate {
|
||||
readonly metadata: TemplateMetadata = {
|
||||
code: 'outfit_change_v1',
|
||||
name: '智能换装',
|
||||
description: '上传人物图片，描述想要的服装，AI自动生成换装效果',
|
||||
category: '换装',
|
||||
creditCost: 15,
|
||||
version: '1.0.0',
|
||||
};
|
||||
|
||||
async execute(input: OutfitChangeInput, context: TemplateExecutionContext) {
|
||||
const prompt = this.buildPrompt(input);
|
||||
const result = await this.stabilityAI.imageToImage({
|
||||
prompt,
|
||||
initImage: input.inputImage,
|
||||
strength: 0.8,
|
||||
});
|
||||
return this.formatOutput(result);
|
||||
}
|
||||
|
||||
getParameterDefinitions(): ParameterDefinition[] {
|
||||
return [
|
||||
{
|
||||
key: 'inputImage',
|
||||
displayName: '人物图片',
|
||||
type: ParameterType.IMAGE,
|
||||
validation: { required: true },
|
||||
order: 1,
|
||||
},
|
||||
{
|
||||
key: 'clothingDescription',
|
||||
displayName: '服装描述',
|
||||
type: ParameterType.STRING,
|
||||
validation: { required: true, minLength: 3, maxLength: 200 },
|
||||
order: 2,
|
||||
},
|
||||
];
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🔧 使用方式
|
||||
|
||||
### 前端调用
|
||||
```typescript
|
||||
// 统一的调用接口，不管底层是什么AI模型
|
||||
const result = await fetch('/api/templates/outfit_change_v1/execute', {
|
||||
method: 'POST',
|
||||
body: JSON.stringify({
|
||||
inputImage: 'data:image/jpeg;base64,...',
|
||||
clothingDescription: '红色连衣裙',
|
||||
style: 'elegant'
|
||||
})
|
||||
});
|
||||
```
|
||||
|
||||
### 添加新模板
|
||||
```typescript
|
||||
// 1. 创建模板类
|
||||
export class MyTemplate extends ImageGenerateTemplate {
|
||||
// 实现抽象方法
|
||||
}
|
||||
|
||||
// 2. 在工厂中注册
|
||||
export class TemplateFactory {
|
||||
createAllTemplates(): Template[] {
|
||||
return [
|
||||
new OutfitChangeTemplate(),
|
||||
new MyTemplate(), // 添加新模板
|
||||
];
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🎯 核心价值
|
||||
|
||||
### 1. **统一抽象**
|
||||
不同的AI模型（Stability AI、RunwayML、OpenAI等）通过统一的模板接口调用，前端无需关心底层实现差异。
|
||||
|
||||
### 2. **类型安全**
|
||||
TypeScript的类型系统确保编译时就能发现接口不匹配、参数错误等问题。
|
||||
|
||||
### 3. **易于维护**
|
||||
每个模板都是独立的类，修改一个模板不会影响其他模板，代码结构清晰。
|
||||
|
||||
### 4. **快速扩展**
|
||||
添加新的AI生成功能只需要继承对应的抽象类，实现几个方法即可。
|
||||
|
||||
### 5. **测试友好**
|
||||
每个模板类都可以独立进行单元测试，不需要复杂的数据库环境。
|
||||
|
||||
## 🚀 总结
|
||||
|
||||
面向对象的模板管理系统完美解决了您提出的问题：
|
||||
|
||||
1. **消除调用方式不一致**: 通过抽象类统一接口
|
||||
2. **消除参数结果不一致**: 通过类型定义标准化
|
||||
3. **简化模板管理**: 通过代码而非数据库管理
|
||||
4. **提升开发效率**: 通过继承和多态减少重复代码
|
||||
|
||||
这个设计既保持了灵活性，又提供了强类型保障，是一个非常优雅的解决方案！
|
||||
Reference in New Issue
Block a user