Kỹ Thuật Thiết Kế Contract-First API Và Đồng Bộ Hóa Schema Cho Đội Ngũ AI Agents Enterprise

flowchart TD
    Contract["OpenAPI YAML Specification (Hiến Pháp Chung)"] --> Generator["openapi-typescript (Trình Biên Dịch Tự Động)"]
    Generator --> Types["Generated TypeScript Types (@/types/api.ts)"]
    
    Types --> BackendAgent["Backend AI Agent (NestJS Controller & Service)"]
    Types --> FrontendAgent["Frontend AI Agent (Next.js Client & Hooks)"]
    
    BackendAgent & FrontendAgent --> Sync["100% Đồng Bộ Kiểu Dữ Liệu (Zero Type Mismatch)"]

openapi: 3.0.3
info:
  title: Order Service API
  version: 1.0.0
paths:
  /orders:
    post:
      summary: Tạo đơn hàng mới
      operationId: createOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderDto'
      responses:
        '201':
          description: Đơn hàng được tạo thành công
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
components:
  schemas:
    CreateOrderDto:
      type: object
      required:
        - customerId
        - items
      properties:
        customerId:
          type: string
          format: uuid
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItemDto'
    OrderItemDto:
      type: object
      required:
        - productId
        - quantity
      properties:
        productId:
          type: string
          format: uuid
        quantity:
          type: integer
          minimum: 1
    Order:
      type: object
      required:
        - id
        - customerId
        - items
        - status
        - createdAt
      properties:
        id:
          type: string
          format: uuid
        customerId:
          type: string
          format: uuid
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItemDto'
        status:
          type: string
          enum: [PENDING, PAID, SHIPPED, CANCELLED]
        createdAt:
          type: string
          format: date-time

npx openapi-typescript ./schemas/order-service.yaml -o ./types/order-service.ts

export interface paths {
  "/orders": {
    post: {
      requestBody: {
        content: {
          "application/json": components["schemas"]["CreateOrderDto"];
        };
      };
      responses: {
        201: {
          content: {
            "application/json": components["schemas"]["Order"];
          };
        };
      };
    };
  };
}

export interface components {
  schemas: {
    CreateOrderDto: {
      customerId: string;
      items: components["schemas"]["OrderItemDto"][];
    };
    OrderItemDto: {
      productId: string;
      quantity: number;
    };
    Order: {
      id: string;
      customerId: string;
      items: components["schemas"]["OrderItemDto"][];
      status: "PENDING" | "PAID" | "SHIPPED" | "CANCELLED";
      createdAt: string;
    };
  };
}

import { Controller, Post, Body, HttpCode, HttpStatus } from '@nestjs/common';
import { components } from '@/types/order-service';

type CreateOrderDto = components['schemas']['CreateOrderDto'];
type OrderResponse = components['schemas']['Order'];

@Controller('orders')
export class OrderController {
  @Post()
  @HttpCode(HttpStatus.CREATED)
  async createOrder(@Body() payload: CreateOrderDto): Promise<OrderResponse> {
    // Logic lưu trữ database...
    return {
      id: '550e8400-e29b-41d4-a716-446655440000',
      customerId: payload.customerId,
      items: payload.items,
      status: 'PENDING',
      createdAt: new Date().toISOString()
    };
  }
}

import { components } from '@/types/order-service';

type CreateOrderDto = components['schemas']['CreateOrderDto'];
type Order = components['schemas']['Order'];

export async function submitOrder(orderData: CreateOrderDto): Promise<Order> {
  const res = await fetch('/api/orders', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(orderData)
  });

  if (!res.ok) {
    throw new Error('Lỗi khi tạo đơn hàng');
  }

  // Kiểu trả về được bảo đảm 100% khớp với Backend
  return res.json();
}