kybernus 3.0.1 → 3.2.0

package/templates/ecommerce/apps/api/src/modules/checkout/__tests__/checkout.service.unit.test.ts

@@ -0,0 +1,191 @@
+/**
+ * CheckoutService — Unit Tests
+ * StripeAdapter and repositories are mocked.
+ */
+
+import { CheckoutService } from '../checkout.service';
+import { IOrderRepository } from '../order.repository';
+import { IPaymentAdapter, PaymentError } from '../../payment/payment.port';
+import { ICartRepository } from '../../cart/cart.repository';
+import { IProductRepository } from '../../catalog/product.repository';
+import { CartEntity } from '../../cart/cart.entity';
+import { OrderEntity } from '../order.entity';
+
+function makeCartWithItems(userId = 'user-1') {
+  return CartEntity.create(userId)
+    .addItem({
+      variantId: 'var-1',
+      productId: 'prod-1',
+      name: 'Camiseta',
+      sku: 'CAM-P',
+      price: 99.9,
+      qty: 2,
+      image: null,
+    });
+}
+
+function makeProduct(stock = 10) {
+  return {
+    id: 'prod-1',
+    name: 'Camiseta',
+    slug: 'camiseta',
+    price: 99.9,
+    images: [],
+    variants: [{ id: 'var-1', sku: 'CAM-P', size: 'P', color: 'Branco', stock, price: null, productId: 'prod-1' }],
+    toRecord: jest.fn().mockReturnThis(),
+  };
+}
+
+describe('CheckoutService — Unit', () => {
+  let orderRepo: jest.Mocked<IOrderRepository>;
+  let paymentAdapter: jest.Mocked<IPaymentAdapter>;
+  let cartRepo: jest.Mocked<ICartRepository>;
+  let productRepo: jest.Mocked<IProductRepository>;
+  let service: CheckoutService;
+
+  beforeEach(() => {
+    orderRepo = {
+      findById: jest.fn(),
+      findByPaymentIntentId: jest.fn(),
+      findByUserId: jest.fn(),
+      findAll: jest.fn(),
+      create: jest.fn(),
+      update: jest.fn(),
+    } as jest.Mocked<IOrderRepository>;
+
+    paymentAdapter = {
+      createPaymentIntent: jest.fn(),
+    } as jest.Mocked<IPaymentAdapter>;
+
+    cartRepo = {
+      findByUserId: jest.fn(),
+      findBySessionId: jest.fn(),
+      save: jest.fn(),
+      delete: jest.fn(),
+    } as jest.Mocked<ICartRepository>;
+
+    productRepo = {
+      findById: jest.fn(),
+      findBySlug: jest.fn(),
+      findAll: jest.fn(),
+      search: jest.fn(),
+      create: jest.fn(),
+      update: jest.fn(),
+      softDelete: jest.fn(),
+      updateVariantStock: jest.fn(),
+      slugExists: jest.fn(),
+    } as jest.Mocked<IProductRepository>;
+
+    service = new CheckoutService(orderRepo, paymentAdapter, cartRepo, productRepo);
+  });
+
+  it('deve criar Order a partir de um Cart válido', async () => {
+    const cart = makeCartWithItems();
+    cartRepo.findByUserId.mockResolvedValue(cart);
+    productRepo.findById.mockResolvedValue(makeProduct() as never);
+    paymentAdapter.createPaymentIntent.mockResolvedValue({ id: 'pi_1', clientSecret: 'secret_1' });
+    orderRepo.create.mockImplementation(async (o) => o);
+    cartRepo.delete.mockResolvedValue();
+
+    const result = await service.checkout({ userId: 'user-1', shippingCost: 18.5, shippingAddress: null });
+
+    expect(result.orderId).toBeDefined();
+    expect(result.clientSecret).toBe('secret_1');
+    expect(orderRepo.create).toHaveBeenCalled();
+  });
+
+  it('deve chamar stripeAdapter.createPaymentIntent com valor correto', async () => {
+    const cart = makeCartWithItems(); // 2 × 99.9 = 199.8 + 18.5 shipping = 218.3
+    cartRepo.findByUserId.mockResolvedValue(cart);
+    productRepo.findById.mockResolvedValue(makeProduct() as never);
+    paymentAdapter.createPaymentIntent.mockResolvedValue({ id: 'pi_2', clientSecret: 'secret_2' });
+    orderRepo.create.mockImplementation(async (o) => o);
+    cartRepo.delete.mockResolvedValue();
+
+    await service.checkout({ userId: 'user-1', shippingCost: 18.5, shippingAddress: null });
+
+    expect(paymentAdapter.createPaymentIntent).toHaveBeenCalledWith(
+      expect.closeTo(218.3, 1),
+      'brl',
+      expect.any(Object),
+    );
+  });
+
+  it('deve decrementar estoque dos produtos ao confirmar pedido', async () => {
+    const cart = makeCartWithItems(); // qty=2
+    cartRepo.findByUserId.mockResolvedValue(cart);
+    productRepo.findById.mockResolvedValue(makeProduct() as never);
+    paymentAdapter.createPaymentIntent.mockResolvedValue({ id: 'pi_3', clientSecret: 'secret_3' });
+    orderRepo.create.mockImplementation(async (o) => o);
+    cartRepo.delete.mockResolvedValue();
+
+    await service.checkout({ userId: 'user-1', shippingCost: 0, shippingAddress: null });
+
+    expect(productRepo.updateVariantStock).toHaveBeenCalledWith('prod-1', 'var-1', expect.any(Number));
+  });
+
+  it('deve limpar o carrinho após criação do pedido bem-sucedida', async () => {
+    const cart = makeCartWithItems();
+    cartRepo.findByUserId.mockResolvedValue(cart);
+    productRepo.findById.mockResolvedValue(makeProduct() as never);
+    paymentAdapter.createPaymentIntent.mockResolvedValue({ id: 'pi_4', clientSecret: 's4' });
+    orderRepo.create.mockImplementation(async (o) => o);
+    cartRepo.delete.mockResolvedValue();
+
+    await service.checkout({ userId: 'user-1', shippingCost: 0, shippingAddress: null });
+
+    expect(cartRepo.delete).toHaveBeenCalledWith({ userId: 'user-1' });
+  });
+
+  it('deve fazer rollback de estoque se stripe.createPaymentIntent lançar erro', async () => {
+    const cart = makeCartWithItems();
+    cartRepo.findByUserId.mockResolvedValue(cart);
+    productRepo.findById.mockResolvedValue(makeProduct() as never);
+    orderRepo.create.mockImplementation(async (o) => o);
+    // Simulate Stripe error after stock has been decremented
+    productRepo.updateVariantStock.mockResolvedValue(undefined as never);
+    paymentAdapter.createPaymentIntent.mockRejectedValue(new PaymentError('card_declined', 'Cartão recusado'));
+
+    await expect(
+      service.checkout({ userId: 'user-1', shippingCost: 0, shippingAddress: null }),
+    ).rejects.toThrow(PaymentError);
+
+    // Stock rollback: updateVariantStock called twice (decrement + restore)
+    expect(productRepo.updateVariantStock).toHaveBeenCalledTimes(2);
+  });
+
+  it('deve incluir frete selecionado no total enviado ao Stripe', async () => {
+    const cart = makeCartWithItems(); // subtotal = 199.8
+    cartRepo.findByUserId.mockResolvedValue(cart);
+    productRepo.findById.mockResolvedValue(makeProduct() as never);
+    paymentAdapter.createPaymentIntent.mockResolvedValue({ id: 'pi_5', clientSecret: 's5' });
+    orderRepo.create.mockImplementation(async (o) => o);
+    cartRepo.delete.mockResolvedValue();
+
+    await service.checkout({ userId: 'user-1', shippingCost: 32, shippingAddress: null });
+
+    expect(paymentAdapter.createPaymentIntent).toHaveBeenCalledWith(
+      expect.closeTo(231.8, 1),
+      'brl',
+      expect.any(Object),
+    );
+  });
+
+  it('deve lançar erro se algum item tiver estoque insuficiente no checkout', async () => {
+    const cart = makeCartWithItems(); // qty=2
+    cartRepo.findByUserId.mockResolvedValue(cart);
+    productRepo.findById.mockResolvedValue(makeProduct(1) as never); // only 1 in stock
+
+    await expect(
+      service.checkout({ userId: 'user-1', shippingCost: 0, shippingAddress: null }),
+    ).rejects.toThrow('Estoque insuficiente');
+  });
+
+  it('deve lançar erro se o carrinho estiver vazio', async () => {
+    cartRepo.findByUserId.mockResolvedValue(CartEntity.create('user-1'));
+
+    await expect(
+      service.checkout({ userId: 'user-1', shippingCost: 0, shippingAddress: null }),
+    ).rejects.toThrow('vazio');
+  });
+});

package/templates/ecommerce/apps/api/src/modules/checkout/__tests__/order.prisma.repository.test.ts

@@ -0,0 +1,150 @@
+import { PrismaClient } from '@prisma/client';
+import { PrismaOrderRepository } from '../order.prisma.repository';
+import { OrderEntity } from '../order.entity';
+
+const db = new PrismaClient();
+const repo = new PrismaOrderRepository(db);
+
+async function cleanDb() {
+  await db.orderItem.deleteMany();
+  await db.order.deleteMany();
+}
+
+beforeAll(async () => {
+  await db.$connect();
+});
+
+afterAll(async () => {
+  await cleanDb();
+  await db.$disconnect();
+});
+
+beforeEach(async () => {
+  await cleanDb();
+});
+
+function makeOrder(userId = 'user-123') {
+  return OrderEntity.create({
+    userId,
+    items: [
+      {
+        id: crypto.randomUUID(),
+        variantId: 'variant-1',
+        productId: 'product-1',
+        name: 'Test Product',
+        sku: 'SKU-001',
+        price: 50.0,
+        qty: 2,
+        image: null,
+      },
+    ],
+    subtotal: 100.0,
+    discount: 0,
+    shippingCost: 10.0,
+    tax: 5.0,
+    total: 115.0,
+    couponCode: null,
+    paymentIntentId: null,
+    shippingAddress: { line1: '123 Main St', city: 'São Paulo', country: 'BR' },
+  });
+}
+
+describe('PrismaOrderRepository', () => {
+  it('create: deve persistir pedido com itens', async () => {
+    const order = makeOrder();
+    const saved = await repo.create(order);
+
+    expect(saved.id).toBe(order.id);
+    expect(saved.status).toBe('PENDING');
+    expect(saved.total).toBe(115.0);
+    expect(saved.items).toHaveLength(1);
+    expect(saved.items[0]!.sku).toBe('SKU-001');
+  });
+
+  it('findById: deve retornar null para id inexistente', async () => {
+    const found = await repo.findById('00000000-0000-0000-0000-000000000000');
+    expect(found).toBeNull();
+  });
+
+  it('findById: deve reconstituir pedido com itens', async () => {
+    const order = makeOrder();
+    await repo.create(order);
+
+    const found = await repo.findById(order.id);
+    expect(found).not.toBeNull();
+    expect(found!.id).toBe(order.id);
+    expect(found!.items).toHaveLength(1);
+    expect(found!.shippingAddress).toEqual({
+      line1: '123 Main St',
+      city: 'São Paulo',
+      country: 'BR',
+    });
+  });
+
+  it('findByPaymentIntentId: deve retornar pedido pelo paymentIntentId', async () => {
+    const order = makeOrder().withPaymentIntentId('pi_test_abc123');
+    await repo.create(order);
+
+    const found = await repo.findByPaymentIntentId('pi_test_abc123');
+    expect(found).not.toBeNull();
+    expect(found!.paymentIntentId).toBe('pi_test_abc123');
+  });
+
+  it('update: deve persistir mudança de status', async () => {
+    const order = makeOrder();
+    await repo.create(order);
+
+    const paid = order.pay();
+    await repo.update(paid);
+
+    const fetched = await repo.findById(order.id);
+    expect(fetched!.status).toBe('PAID');
+  });
+
+  it('findByUserId: deve retornar pedidos do usuário com paginação', async () => {
+    const userId = 'user-pagination-test';
+    await Promise.all([
+      repo.create(makeOrder(userId)),
+      repo.create(makeOrder(userId)),
+      repo.create(makeOrder(userId)),
+    ]);
+
+    const page1 = await repo.findByUserId(userId, { limit: 2 });
+    expect(page1.items).toHaveLength(2);
+    expect(page1.nextCursor).not.toBeNull();
+
+    const page2 = await repo.findByUserId(userId, {
+      cursor: page1.nextCursor!,
+      limit: 2,
+    });
+    expect(page2.items).toHaveLength(1);
+    expect(page2.nextCursor).toBeNull();
+  });
+
+  it('findAll: deve filtrar por status', async () => {
+    const o1 = makeOrder();
+    const o2 = makeOrder();
+    await repo.create(o1);
+    await repo.create(o2);
+    await repo.update(o1.pay());
+
+    const { items } = await repo.findAll({ status: 'PAID' });
+    expect(items).toHaveLength(1);
+    expect(items[0]!.status).toBe('PAID');
+  });
+
+  it('update: deve persistir trackingCode no pedido enviado', async () => {
+    const order = makeOrder().withPaymentIntentId('pi_track_test');
+    await repo.create(order);
+
+    const paid = order.pay();
+    await repo.update(paid);
+
+    const shipped = paid.ship('TRACK-001');
+    await repo.update(shipped);
+
+    const fetched = await repo.findById(order.id);
+    expect(fetched!.status).toBe('SHIPPED');
+    expect(fetched!.trackingCode).toBe('TRACK-001');
+  });
+});

package/templates/ecommerce/apps/api/src/modules/checkout/checkout.controller.ts

@@ -0,0 +1,59 @@
+import { Request, Response, NextFunction } from 'express';
+import { z } from 'zod';
+import { checkoutRegistry } from './checkout.registry';
+import { AppError } from '../../shared/errors/AppError';
+
+// ── Zod schemas ──────────────────────────────────────────────────────────────
+const checkoutSchema = z.object({
+  shippingCost: z.number().min(0),
+  shippingAddress: z
+    .record(z.string(), z.string())
+    .nullable()
+    .optional()
+    .transform((v) => v ?? null),
+});
+
+// ── POST /api/checkout ───────────────────────────────────────────────────────
+export async function checkout(
+  req: Request,
+  res: Response,
+  next: NextFunction,
+): Promise<void> {
+  try {
+    const user = req.user as { id: string };
+    const dto = checkoutSchema.parse(req.body);
+
+    const result = await checkoutRegistry.checkoutService.checkout({
+      userId: user.id,
+      shippingCost: dto.shippingCost,
+      shippingAddress: dto.shippingAddress ?? null,
+    });
+
+    res.status(201).json(result);
+  } catch (err) {
+    next(err);
+  }
+}
+
+// ── POST /api/checkout/webhook ───────────────────────────────────────────────
+export async function webhook(
+  req: Request,
+  res: Response,
+  next: NextFunction,
+): Promise<void> {
+  try {
+    const signature = req.headers['stripe-signature'];
+    if (!signature || typeof signature !== 'string') {
+      throw new AppError('Header stripe-signature ausente', 400);
+    }
+
+    // req.body is a Buffer when using express.raw()
+    const payload =
+      Buffer.isBuffer(req.body) ? req.body.toString('utf-8') : JSON.stringify(req.body);
+
+    await checkoutRegistry.webhookHandler.handleEvent(payload, signature);
+    res.status(200).json({ received: true });
+  } catch (err) {
+    next(err);
+  }
+}

package/templates/ecommerce/apps/api/src/modules/checkout/checkout.registry.ts

@@ -0,0 +1 @@
+export * from '../../infrastructure/config/registry/checkout.registry';

package/templates/ecommerce/apps/api/src/modules/checkout/checkout.routes.ts

@@ -0,0 +1,18 @@
+import { Router } from 'express';
+import express from 'express';
+import { authenticate } from '../../shared/middlewares/authenticate';
+import * as checkoutController from './checkout.controller';
+
+const router = Router();
+
+// POST /api/checkout — create order and payment intent
+router.post('/', authenticate, checkoutController.checkout);
+
+// POST /api/checkout/webhook — Stripe webhook (raw body required for signature verification)
+router.post(
+  '/webhook',
+  express.raw({ type: 'application/json' }),
+  checkoutController.webhook,
+);
+
+export default router;

package/templates/ecommerce/apps/api/src/modules/checkout/checkout.service.ts

@@ -0,0 +1 @@
+export * from '../../application/checkout/checkout.service';

package/templates/ecommerce/apps/api/src/modules/checkout/order.entity.ts

@@ -0,0 +1 @@
+export * from '../../domain/checkout/order.entity';

package/templates/ecommerce/apps/api/src/modules/checkout/order.prisma.repository.ts

@@ -0,0 +1 @@
+export * from '../../infrastructure/persistence/prisma/checkout/order.prisma.repository';

package/templates/ecommerce/apps/api/src/modules/checkout/order.repository.ts

@@ -0,0 +1,2 @@
+export * from '../../domain/checkout/order.repository';
+export * from '../../infrastructure/persistence/in-memory/order.memory.repository';

package/templates/ecommerce/apps/api/src/modules/checkout/tax.service.ts

@@ -0,0 +1,9 @@
+/**
+ * TaxService — Pluggable tax calculator scaffold.
+ * Currently returns 0 tax. Replace with real Brazilian tax rules as needed.
+ */
+export class TaxService {
+  calculate(_subtotal: number, _region?: string): number {
+    return 0;
+  }
+}

package/templates/ecommerce/apps/api/src/modules/orders/__tests__/order.entity.unit.test.ts

@@ -0,0 +1,68 @@
+/**
+ * Order Entity — State Machine Unit Tests (Phase 5)
+ */
+import { OrderEntity } from '../../checkout/order.entity';
+
+function makeOrder() {
+  return OrderEntity.create({
+    userId: 'user-1',
+    items: [],
+    subtotal: 100,
+    discount: 0,
+    shippingCost: 10,
+    tax: 0,
+    total: 110,
+    couponCode: null,
+    paymentIntentId: null,
+    shippingAddress: null,
+  });
+}
+
+describe('Order Entity — State Machine', () => {
+  it('estado inicial deve ser PENDING', () => {
+    const order = makeOrder();
+    expect(order.status).toBe('PENDING');
+  });
+
+  it('PENDING → PAID: deve ser permitido', () => {
+    const order = makeOrder().pay();
+    expect(order.status).toBe('PAID');
+  });
+
+  it('PENDING → SHIPPED: deve lançar InvalidTransitionError', () => {
+    const order = makeOrder();
+    expect(() => order.ship()).toThrow();
+  });
+
+  it('PAID → SHIPPED: deve ser permitido', () => {
+    const order = makeOrder().pay().ship();
+    expect(order.status).toBe('SHIPPED');
+  });
+
+  it('SHIPPED → DELIVERED: deve ser permitido', () => {
+    const order = makeOrder().pay().ship().deliver();
+    expect(order.status).toBe('DELIVERED');
+  });
+
+  it('PENDING → CANCELLED: deve ser permitido', () => {
+    const order = makeOrder().cancel();
+    expect(order.status).toBe('CANCELLED');
+  });
+
+  it('DELIVERED → CANCELLED: deve lançar InvalidTransitionError', () => {
+    const order = makeOrder().pay().ship().deliver();
+    expect(() => order.cancel()).toThrow();
+  });
+
+  it('deve registrar timestamp de cada transição de estado', () => {
+    const before = new Date();
+    const order = makeOrder().pay();
+    expect(order.updatedAt.getTime()).toBeGreaterThanOrEqual(before.getTime());
+  });
+
+  it('deve aceitar trackingCode ao transicionar para SHIPPED', () => {
+    const order = makeOrder().pay().ship('TRACK-001');
+    expect(order.status).toBe('SHIPPED');
+    expect(order.trackingCode).toBe('TRACK-001');
+  });
+});