openapi: 3.0.3
info:
  title: OMS·WMS·ERP Unified Business Platform API
  description: |
    Enterprise-grade Order/Warehouse/ERP management API
    Based on PDF specifications + 30 Strategic Principles

    ## Key Design Principles
    - REST-first (Principle 25: API Consistency)
    - Transaction-based (not CRUD-only) per PDF spec
    - RBAC with JWT tokens (Principle 23: Security)
    - Audit trail on all mutations (Principle 14: Traceability)
    - Type-safe schemas (Principle 19: Type Safety)
  version: 0.1.0
  contact:
    name: QuantEngine Architecture Team
    email: arch@quantengine.dev
  license:
    name: Internal Use Only

servers:
  - url: https://api.quantengine.dev
    description: Production
  - url: http://localhost:5265
    description: Local Development

# ===== SECURITY DEFINITIONS (Principle 23: Security) =====
security:
  - BearerAuth: []

securitySchemes:
  BearerAuth:
    type: http
    scheme: bearer
    bearerFormat: JWT
    description: |
      JWT token with claims:
      - sub: user_id
      - role: admin|manager|operator|viewer|analyst
      - iat, exp

# ===== COMPONENTS / SCHEMAS (Principle 19: Type Safety) =====
components:
  schemas:
    # Common Response Wrapper
    ApiError:
      type: object
      required: [code, message]
      properties:
        code:
          type: string
          example: "ERR_ORDER_VALIDATION_QUANTITY_EXCEEDS_STOCK"
          description: Machine-readable error code (Principle 24)
        message:
          type: string
          example: "Order quantity (150) exceeds available stock (100)"
          description: User-friendly message
        details:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
                example: "line_items[0].quantity"
              reason:
                type: string
                example: "Exceeds reserved inventory"

    PaginatedResponse:
      type: object
      required: [data, pagination]
      properties:
        data:
          type: array
        pagination:
          type: object
          required: [page, pageSize, totalCount]
          properties:
            page:
              type: integer
              minimum: 1
              example: 1
            pageSize:
              type: integer
              minimum: 1
              maximum: 100
              default: 20
            totalCount:
              type: integer
              example: 245
            totalPages:
              type: integer
              example: 13

    AuditInfo:
      type: object
      description: Traceability fields (Principle 14)
      required: [createdBy, createdAt]
      properties:
        createdBy:
          type: string
          example: "USER_001"
        createdAt:
          type: string
          format: date-time
        modifiedBy:
          type: string
          example: "USER_002"
        modifiedAt:
          type: string
          format: date-time
        deletedBy:
          type: string
        deletedAt:
          type: string
          format: date-time

    # ===== OMS Domain Schemas =====
    Order:
      type: object
      description: Master order record (TPL-CREATE-02 header)
      required: [orderId, orderNo, customerId, orderDate, totalAmount, status]
      properties:
        orderId:
          type: string
          format: uuid
          example: "550e8400-e29b-41d4-a716-446655440000"
        orderNo:
          type: string
          example: "ORD-2026-001234"
          description: Business-friendly order number
        customerId:
          type: string
          format: uuid
        customerName:
          type: string
          example: "ABC Corporation"
        orderDate:
          type: string
          format: date
          example: "2026-07-26"
        totalAmount:
          type: number
          format: double
          example: 50000.00
          description: Decimal precision (Principle 23)
        status:
          type: string
          enum: [DRAFT, CONFIRMED, SHIPPED, DELIVERED, CANCELLED]
          example: CONFIRMED
          description: State machine (Principle 24 UX)
        lines:
          type: array
          items:
            $ref: '#/components/schemas/OrderLine'
        audit:
          $ref: '#/components/schemas/AuditInfo'

    OrderLine:
      type: object
      description: Order detail line (TPL-CREATE-02 detail)
      required: [lineId, productId, quantity, unitPrice, lineTotal]
      properties:
        lineId:
          type: string
          format: uuid
        lineNo:
          type: integer
          minimum: 1
          example: 1
        productId:
          type: string
          format: uuid
        productSku:
          type: string
          example: "PROD-2026-0001"
        productName:
          type: string
        quantity:
          type: number
          format: double
          example: 10.5
        quantityUnit:
          type: string
          enum: [EA, KG, M, L, BOX]
          example: "EA"
        unitPrice:
          type: number
          format: double
          example: 4761.90
        lineTotal:
          type: number
          format: double
          example: 50000.00
        status:
          type: string
          enum: [PENDING, ALLOCATED, SHIPPED, CANCELLED]
          example: ALLOCATED

    # ===== WMS Domain Schemas =====
    Inventory:
      type: object
      description: Warehouse inventory position
      required: [inventoryId, warehouseId, productId, qtyOnHand, status]
      properties:
        inventoryId:
          type: string
          format: uuid
        warehouseId:
          type: string
          format: uuid
        warehouseName:
          type: string
          example: "Seoul Main Warehouse"
        productId:
          type: string
          format: uuid
        productSku:
          type: string
        productName:
          type: string
        qtyOnHand:
          type: number
          format: double
          example: 500.0
        qtyReserved:
          type: number
          format: double
          example: 150.0
        qtyAvailable:
          type: number
          format: double
          example: 350.0
        lastAdjustmentDate:
          type: string
          format: date-time
        status:
          type: string
          enum: [ACTIVE, INACTIVE, DAMAGED]
          example: ACTIVE
        audit:
          $ref: '#/components/schemas/AuditInfo'

    StockTransfer:
      type: object
      description: Inter-warehouse stock movement
      required: [transferId, fromWarehouse, toWarehouse, productId, quantity, status]
      properties:
        transferId:
          type: string
          format: uuid
        transferNo:
          type: string
          example: "XFER-2026-00567"
        fromWarehouse:
          type: string
          format: uuid
        toWarehouse:
          type: string
          format: uuid
        productId:
          type: string
          format: uuid
        quantity:
          type: number
          format: double
        status:
          type: string
          enum: [REQUESTED, APPROVED, SHIPPED, RECEIVED, CANCELLED]
          example: APPROVED
        reason:
          type: string
          example: "Inventory balancing - oversupply in Seoul"
        audit:
          $ref: '#/components/schemas/AuditInfo'

    # ===== ERP Domain Schemas =====
    Product:
      type: object
      description: Master product record
      required: [productId, sku, name, categoryId]
      properties:
        productId:
          type: string
          format: uuid
        sku:
          type: string
          example: "PROD-2026-0001"
          description: Stock Keeping Unit
        name:
          type: string
          example: "Widget Standard Size"
        categoryId:
          type: string
          format: uuid
        categoryName:
          type: string
        unitOfMeasure:
          type: string
          enum: [EA, KG, M, L, BOX]
          example: "EA"
        status:
          type: string
          enum: [ACTIVE, INACTIVE, OBSOLETE]
          example: ACTIVE
        audit:
          $ref: '#/components/schemas/AuditInfo'

    Supplier:
      type: object
      description: Master vendor/supplier record
      required: [supplierId, name, status]
      properties:
        supplierId:
          type: string
          format: uuid
        name:
          type: string
          example: "ABC Trading Co., Ltd."
        email:
          type: string
          format: email
        phone:
          type: string
          example: "+82-2-1234-5678"
        businessRegistration:
          type: string
          example: "123-45-67890"
        status:
          type: string
          enum: [ACTIVE, INACTIVE, SUSPENDED]
          example: ACTIVE
        audit:
          $ref: '#/components/schemas/AuditInfo'

    Customer:
      type: object
      description: Master customer record
      required: [customerId, name, status]
      properties:
        customerId:
          type: string
          format: uuid
        name:
          type: string
          example: "XYZ Corporation"
        email:
          type: string
          format: email
        phone:
          type: string
        businessRegistration:
          type: string
        status:
          type: string
          enum: [ACTIVE, INACTIVE, SUSPENDED]
          example: ACTIVE
        audit:
          $ref: '#/components/schemas/AuditInfo'

    GLAccount:
      type: object
      description: General Ledger account
      required: [accountId, code, name, type]
      properties:
        accountId:
          type: string
          format: uuid
        code:
          type: string
          example: "1010"
          description: Chart of Accounts code
        name:
          type: string
          example: "Cash - KRW"
        type:
          type: string
          enum: [ASSET, LIABILITY, EQUITY, REVENUE, EXPENSE]
          example: ASSET
        status:
          type: string
          enum: [ACTIVE, INACTIVE]
          example: ACTIVE
        audit:
          $ref: '#/components/schemas/AuditInfo'

    Voucher:
      type: object
      description: Accounting journal entry
      required: [voucherId, voucherNo, status]
      properties:
        voucherId:
          type: string
          format: uuid
        voucherNo:
          type: string
          example: "JNL-2026-00123"
        documentDate:
          type: string
          format: date
        documentType:
          type: string
          enum: [PURCHASE, SALES, JOURNAL, ADJUSTMENT]
          example: PURCHASE
        status:
          type: string
          enum: [DRAFT, POSTED, APPROVED, VOIDED]
          example: APPROVED
        totalDebit:
          type: number
          format: double
        totalCredit:
          type: number
          format: double
        description:
          type: string
        audit:
          $ref: '#/components/schemas/AuditInfo'

    # ===== Audit & History =====
    AuditLog:
      type: object
      description: Complete change audit trail (Principle 14)
      required: [auditId, entityType, entityId, operation, changedBy, changedAt]
      properties:
        auditId:
          type: string
          format: uuid
        entityType:
          type: string
          enum: [ORDER, INVENTORY, PRODUCT, SUPPLIER, CUSTOMER, VOUCHER]
          example: ORDER
        entityId:
          type: string
          format: uuid
        operation:
          type: string
          enum: [CREATE, UPDATE, DELETE]
          example: UPDATE
        oldValue:
          type: object
          description: "JSON snapshot of previous state"
        newValue:
          type: object
          description: "JSON snapshot of current state"
        changedBy:
          type: string
          format: uuid
        changedAt:
          type: string
          format: date-time
        reason:
          type: string
          example: "Manual correction per user request"

# ===== PATHS / ENDPOINTS (Principle 25: REST) =====
paths:
  # ===== OMS: Order Management =====
  /api/orders:
    get:
      summary: List orders (TPL-LIST-01)
      operationId: listOrders
      tags: [OMS]
      description: Retrieve orders with pagination and filters
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: pageSize
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: status
          in: query
          schema:
            type: string
            enum: [DRAFT, CONFIRMED, SHIPPED, DELIVERED, CANCELLED]
        - name: fromDate
          in: query
          schema:
            type: string
            format: date
        - name: toDate
          in: query
          schema:
            type: string
            format: date
        - name: customerId
          in: query
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: List of orders
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PaginatedResponse'
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Order'
        '400':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden (insufficient role)

    post:
      summary: Create order (TPL-CREATE-02)
      operationId: createOrder
      tags: [OMS]
      description: Create new order with line items
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [customerId, lines]
              properties:
                customerId:
                  type: string
                  format: uuid
                orderDate:
                  type: string
                  format: date
                  default: today
                lines:
                  type: array
                  minItems: 1
                  items:
                    type: object
                    required: [productId, quantity]
                    properties:
                      productId:
                        type: string
                        format: uuid
                      quantity:
                        type: number
                        format: double
                        minimum: 0.01
      responses:
        '201':
          description: Order created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          description: Validation error (stock insufficient, invalid product, etc.)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: Conflict (customer locked, inventory reserved)

  /api/orders/{orderId}:
    get:
      summary: Get order detail (TPL-DETAIL-01)
      operationId: getOrder
      tags: [OMS]
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Order detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '404':
          description: Order not found

    put:
      summary: Update order (TPL-EDIT-01)
      operationId: updateOrder
      tags: [OMS]
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  enum: [DRAFT, CONFIRMED, CANCELLED]
                lines:
                  type: array
                  items:
                    $ref: '#/components/schemas/OrderLine'
      responses:
        '200':
          description: Order updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'

    delete:
      summary: Cancel order (TPL-CANCEL-01)
      operationId: cancelOrder
      tags: [OMS]
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [reason]
              properties:
                reason:
                  type: string
                  example: "Customer request"
      responses:
        '200':
          description: Order cancelled (creates reversal transaction per PDF)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'

  # ===== WMS: Warehouse Management =====
  /api/inventory:
    get:
      summary: List inventory (TPL-LIST-01)
      operationId: listInventory
      tags: [WMS]
      parameters:
        - name: warehouseId
          in: query
          schema:
            type: string
            format: uuid
        - name: productSku
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Inventory list
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PaginatedResponse'
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Inventory'

  /api/stock-transfers:
    post:
      summary: Request stock transfer (TPL-CREATE-02)
      operationId: createStockTransfer
      tags: [WMS]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [fromWarehouse, toWarehouse, productId, quantity]
              properties:
                fromWarehouse:
                  type: string
                  format: uuid
                toWarehouse:
                  type: string
                  format: uuid
                productId:
                  type: string
                  format: uuid
                quantity:
                  type: number
                  format: double
                reason:
                  type: string
      responses:
        '201':
          description: Transfer request created (pending approval)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StockTransfer'

  /api/stock-transfers/{transferId}:
    patch:
      summary: Approve/reject transfer (TPL-APPROVAL-01)
      operationId: approveTransfer
      tags: [WMS]
      parameters:
        - name: transferId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [status]
              properties:
                status:
                  type: string
                  enum: [APPROVED, REJECTED]
                reason:
                  type: string
      responses:
        '200':
          description: Transfer status updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StockTransfer'

  # ===== ERP: Master Data Management =====
  /api/products:
    get:
      summary: List products (TPL-LIST-01)
      operationId: listProducts
      tags: [ERP]
      responses:
        '200':
          description: Product list
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PaginatedResponse'
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Product'

    post:
      summary: Create product (TPL-CREATE-01)
      operationId: createProduct
      tags: [ERP]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [sku, name, categoryId]
              properties:
                sku:
                  type: string
                name:
                  type: string
                categoryId:
                  type: string
                  format: uuid
      responses:
        '201':
          description: Product created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'

  /api/suppliers:
    get:
      summary: List suppliers (TPL-LIST-01)
      operationId: listSuppliers
      tags: [ERP]
      responses:
        '200':
          description: Supplier list
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PaginatedResponse'
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Supplier'

  /api/customers:
    get:
      summary: List customers (TPL-LIST-01)
      operationId: listCustomers
      tags: [ERP]
      responses:
        '200':
          description: Customer list
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PaginatedResponse'
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Customer'

  /api/gl-accounts:
    get:
      summary: List GL accounts (TPL-LIST-01)
      operationId: listGLAccounts
      tags: [ERP]
      responses:
        '200':
          description: GL account list
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PaginatedResponse'
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/GLAccount'

  /api/vouchers:
    get:
      summary: List vouchers (TPL-LIST-01)
      operationId: listVouchers
      tags: [ERP]
      responses:
        '200':
          description: Voucher list
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PaginatedResponse'
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Voucher'

    post:
      summary: Create voucher (TPL-CREATE-01)
      operationId: createVoucher
      tags: [ERP]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [documentDate, documentType]
              properties:
                documentDate:
                  type: string
                  format: date
                documentType:
                  type: string
                  enum: [PURCHASE, SALES, JOURNAL, ADJUSTMENT]
                description:
                  type: string
      responses:
        '201':
          description: Voucher created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Voucher'

  # ===== Audit Trail =====
  /api/audit-logs:
    get:
      summary: Query audit trail (TPL-HISTORY-01)
      operationId: getAuditLogs
      tags: [Audit]
      description: |
        Retrieve complete change history for entities.
        Principle 14: Complete traceability of all mutations.
      parameters:
        - name: entityType
          in: query
          schema:
            type: string
            enum: [ORDER, INVENTORY, PRODUCT, SUPPLIER, CUSTOMER, VOUCHER]
        - name: entityId
          in: query
          schema:
            type: string
            format: uuid
        - name: fromDate
          in: query
          schema:
            type: string
            format: date-time
        - name: toDate
          in: query
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: Audit log entries
          content:
            application/json:
              schema:
                type: object
                properties:
                  logs:
                    type: array
                    items:
                      $ref: '#/components/schemas/AuditLog'

tags:
  - name: OMS
    description: Order Management System endpoints
  - name: WMS
    description: Warehouse Management System endpoints
  - name: ERP
    description: Enterprise Resource Planning endpoints
  - name: Audit
    description: Audit trail and history endpoints

x-api-meta:
  architecture: Domain-Driven Design (Principle 1: SOLID)
  security: RBAC via JWT claims (Principle 23)
  transactions: Reversal-based (no overwrites) per PDF spec
  audit: Complete trail on all mutations (Principle 14)
  consistency: Decimal precision for financials (Principle 23)
  versioning: "X-API-Version: 1" header (future expansion)