AI 파이프라인 실패 시 결제 안전성 설계: 선차감-환불 패턴과 멱등 트랜잭션

// energy.constants.ts — 행동력 정책 (단일 소스)
export const ENERGY_CONSTANTS = {
  DAILY_ALLOWANCE: 30,   // 일일 지급
  MAX_CARRYOVER: 10,     // 이월 상한
  AUTO_CHARGE_AMOUNT: 10, // 젬으로 충전 시 행동력
  COST_PER_ACTION: 2,    // 메시지당 소비
} as const;

// gem-costs.ts — 젬 소비 단가 (단일 소스)
export const GEM_COST: Partial<Record<GemTransactionReason, number>> = {
  ENERGY_CHARGE: 20,            // 행동력 자동 충전
  AFFINITY_BOOST: 5,            // 호감도 부스터
  STORY_UNLOCK: 100,            // 스토리 해금
  PREMIUM_CHARACTER_UNLOCK: 50, // 프리미엄 캐릭터 해금
  TALK_ROOM_UNLOCK: 50,         // 토크룸 해금
  EXTENDED_MEMORY: 30,          // 확장 메모리
};

// energy.service.ts — 행동력 소비 (Redis 락 + 원자적 차감)
async consumeEnergy(userId: string) {
  // 분산 락: 동일 사용자의 동시 차감 방지
  const lockKey = `energy:consume:${userId}`;
  const locked = await this.redis.set(lockKey, '1', { ex: 5, nx: true });
  if (!locked) {
    throw new HttpException('처리 중입니다', HttpStatus.TOO_MANY_REQUESTS);
  }

  try {
    let wallet = await this.getOrCreateEnergy(userId);

    // 잔액 충분 → 원자적 차감 (WHERE balance >= cost)
    if (wallet.balance >= cost) {
      const result = await this.prisma.$queryRawUnsafe<{ balance: number }[]>(
        `UPDATE energy_wallets
         SET balance = balance - $1, updated_at = NOW()
         WHERE user_id = $2 AND balance >= $1
         RETURNING balance`,
        cost, userId,
      );
      if (result.length > 0) {
        return { energy: result[0].balance, gemCharged: false };
      }
    }

    // 잔액 부족 → 젬 20개 자동 소비 → 행동력 10 충전
    await this.gemsService.consume(userId, GemTransactionReason.ENERGY_CHARGE);
    const chargedBalance = wallet.balance + ENERGY_CONSTANTS.AUTO_CHARGE_AMOUNT - cost;
    await this.prisma.energyWallet.update({
      where: { userId },
      data: { balance: chargedBalance },
    });
    return { energy: chargedBalance, gemCharged: true };
  } finally {
    await this.redis.del(lockKey); // 락 해제
  }
}

// chat.controller.ts — 입력 필터 차단 시 환불 (BIL-016)
if (inputCheck.flagged) {
  let energyRefunded = false;
  let gemRefunded = false;
  if (energyResult) {
    try {
      await this.energyService.refundEnergy(userId, ENERGY_CONSTANTS.COST_PER_ACTION);
      energyRefunded = true;
      // 젬 자동 충전이 있었다면 젬도 환불
      if (energyResult.gemCharged) {
        await this.gemsService.refund(
          userId, GemTransactionReason.ENERGY_CHARGE, sessionId,
        );
        gemRefunded = true;
      }
    } catch (refundError) {
      this.logger.error(`Input filter refund failed for user ${userId}:`, refundError);
    }
  }
  // SSE 에러 이벤트에 환불 결과 포함
  res.write(`event: error\ndata: ${JSON.stringify({
    message: energyRefunded
      ? gemRefunded
        ? '부적절한 내용이 포함되어 있어 전송할 수 없습니다. 행동력과 젬이 환불되었습니다.'
        : '부적절한 내용이 포함되어 있어 전송할 수 없습니다. 행동력이 환불되었습니다.'
      : '부적절한 내용이 포함되어 있어 전송할 수 없습니다.',
    code: 'INPUT_FILTER_BLOCKED',
    energyRefunded,
    gemRefunded,
  })}\n\n`);
}

// chat.controller.ts — 파이프라인 실패 시 환불
catch (error) {
  this.logger.error(`Pipeline error for session ${sessionId}:`, error);

  let energyRefunded = false;
  let gemRefunded = false;

  if (energyResult) {
    try {
      await this.energyService.refundEnergy(userId, ENERGY_CONSTANTS.COST_PER_ACTION);
      energyRefunded = true;
      if (energyResult.gemCharged) {
        await this.gemsService.refund(userId, GemTransactionReason.ENERGY_CHARGE, sessionId);
        gemRefunded = true;
      }
    } catch (refundError) {
      this.logger.error(`Refund failed for user ${userId}:`, refundError);
    }
  }
}

// gems.service.ts — 환불 (트랜잭션 내 원자적 처리)
async refund(userId: string, reason: GemTransactionReason, referenceId?: string) {
  const cost = GEM_COST[reason]; // 20 (ENERGY_CHARGE)

  return this.prisma.$transaction(async (tx) => {
    const wallet = await tx.gemWallet.findUnique({ where: { userId } });

    // 원자적 잔액 복원
    const result = await tx.$queryRawUnsafe<{ balance: number }[]>(
      `UPDATE gem_wallets SET balance = balance + $1, updated_at = NOW()
       WHERE user_id = $2 RETURNING balance`,
      cost, userId,
    );

    // 환불 트랜잭션 기록 (referenceId로 추적)
    await tx.gemTransaction.create({
      data: {
        walletId: wallet.id,
        type: GemTransactionType.REFUND,
        amount: cost,
        balanceAfter: result[0].balance,
        reason: GemTransactionReason.REFUND,
        referenceId, // sessionId — 어떤 세션에서 발생한 환불인지 추적
        description: 'AI 응답 실패로 인한 행동력 충전 환불',
      },
    });
    return { balance: result[0].balance };
  });
}

// chat.controller.ts — 환불 실패 시 로깅 (Sentry가 자동 캡처)
} catch (refundError) {
  this.logger.error(`Refund failed for user ${userId}:`, refundError);
  // SentryGlobalFilter가 500 에러로 캡처 → 알림 발생
}

// SSE 에러 이벤트 페이로드
{
  message: 'AI 응답 생성에 실패했습니다. 행동력과 젬이 환불되었습니다.',
  code: 'AI_GENERATION_FAILED',  // | 'INPUT_FILTER_BLOCKED' | 'INSUFFICIENT_GEMS'
  energyRefunded: true,
  gemRefunded: true,
}