Kỹ Thuật Quản Lý Micro-Context Và API Contract Cho Doanh Nghiệp

flowchart TD
    A["Yêu Cầu Tính Năng Enterprise"] --> B["API Contract Specification (TypeScript / OpenAPI)"]
    B --> C["Micro-Context Isolation Layer"]
    C -->|Chỉ nạp DTO & Interface| D["AI Coding Agent"]
    D --> E["Mã Nguồn Mới Được Sinh Ra"]
    E --> F["Automated Contract Linter"]
    F -->|Đạt chuẩn Schema| G["Tích hợp vào Codebase"]
    F -->|Vi phạm Schema / Thay đổi kiểu| H["Reject & Yêu cầu sửa lỗi"]

export enum OrderStatus {
  PENDING = 'PENDING',
  PAID = 'PAID',
  CANCELLED = 'CANCELLED',
  REFUNDED = 'REFUNDED'
}

export interface CreateOrderPayload {
  customerId: string;
  items: Array<{
    sku: string;
    quantity: number;
    unitPrice: number;
  }>;
  currency: 'VND' | 'USD';
  callbackUrl?: string;
}

export type PaymentResult =
  | { success: true; transactionId: string; timestamp: number }
  | { success: false; errorCode: string; errorMessage: string };

// Giao ước bắt buộc của OrderService
export interface IOrderService {
  createOrder(payload: CreateOrderPayload): Promise<{ orderId: string; totalAmount: number }>;
  processPayment(orderId: string, amount: number): Promise<PaymentResult>;
  getOrderStatus(orderId: string): Promise<OrderStatus>;
}

import { Queue } from 'bullmq';

export class OrderProcessor {
  private emailQueue: Queue;

  constructor() {
    this.emailQueue = new Queue('order-notifications');
  }

  async completeOrder(orderId: string, customerEmail: string): Promise<void> {
    // 1. Cập nhật trạng thái Database trong transaction
    await this.updateStatus(orderId, OrderStatus.PAID);

    // 2. Đẩy tác vụ gửi email vào hàng đợi nền (Non-blocking)
    await this.emailQueue.add('send-invoice', {
      orderId,
      email: customerEmail,
      timestamp: Date.now()
    });
  }

  private async updateStatus(orderId: string, status: OrderStatus): Promise<void> {
    // Logic cập nhật trạng thái
  }
}

// Dumb Component: OrderSummaryCard.tsx
interface OrderSummaryProps {
  orderId: string;
  totalAmount: number;
  status: OrderStatus;
  onRetryPayment?: () => void;
}

export const OrderSummaryCard: React.FC<OrderSummaryProps> = ({
  orderId,
  totalAmount,
  status,
  onRetryPayment
}) => {
  return (
    <div className="p-4 border rounded-lg shadow-sm bg-white dark:bg-slate-900">
      <div className="flex justify-between items-center mb-2">
        <span className="font-semibold text-sm">Mã đơn: {orderId}</span>
        <span className={`text-xs px-2 py-1 rounded font-bold ${
          status === OrderStatus.PAID ? 'bg-emerald-100 text-emerald-700' : 'bg-amber-100 text-amber-700'
        }`}>
          {status}
        </span>
      </div>
      <p className="text-lg font-bold text-slate-800 dark:text-slate-100">
        {totalAmount.toLocaleString('vi-VN')} VND
      </p>
      {status === OrderStatus.CANCELLED && onRetryPayment && (
        <button onClick={onRetryPayment} className="mt-3 w-full py-1.5 text-xs font-semibold bg-indigo-600 text-white rounded">
          Thử lại thanh toán
        </button>
      )}
    </div>
  );
};

# ENTERPRISE BOUNDARY RULES
1. BẮT BUỘC tuân thủ 100% Interface đã được định nghĩa trong `src/contracts/`.
2. TUYỆT ĐỐI KHÔNG sửa đổi các tệp `.d.ts` hoặc thêm field mới vào DTO khi chưa có yêu cầu rõ ràng.
3. Mọi tác vụ bên ngoài (gửi mail, đồng bộ CRM) phải đẩy qua Message Queue, không viết blocking call trong Controller.
4. Mọi API endpoint mới bắt buộc phải có JSON Schema validation trước khi xử lý logic.