@su-record/vibe 2.5.12 → 2.5.13

package/skills/commerce-patterns.md

@@ -0,0 +1,361 @@
+---
+name: commerce-patterns
+description: "E-commerce domain patterns - cart, payment, inventory with transaction safety"
+triggers: [commerce, ecommerce, cart, payment, checkout, inventory, stock, order, pg, toss, stripe]
+priority: 70
+---
+# Commerce Patterns Skill
+
+E-commerce domain patterns for reliable transactions.
+
+## When to Use
+
+- Shopping cart implementation
+- Payment integration (PG, Stripe, Toss)
+- Inventory/stock management
+- Order processing systems
+
+## Core Patterns
+
+### 1. Cart (Shopping Cart)
+
+#### State Model
+```typescript
+interface CartItem {
+  productId: string;
+  variantId?: string;
+  quantity: number;
+  price: number;           // Snapshot at add time
+  originalPrice: number;   // For comparison
+  addedAt: Date;
+}
+
+interface Cart {
+  id: string;
+  userId?: string;         // null for guest
+  sessionId: string;       // For guest merge
+  items: CartItem[];
+  couponCode?: string;
+  updatedAt: Date;
+  expiresAt: Date;         // Cart expiration
+}
+```
+
+#### Key Patterns
+
+| Pattern | Description |
+|---------|-------------|
+| **Guest → User Merge** | Merge localStorage cart on login |
+| **Price Snapshot** | Store price at add time, revalidate at checkout |
+| **Expiration** | Clear abandoned carts after N days |
+| **Validation** | Check stock/price at checkout entry |
+
+#### Implementation
+```typescript
+class CartService {
+  async addItem(cartId: string, item: AddItemRequest): Promise<Cart> {
+    // 1. Validate product exists and in stock
+    const product = await this.productService.get(item.productId);
+    if (!product || product.stock < item.quantity) {
+      throw new OutOfStockError();
+    }
+
+    // 2. Snapshot current price
+    const cartItem: CartItem = {
+      ...item,
+      price: product.currentPrice,
+      originalPrice: product.originalPrice,
+      addedAt: new Date(),
+    };
+
+    // 3. Add or update quantity
+    return this.cartRepository.upsertItem(cartId, cartItem);
+  }
+
+  async mergeGuestCart(userId: string, sessionId: string): Promise<Cart> {
+    const guestCart = await this.cartRepository.findBySession(sessionId);
+    const userCart = await this.cartRepository.findByUser(userId);
+
+    if (!guestCart) return userCart;
+
+    // Merge: user cart takes priority for duplicates
+    const merged = this.mergeItems(userCart.items, guestCart.items);
+    await this.cartRepository.delete(guestCart.id);
+
+    return this.cartRepository.update(userCart.id, { items: merged });
+  }
+}
+```
+
+### 2. Payment
+
+#### State Machine
+```
+PENDING → PROCESSING → AUTHORIZED → CAPTURED → COMPLETED
+                    ↘ FAILED
+                    ↘ CANCELED
+COMPLETED → REFUND_REQUESTED → REFUNDED (partial/full)
+```
+
+#### Idempotency Pattern (Critical)
+```typescript
+interface PaymentRequest {
+  orderId: string;
+  amount: number;
+  currency: string;
+  idempotencyKey: string;  // REQUIRED: `order_${orderId}_${timestamp}`
+  paymentMethod: PaymentMethod;
+}
+
+class PaymentService {
+  async processPayment(request: PaymentRequest): Promise<PaymentResult> {
+    // 1. Check idempotency - prevent duplicate charges
+    const existing = await this.paymentRepository.findByIdempotencyKey(
+      request.idempotencyKey
+    );
+    if (existing) {
+      return existing.result;  // Return cached result
+    }
+
+    // 2. Create payment record (PENDING)
+    const payment = await this.paymentRepository.create({
+      ...request,
+      status: 'PENDING',
+    });
+
+    try {
+      // 3. Call PG adapter
+      const pgResult = await this.pgAdapter.authorize(request);
+
+      // 4. Update status
+      return this.paymentRepository.update(payment.id, {
+        status: pgResult.success ? 'AUTHORIZED' : 'FAILED',
+        pgTransactionId: pgResult.transactionId,
+        result: pgResult,
+      });
+    } catch (error) {
+      await this.paymentRepository.update(payment.id, {
+        status: 'FAILED',
+        error: error.message,
+      });
+      throw error;
+    }
+  }
+}
+```
+
+#### PG Adapter Pattern
+```typescript
+interface PGAdapter {
+  authorize(request: PaymentRequest): Promise<PGResult>;
+  capture(transactionId: string): Promise<PGResult>;
+  cancel(transactionId: string): Promise<PGResult>;
+  refund(transactionId: string, amount?: number): Promise<PGResult>;
+}
+
+// Implementations
+class TossPaymentsAdapter implements PGAdapter { /* ... */ }
+class StripeAdapter implements PGAdapter { /* ... */ }
+class PortOneAdapter implements PGAdapter { /* ... */ }
+```
+
+#### Webhook Handling
+```typescript
+class PaymentWebhookHandler {
+  async handle(event: WebhookEvent): Promise<void> {
+    // 1. Verify signature
+    if (!this.verifySignature(event)) {
+      throw new UnauthorizedError();
+    }
+
+    // 2. Idempotency check - process each event only once
+    const processed = await this.eventStore.find(event.id);
+    if (processed) {
+      return;  // Already processed
+    }
+
+    // 3. Process event
+    await this.processEvent(event);
+
+    // 4. Mark as processed
+    await this.eventStore.save({
+      eventId: event.id,
+      processedAt: new Date(),
+    });
+  }
+}
+```
+
+### 3. Inventory (Stock Management)
+
+#### Reservation Pattern (Two-Phase)
+```typescript
+interface StockReservation {
+  id: string;
+  productId: string;
+  quantity: number;
+  orderId: string;
+  status: 'RESERVED' | 'COMMITTED' | 'RELEASED';
+  expiresAt: Date;         // Auto-release if not committed
+  createdAt: Date;
+}
+
+class InventoryService {
+  // Phase 1: Reserve stock (at checkout start)
+  async reserve(orderId: string, items: OrderItem[]): Promise<void> {
+    for (const item of items) {
+      // Atomic decrement with check
+      const result = await this.db.query(`
+        UPDATE products
+        SET reserved_stock = reserved_stock + $1
+        WHERE id = $2
+          AND (available_stock - reserved_stock) >= $1
+        RETURNING *
+      `, [item.quantity, item.productId]);
+
+      if (result.rowCount === 0) {
+        // Rollback previous reservations
+        await this.releaseAll(orderId);
+        throw new InsufficientStockError(item.productId);
+      }
+
+      await this.reservationRepository.create({
+        orderId,
+        productId: item.productId,
+        quantity: item.quantity,
+        status: 'RESERVED',
+        expiresAt: addMinutes(new Date(), 15),  // 15min hold
+      });
+    }
+  }
+
+  // Phase 2: Commit stock (after payment success)
+  async commit(orderId: string): Promise<void> {
+    const reservations = await this.reservationRepository.findByOrder(orderId);
+
+    for (const reservation of reservations) {
+      await this.db.query(`
+        UPDATE products
+        SET
+          available_stock = available_stock - $1,
+          reserved_stock = reserved_stock - $1
+        WHERE id = $2
+      `, [reservation.quantity, reservation.productId]);
+
+      await this.reservationRepository.update(reservation.id, {
+        status: 'COMMITTED',
+      });
+    }
+  }
+
+  // Rollback: Release stock (payment failed or timeout)
+  async release(orderId: string): Promise<void> {
+    const reservations = await this.reservationRepository.findByOrder(orderId);
+
+    for (const reservation of reservations) {
+      if (reservation.status === 'RESERVED') {
+        await this.db.query(`
+          UPDATE products
+          SET reserved_stock = reserved_stock - $1
+          WHERE id = $2
+        `, [reservation.quantity, reservation.productId]);
+
+        await this.reservationRepository.update(reservation.id, {
+          status: 'RELEASED',
+        });
+      }
+    }
+  }
+}
+```
+
+#### Concurrency Control
+```typescript
+// Option 1: Optimistic Locking
+await db.query(`
+  UPDATE products
+  SET stock = stock - $1, version = version + 1
+  WHERE id = $2 AND version = $3 AND stock >= $1
+`, [quantity, productId, expectedVersion]);
+
+// Option 2: Pessimistic Locking (for high contention)
+await db.query(`
+  SELECT * FROM products WHERE id = $1 FOR UPDATE
+`, [productId]);
+
+// Option 3: Redis Distributed Lock
+const lock = await redlock.lock(`stock:${productId}`, 5000);
+try {
+  // Update stock
+} finally {
+  await lock.unlock();
+}
+```
+
+## Order Flow (Complete)
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  CHECKOUT FLOW                                              │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  1. Cart Validation                                         │
+│     └─ Revalidate prices, check stock availability          │
+│                                                             │
+│  2. Order Creation (PENDING)                                │
+│     └─ Generate orderId, snapshot cart                      │
+│                                                             │
+│  3. Stock Reservation                                       │
+│     └─ Reserve inventory (15min hold)                       │
+│                                                             │
+│  4. Payment Processing                                      │
+│     ├─ Success → Order PAID, Stock COMMIT                   │
+│     └─ Failure → Order FAILED, Stock RELEASE                │
+│                                                             │
+│  5. Order Confirmation                                      │
+│     └─ Send notification, trigger fulfillment               │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Common Bugs & Prevention
+
+| Bug | Cause | Prevention |
+|-----|-------|------------|
+| **Duplicate payment** | User double-click, webhook retry | Idempotency key |
+| **Negative stock** | Race condition | Atomic update with check |
+| **Price mismatch** | Price changed during checkout | Snapshot + revalidation |
+| **Orphan reservation** | Payment timeout without release | TTL + scheduled cleanup |
+| **Lost webhook** | Network failure | Retry + idempotent handler |
+| **Order state corruption** | Concurrent updates | State machine + versioning |
+
+## Integration with /vibe.run
+
+During commerce feature implementation:
+
+1. **Phase 1**: Define domain models (Cart, Order, Payment, Inventory)
+2. **Phase 2**: Implement core services with patterns above
+3. **Phase 3**: Add PG adapter and webhook handlers
+4. **Phase 4**: Implement compensating transactions (Saga)
+5. **Phase 5**: E2E test critical flows
+
+## Checklist
+
+### Cart
+- [ ] Guest/user cart merge on login
+- [ ] Price snapshot at add time
+- [ ] Stock validation at checkout
+- [ ] Cart expiration cleanup
+
+### Payment
+- [ ] Idempotency key on all requests
+- [ ] Webhook signature verification
+- [ ] Duplicate event handling
+- [ ] Timeout/retry strategy
+- [ ] Refund flow tested
+
+### Inventory
+- [ ] Two-phase reservation (reserve → commit/release)
+- [ ] Atomic stock updates
+- [ ] Reservation TTL and cleanup job
+- [ ] Concurrency control tested

package/skills/e2e-commerce.md

@@ -0,0 +1,304 @@
+---
+name: e2e-commerce
+description: "E2E test scenarios for commerce checkout and payment flows"
+triggers: [e2e commerce, checkout test, payment test, order flow test]
+priority: 65
+---
+# E2E Commerce Test Scenarios
+
+Playwright-based E2E testing for commerce checkout flows.
+
+## When to Use
+
+- After implementing checkout/payment features
+- Before production deployment
+- CI/CD pipeline quality gate
+- Regression testing after changes
+
+## Test Scenarios
+
+### 1. Happy Path - Complete Checkout
+
+```typescript
+// tests/e2e/checkout.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Checkout Flow', () => {
+  test('complete purchase - happy path', async ({ page }) => {
+    // 1. Add to cart
+    await page.goto('/products/test-product');
+    await page.click('[data-testid="add-to-cart"]');
+    await expect(page.locator('[data-testid="cart-count"]')).toHaveText('1');
+
+    // 2. Go to cart
+    await page.click('[data-testid="cart-icon"]');
+    await expect(page).toHaveURL('/cart');
+
+    // 3. Proceed to checkout
+    await page.click('[data-testid="checkout-button"]');
+    await expect(page).toHaveURL('/checkout');
+
+    // 4. Fill shipping info
+    await page.fill('[name="name"]', 'Test User');
+    await page.fill('[name="phone"]', '010-1234-5678');
+    await page.fill('[name="address"]', 'Test Address 123');
+
+    // 5. Select payment method
+    await page.click('[data-testid="payment-card"]');
+
+    // 6. Complete payment (sandbox/mock)
+    await page.click('[data-testid="pay-button"]');
+
+    // 7. Verify order complete
+    await expect(page).toHaveURL(/\/orders\/\w+/);
+    await expect(page.locator('[data-testid="order-status"]')).toHaveText('결제 완료');
+  });
+});
+```
+
+### 2. Stock Validation
+
+```typescript
+test('prevent checkout when out of stock', async ({ page }) => {
+  // Setup: Product with stock = 1, another user reserves it
+  await page.goto('/products/low-stock-product');
+  await page.click('[data-testid="add-to-cart"]');
+  await page.goto('/checkout');
+
+  // Simulate stock depletion during checkout
+  await page.evaluate(async () => {
+    await fetch('/api/test/deplete-stock', { method: 'POST' });
+  });
+
+  // Attempt payment
+  await page.click('[data-testid="pay-button"]');
+
+  // Should show out of stock error
+  await expect(page.locator('[data-testid="error-message"]'))
+    .toContainText('재고가 부족합니다');
+});
+```
+
+### 3. Payment Failure Handling
+
+```typescript
+test('handle payment failure gracefully', async ({ page }) => {
+  await page.goto('/products/test-product');
+  await page.click('[data-testid="add-to-cart"]');
+  await page.goto('/checkout');
+
+  // Fill form
+  await page.fill('[name="name"]', 'Test User');
+  await page.fill('[name="address"]', 'Test Address');
+
+  // Use test card that triggers failure
+  await page.fill('[name="card-number"]', '4000000000000002'); // Decline card
+  await page.click('[data-testid="pay-button"]');
+
+  // Verify error handling
+  await expect(page.locator('[data-testid="payment-error"]'))
+    .toContainText('결제가 거절되었습니다');
+
+  // Stock should be released
+  await page.goto('/products/test-product');
+  await expect(page.locator('[data-testid="stock-status"]'))
+    .not.toContainText('품절');
+});
+```
+
+### 4. Duplicate Payment Prevention
+
+```typescript
+test('prevent duplicate payment on double click', async ({ page }) => {
+  await page.goto('/checkout');
+  // Fill checkout form...
+
+  // Double click pay button rapidly
+  const payButton = page.locator('[data-testid="pay-button"]');
+  await Promise.all([
+    payButton.click(),
+    payButton.click(),
+  ]);
+
+  // Wait for completion
+  await page.waitForURL(/\/orders\/\w+/);
+
+  // Verify only one order created
+  const orderId = page.url().split('/').pop();
+  const response = await page.request.get(`/api/orders?userId=test`);
+  const orders = await response.json();
+
+  expect(orders.filter(o => o.id === orderId)).toHaveLength(1);
+});
+```
+
+### 5. Coupon Application
+
+```typescript
+test('apply coupon and verify discount', async ({ page }) => {
+  await page.goto('/products/test-product'); // Price: 10,000
+  await page.click('[data-testid="add-to-cart"]');
+  await page.goto('/checkout');
+
+  // Original price
+  await expect(page.locator('[data-testid="total-price"]'))
+    .toHaveText('10,000원');
+
+  // Apply 10% coupon
+  await page.fill('[name="coupon"]', 'DISCOUNT10');
+  await page.click('[data-testid="apply-coupon"]');
+
+  // Verify discount applied
+  await expect(page.locator('[data-testid="discount-amount"]'))
+    .toHaveText('-1,000원');
+  await expect(page.locator('[data-testid="total-price"]'))
+    .toHaveText('9,000원');
+});
+```
+
+### 6. Webhook Resilience
+
+```typescript
+test('order completes even with webhook delay', async ({ page, request }) => {
+  // Configure webhook delay in test environment
+  await request.post('/api/test/configure-webhook', {
+    data: { delay: 5000 } // 5 second delay
+  });
+
+  // Complete checkout
+  await page.goto('/checkout');
+  // ... fill form
+  await page.click('[data-testid="pay-button"]');
+
+  // Should show processing state
+  await expect(page.locator('[data-testid="order-status"]'))
+    .toHaveText('처리 중');
+
+  // Wait for webhook
+  await page.waitForSelector('[data-testid="order-status"]:has-text("결제 완료")', {
+    timeout: 10000
+  });
+});
+```
+
+## CLI Usage
+
+```bash
+# Run all commerce e2e tests
+/vibe.utils --e2e commerce
+
+# Run specific scenario
+/vibe.utils --e2e checkout-flow
+
+# Run with visual recording
+/vibe.utils --e2e commerce --record
+
+# Run against staging
+/vibe.utils --e2e commerce --env staging
+```
+
+## Test Environment Setup
+
+### Mock PG Server
+```typescript
+// tests/mocks/pg-server.ts
+import { setupServer } from 'msw/node';
+import { http, HttpResponse } from 'msw';
+
+export const pgMockServer = setupServer(
+  // Success response
+  http.post('/payments/authorize', () => {
+    return HttpResponse.json({
+      success: true,
+      transactionId: `txn_${Date.now()}`,
+      status: 'AUTHORIZED',
+    });
+  }),
+
+  // Failure simulation
+  http.post('/payments/authorize', ({ request }) => {
+    const body = request.json();
+    if (body.cardNumber === '4000000000000002') {
+      return HttpResponse.json({
+        success: false,
+        error: 'CARD_DECLINED',
+      }, { status: 400 });
+    }
+  }),
+);
+```
+
+### Database Seeding
+```typescript
+// tests/fixtures/commerce.ts
+export async function seedCommerceData(db: Database) {
+  // Create test products
+  await db.products.createMany([
+    { id: 'test-product', name: 'Test Product', price: 10000, stock: 100 },
+    { id: 'low-stock', name: 'Low Stock', price: 5000, stock: 1 },
+  ]);
+
+  // Create test coupons
+  await db.coupons.create({
+    code: 'DISCOUNT10',
+    discountPercent: 10,
+    expiresAt: addDays(new Date(), 30),
+  });
+}
+```
+
+## CI/CD Integration
+
+```yaml
+# .github/workflows/e2e.yml
+name: E2E Commerce Tests
+
+on:
+  pull_request:
+    paths:
+      - 'src/checkout/**'
+      - 'src/payment/**'
+      - 'src/cart/**'
+
+jobs:
+  e2e:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Start test server
+        run: npm run start:test &
+
+      - name: Run E2E tests
+        run: npx playwright test tests/e2e/commerce/
+
+      - name: Upload test results
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-report
+          path: playwright-report/
+```
+
+## Quality Checklist
+
+### Must Pass (P0)
+- [ ] Happy path checkout completes
+- [ ] Payment failure releases stock
+- [ ] Duplicate payment prevented
+- [ ] Out of stock blocks checkout
+
+### Should Pass (P1)
+- [ ] Coupon calculation correct
+- [ ] Webhook retry handled
+- [ ] Cart merge on login works
+- [ ] Partial refund processed
+
+### Nice to Have (P2)
+- [ ] Multiple payment methods
+- [ ] Guest checkout flow
+- [ ] Order cancellation
+- [ ] Subscription renewal