swagger.json

{
  "openapi": "3.0.3",
  "info": {
    "title": "EVM Dealer Management API",
    "version": "1.0.0",
    "description": "EVDMS SYSTEMS"
  },
  "servers": [
    { "url": "http://localhost:5000", "description": "Development server" },
    { "url": "/", "description": "Current server" }
  ],
  "security": [{ "bearerAuth": [] }],
  "tags": [
    { "name": "Auth", "description": "Authentication endpoints - Role: Admin, DealerManager" },
    { "name": "VehicleModels", "description": "Vehicle model management - Role: EVMStaff, Admin" },
    { "name": "VehicleVariants", "description": "Vehicle variant management - Role: EVMStaff, Admin" },
    { "name": "VehicleColors", "description": "Vehicle color management - Role: EVMStaff, Admin" },
    { "name": "Inventory", "description": "Inventory management - Role: DealerStaff (read), DealerManager, EVMStaff, Admin" },
    { "name": "Promotions", "description": "Promotion management - Role: DealerStaff (read), EVMStaff, Admin" },
    { "name": "Customers", "description": "Customer management - Role: DealerStaff, DealerManager, Admin" },
    { "name": "TestDrives", "description": "Test drive booking - Role: DealerStaff, DealerManager, Admin" },
    { "name": "Quotes", "description": "Quote management - Role: DealerStaff, DealerManager, Admin" },
    { "name": "Orders", "description": "Order management - Role: DealerStaff, DealerManager, Admin" },
    { "name": "Contracts", "description": "Contract management - Role: DealerStaff, DealerManager, Admin" },
    { "name": "Payments", "description": "Payment management - Role: DealerStaff, DealerManager, Admin" },
    { "name": "Dealers", "description": "Dealer management - Role: DealerManager, EVMStaff, Admin" },
    { "name": "Reports", "description": "Reports and analytics - Role: DealerManager, EVMStaff, Admin" },
    { "name": "Deliveries", "description": "Quản lý giao xe - DealerStaff tạo, DealerManager cập nhật" },
    { "name": "Feedbacks", "description": "Phản hồi khách hàng - DealerStaff tạo, DealerManager xem/cập nhật" },
    { "name": "Dashboard", "description": "Tổng quan hệ thống" },
    { "name": "Users", "description": "Quản trị tài khoản" }
  ],
  "paths": {
    "/api/auth/login": {
      "post": {
        "tags": ["Auth"],
        "summary": "Đăng nhập người dùng",
        "description": "Đăng nhập bằng email và mật khẩu. Trả về access token và refresh token.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": { "type": "string", "example": "admin@evms.com" },
                  "password": { "type": "string", "example": "123456" }
                },
                "required": ["email", "password"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Login successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": { "type": "string", "example": "Login successful" },
                    "token": { "type": "string", "description": "JWT access token (valid for 1 day)" },
                    "refreshToken": { "type": "string", "description": "JWT refresh token (valid for 7 days)" },
                    "user": {
                      "type": "object",
                      "properties": {
                        "_id": { "type": "string" },
                        "email": { "type": "string" },
                        "role": { "type": "string" },
                        "profile": { "type": "object" },
                        "dealer": { "type": "string" }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": { "description": "Invalid credentials" },
          "500": { "description": "Server error" }
        },
        "security": []
      }
    },
    "/api/auth/refresh": {
      "post": {
        "tags": ["Auth"],
        "summary": "Làm mới access token",
        "description": "Tạo mới access token và refresh token từ refresh token hợp lệ",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "refreshToken": { "type": "string", "description": "Valid refresh token", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }
                },
                "required": ["refreshToken"],
                "example": {
                  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjY4ZjkwZWJlYmVhZWY3MmVjZjZlMDA1YSIsInJvbGUiOiJBZG1pbiIsInR5cGUiOiJyZWZyZXNoIiwiaWF0IjoxNzE2NTY3ODkzLCJleHAiOjE3MTcxNzI2OTN9..."
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Token refreshed successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": { "type": "string", "example": "Token refreshed successfully" },
                    "token": { "type": "string", "description": "New JWT access token" },
                    "refreshToken": { "type": "string", "description": "New JWT refresh token" },
                    "user": {
                      "type": "object",
                      "properties": {
                        "_id": { "type": "string" },
                        "email": { "type": "string" },
                        "role": { "type": "string" },
                        "profile": { "type": "object" },
                        "dealer": { "type": "string" }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": { "description": "Refresh token is required" },
          "401": { "description": "Invalid or expired refresh token" },
          "500": { "description": "Server error" }
        },
        "security": []
      }
    },
    "/api/auth/register": {
      "post": {
        "tags": ["Auth"],
        "summary": "Tạo tài khoản người dùng (Admin & DealerManager)",
        "description": "Tạo tài khoản người dùng mới - Yêu cầu quyền: Admin hoặc DealerManager (DealerManager chỉ được tạo DealerStaff)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": { "type": "string", "example": "newuser@evms.com" },
                  "password": { "type": "string", "example": "password123" },
                  "role": { "type": "string", "enum": ["Admin", "EVMStaff", "DealerManager", "DealerStaff"], "example": "DealerStaff" },
                  "dealer": { "type": "string", "description": "Dealer ID (required for DealerManager/DealerStaff)", "example": "68f90ebebeaef72ecf6e005a" },
                  "profile": {
                    "type": "object",
                    "properties": {
                      "name": { "type": "string", "example": "John Doe" },
                      "phone": { "type": "string", "example": "0901234567" }
                    }
                  }
                },
                "required": ["email", "password", "role"],
                "example": {
                  "email": "staff@dealer.com",
                  "password": "password123",
                  "role": "DealerStaff",
                  "dealer": "68f90ebebeaef72ecf6e005a",
                  "profile": {
                    "name": "Nguyen Van A",
                    "phone": "0901234567"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "User created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": { "type": "string", "example": "User registered successfully" },
                    "user": {
                      "type": "object",
                      "properties": {
                        "id": { "type": "string" },
                        "email": { "type": "string" },
                        "role": { "type": "string" },
                        "profile": { "type": "object" },
                        "dealer": { "type": "string" }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": { "description": "Bad request - User already exists or invalid data" },
          "403": { "description": "Forbidden - Insufficient permissions" },
          "500": { "description": "Server error" }
        }
      }
    },
    "/api/auth/me": {
      "get": {
        "tags": ["Auth"],
        "summary": "Lấy thông tin người dùng hiện tại",
        "description": "Trả về thông tin hồ sơ của người dùng đã xác thực",
        "responses": {
          "200": { 
            "description": "User profile",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "_id": { "type": "string" },
                    "email": { "type": "string" },
                    "role": { "type": "string", "enum": ["Admin", "EVMStaff", "DealerManager", "DealerStaff"] },
                    "profile": { 
                      "type": "object",
                      "properties": {
                        "name": { "type": "string" },
                        "phone": { "type": "string" }
                      }
                    },
                    "dealer": { "type": "string" },
                    "status": { "type": "string", "enum": ["active", "locked"] },
                    "createdAt": { "type": "string", "format": "date-time" },
                    "updatedAt": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "401": { "description": "Unauthorized - No token or invalid token" }
        }
      }
    },
    "/api/auth/logout": {
      "post": {
        "tags": ["Auth"],
        "summary": "Đăng xuất",
        "description": "Đăng xuất người dùng đã đăng nhập. Client nên xóa token khỏi localStorage/cookie.",
        "responses": {
          "200": {
            "description": "Logout successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean", "example": true },
                    "message": { "type": "string", "example": "Logout successful" }
                  }
                }
              }
            }
          },
          "401": { "description": "Not authenticated" },
          "500": { "description": "Server error" }
        }
      }
    },
    "/api/vehicles": {
      "get": {
        "tags": ["VehicleVariants"],
        "summary": "Liệt kê tất cả phiên bản xe (variants)",
        "responses": { "200": { "description": "List of vehicle variants" } }
      },
      "post": {
        "tags": ["VehicleVariants"],
        "summary": "Tạo phiên bản xe (variant) mới",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "model": { "type": "string", "description": "VehicleModel ID", "example": "68f90ebebeaef72ecf6e005e" },
                  "trim": { "type": "string", "example": "Premium" },
                  "battery": { "type": "string", "example": "100kWh" },
                  "range": { "type": "number", "example": 600 },
                  "motorPower": { "type": "number", "example": 300 },
                  "features": { "type": "array", "items": { "type": "string" }, "example": ["Electric", "Autopilot", "AI Assistant", "Fast Charging", "Premium Interior", "Panoramic Sunroof"] },
                  "msrp": { "type": "number", "example": 6500000000 },
                  "images": { "type": "array", "items": { "type": "string" }, "example": ["vf8_premium_front.jpg", "vf8_premium_interior.jpg", "vf8_premium_side.jpg"] },
                  "active": { "type": "boolean", "example": true }
                },
                "required": ["model", "trim", "msrp"],
                "example": {
                  "model": "68f90ebebeaef72ecf6e005e",
                  "trim": "Premium",
                  "battery": "100kWh",
                  "range": 600,
                  "motorPower": 300,
                  "features": ["Electric", "Autopilot", "AI Assistant", "Fast Charging", "Premium Interior"],
                  "msrp": 6500000000,
                  "images": ["vf8_premium_1.jpg"],
                  "active": true
                }
              }
            }
          }
        },
        "responses": { "201": { "description": "Vehicle variant created" } }
      }
    },
    "/api/vehicles/compare": {
      "get": {
        "tags": ["VehicleVariants"],
        "summary": "So sánh nhiều phiên bản xe (GET)",
        "description": "So sánh nhiều xe bằng query parameter. Tối thiểu 2 xe, không giới hạn tối đa. Truyền danh sách id biến thể qua query 'ids', phân tách dấu phẩy",
        "parameters": [
          { 
            "name": "ids", 
            "in": "query", 
            "required": true, 
            "schema": { "type": "string" }, 
            "example": "68f90e...005c,68f90e...005e,68f90e...005f",
            "description": "Danh sách ID của các xe cần so sánh, phân tách bởi dấu phẩy"
          }
        ],
        "responses": { 
          "200": { 
            "description": "So sánh thành công",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean", "example": true },
                    "message": { "type": "string", "example": "So sánh 3 xe thành công" },
                    "data": {
                      "type": "object",
                      "properties": {
                        "count": { "type": "number", "example": 3 },
                        "vehicles": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "_id": { "type": "string" },
                              "model": {
                                "type": "object",
                                "properties": {
                                  "_id": { "type": "string" },
                                  "name": { "type": "string" },
                                  "brand": { "type": "string" },
                                  "segment": { "type": "string" },
                                  "description": { "type": "string" }
                                }
                              },
                              "trim": { "type": "string" },
                              "battery": { "type": "string" },
                              "range": { "type": "number" },
                              "motorPower": { "type": "number" },
                              "features": { "type": "array", "items": { "type": "string" } },
                              "msrp": { "type": "number" },
                              "images": { "type": "array", "items": { "type": "string" } },
                              "active": { "type": "boolean" }
                            }
                          }
                        },
                        "comparison": {
                          "type": "object",
                          "properties": {
                            "models": { "type": "array", "items": { "type": "string" } },
                            "trims": { "type": "array", "items": { "type": "string" } },
                            "priceRange": {
                              "type": "object",
                              "properties": {
                                "min": { "type": "number" },
                                "max": { "type": "number" }
                              }
                            },
                            "rangeRange": {
                              "type": "object",
                              "properties": {
                                "min": { "type": "number" },
                                "max": { "type": "number" }
                              }
                            },
                            "motorPowerRange": {
                              "type": "object",
                              "properties": {
                                "min": { "type": "number" },
                                "max": { "type": "number" }
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }, 
          "400": { "description": "Thiếu hoặc sai tham số (cần ít nhất 2 xe)" },
          "404": { "description": "Không tìm thấy một hoặc nhiều xe" }
        }
      },
      "post": {
        "tags": ["VehicleVariants"],
        "summary": "So sánh nhiều phiên bản xe (POST - JSON)",
        "description": "So sánh nhiều xe bằng JSON body. Tối thiểu 2 xe, không giới hạn tối đa. Gửi mảng IDs trong request body.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "ids": {
                    "type": "array",
                    "items": { "type": "string" },
                    "minItems": 2,
                    "description": "Danh sách ID của các xe cần so sánh"
                  }
                },
                "required": ["ids"],
                "example": {
                  "ids": ["68f90e...005c", "68f90e...005e", "68f90e...005f"]
                }
              }
            }
          }
        },
        "responses": { 
          "200": { 
            "description": "So sánh thành công",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean", "example": true },
                    "message": { "type": "string", "example": "So sánh 3 xe thành công" },
                    "data": {
                      "type": "object",
                      "properties": {
                        "count": { "type": "number", "example": 3 },
                        "vehicles": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "_id": { "type": "string" },
                              "model": {
                                "type": "object",
                                "properties": {
                                  "_id": { "type": "string" },
                                  "name": { "type": "string" },
                                  "brand": { "type": "string" },
                                  "segment": { "type": "string" },
                                  "description": { "type": "string" }
                                }
                              },
                              "trim": { "type": "string" },
                              "battery": { "type": "string" },
                              "range": { "type": "number" },
                              "motorPower": { "type": "number" },
                              "features": { "type": "array", "items": { "type": "string" } },
                              "msrp": { "type": "number" },
                              "images": { "type": "array", "items": { "type": "string" } },
                              "active": { "type": "boolean" }
                            }
                          }
                        },
                        "comparison": {
                          "type": "object",
                          "properties": {
                            "models": { "type": "array", "items": { "type": "string" } },
                            "trims": { "type": "array", "items": { "type": "string" } },
                            "priceRange": {
                              "type": "object",
                              "properties": {
                                "min": { "type": "number" },
                                "max": { "type": "number" }
                              }
                            },
                            "rangeRange": {
                              "type": "object",
                              "properties": {
                                "min": { "type": "number" },
                                "max": { "type": "number" }
                              }
                            },
                            "motorPowerRange": {
                              "type": "object",
                              "properties": {
                                "min": { "type": "number" },
                                "max": { "type": "number" }
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }, 
          "400": { "description": "Thiếu hoặc sai tham số (cần ít nhất 2 xe)" },
          "404": { "description": "Không tìm thấy một hoặc nhiều xe" }
        }
      }
    },
    "/api/vehicles/{id}": {
      "get": {
        "tags": ["VehicleVariants"],
        "summary": "Lấy chi tiết phiên bản xe theo ID",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Vehicle variant details" } }
      },
      "put": {
        "tags": ["VehicleVariants"],
        "summary": "Cập nhật phiên bản xe",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "trim": { "type": "string" },
                  "battery": { "type": "string" },
                  "range": { "type": "number" },
                  "motorPower": { "type": "number" },
                  "features": { "type": "array", "items": { "type": "string" } },
                  "msrp": { "type": "number" },
                  "images": { "type": "array", "items": { "type": "string" } },
                  "active": { "type": "boolean" }
                }
              }
            }
          }
        },
        "responses": { "200": { "description": "Vehicle variant updated" } }
      },
      "delete": {
        "tags": ["VehicleVariants"],
        "summary": "Xóa phiên bản xe",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Vehicle variant deleted" } }
      }
    },
    "/api/inventory": {
      "get": {
        "tags": ["Inventory"],
        "summary": "Lấy tồn kho (theo đại lý hoặc tổng)",
        "responses": { "200": { "description": "Inventory list" } }
      },
      "post": {
        "tags": ["Inventory"],
        "summary": "Tạo mục tồn kho",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "ownerType": { "type": "string", "enum": ["EVM", "Dealer"], "example": "Dealer" },
                  "owner": { "type": "string", "description": "Dealer ID", "example": "68f90ebebeaef72ecf6e005a" },
                  "variant": { "type": "string", "description": "VehicleVariant ID", "example": "68f90ebebeaef72ecf6e005c" },
                  "color": { "type": "string", "description": "VehicleColor ID", "example": "68f90ebebeaef72ecf6e005d" },
                  "quantity": { "type": "number", "example": 10 },
                  "reserved": { "type": "number", "example": 0 },
                  "vinList": { "type": "array", "items": { "type": "string" }, "example": ["VIN001234567890", "VIN001234567891"] },
                  "location": { "type": "string", "example": "Warehouse A - Hanoi" }
                },
                "required": ["ownerType", "owner", "variant", "quantity"],
                "example": {
                  "ownerType": "Dealer",
                  "owner": "68f90ebebeaef72ecf6e005a",
                  "variant": "68f90ebebeaef72ecf6e005c",
                  "color": "68f90ebebeaef72ecf6e005d",
                  "quantity": 15,
                  "reserved": 2,
                  "vinList": ["VIN001234567890", "VIN001234567891", "VIN001234567892"],
                  "location": "Warehouse A - Hanoi"
                }
              }
            }
          }
        },
        "responses": { "201": { "description": "Inventory created" } }
      }
    },
    "/api/inventory/dealer/{dealerId}": {
      "get": {
        "tags": ["Inventory"],
        "summary": "Lấy tồn kho theo đại lý",
        "parameters": [{ "name": "dealerId", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Danh sách tồn kho của đại lý" } }
      }
    },
    "/api/inventory/transfer": {
      "post": {
        "tags": ["Inventory"],
        "summary": "Điều phối xe giữa các đại lý",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "variant": { "type": "string" }, "color": { "type": "string" }, "fromDealerId": { "type": "string" }, "toDealerId": { "type": "string" }, "quantity": { "type": "number" } }, "required": ["variant", "fromDealerId", "toDealerId", "quantity"], "example": { "variant": "68f9...005c", "color": "68f9...005d", "fromDealerId": "68f9...00aa", "toDealerId": "68f9...00bb", "quantity": 2 } } } } },
        "responses": { "200": { "description": "Kết quả điều phối" } }
      }
    },
    "/api/inventory/{id}": {
      "put": {
        "tags": ["Inventory"],
        "summary": "Update inventory item",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "quantity": { "type": "number", "example": 15 },
                  "reserved": { "type": "number", "example": 2 },
                  "vinList": { "type": "array", "items": { "type": "string" } },
                  "location": { "type": "string" }
                },
                "example": {
                  "quantity": 20,
                  "reserved": 3,
                  "vinList": ["VIN001234567893", "VIN001234567894"],
                  "location": "Warehouse B - Ho Chi Minh City"
                }
              }
            }
          }
        },
        "responses": { "200": { "description": "Inventory updated" } }
      },
      "delete": {
        "tags": ["Inventory"],
        "summary": "Delete inventory item",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Inventory deleted" } }
      }
    },
    "/api/promotions": {
      "get": {
        "tags": ["Promotions"],
        "summary": "Liệt kê khuyến mãi",
        "responses": { "200": { "description": "Promotion list" } }
      },
      "post": {
        "tags": ["Promotions"],
        "summary": "Tạo khuyến mãi",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": { "type": "string", "example": "Summer Sale 2024" },
                  "scope": { "type": "string", "enum": ["global", "byDealer", "byVariant"], "example": "byDealer" },
                  "dealers": { "type": "array", "items": { "type": "string" }, "description": "Array of Dealer IDs", "example": ["68f90ebebeaef72ecf6e005a", "68f90ebebeaef72ecf6e005b"] },
                  "variants": { "type": "array", "items": { "type": "string" }, "description": "Array of VehicleVariant IDs", "example": ["68f90ebebeaef72ecf6e005c", "68f90ebebeaef72ecf6e005d"] },
                  "type": { "type": "string", "enum": ["cashback", "accessory", "finance"], "example": "cashback" },
                  "value": { "type": "number", "example": 15, "description": "Percentage discount" },
                  "stackable": { "type": "boolean", "example": false },
                  "validFrom": { "type": "string", "format": "date", "example": "2024-06-01" },
                  "validTo": { "type": "string", "format": "date", "example": "2024-08-31" },
                  "status": { "type": "string", "enum": ["active", "inactive"], "example": "active" }
                },
                "required": ["name", "validFrom", "validTo"],
                "example": {
                  "name": "Summer Sale 2024 - VF8 Special",
                  "scope": "byDealer",
                  "dealers": ["68f90ebebeaef72ecf6e005a"],
                  "variants": ["68f90ebebeaef72ecf6e005c"],
                  "type": "cashback",
                  "value": 15,
                  "stackable": false,
                  "validFrom": "2024-06-01",
                  "validTo": "2024-08-31",
                  "status": "active"
                }
              }
            }
          }
        },
        "responses": { "201": { "description": "Promotion created" } }
      }
    },
    "/api/promotions/{id}": {
      "put": {
        "tags": ["Promotions"],
        "summary": "Cập nhật khuyến mãi",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": { "type": "string" },
                  "scope": { "type": "string", "enum": ["global", "byDealer", "byVariant"] },
                  "dealers": { "type": "array", "items": { "type": "string" } },
                  "variants": { "type": "array", "items": { "type": "string" } },
                  "type": { "type": "string", "enum": ["cashback", "accessory", "finance"] },
                  "value": { "type": "number" },
                  "stackable": { "type": "boolean" },
                  "validFrom": { "type": "string", "format": "date" },
                  "validTo": { "type": "string", "format": "date" },
                  "status": { "type": "string", "enum": ["active", "inactive"] }
                }
              }
            }
          }
        },
        "responses": { "200": { "description": "Promotion updated" } }
      },
      "delete": {
        "tags": ["Promotions"],
        "summary": "Xóa khuyến mãi",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Promotion deleted" } }
      }
    },
    "/api/customers": {
      "get": {
        "tags": ["Customers"],
        "summary": "Liệt kê khách hàng",
        "responses": { "200": { "description": "Customer list" } }
      },
      "post": {
        "tags": ["Customers"],
        "summary": "Tạo khách hàng",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "fullName": { "type": "string", "example": "Nguyen Van A" },
                  "email": { "type": "string", "example": "nguyenvana@gmail.com" },
                  "phone": { "type": "string", "example": "0901234567" },
                  "address": { "type": "string", "example": "123 Tran Hung Dao, Hoan Kiem, Hanoi" },
                  "notes": { "type": "string", "example": "Very interested in VF8 Premium. Budget around 6.5 billion VND" }
                },
                "required": ["fullName", "phone"],
                "example": {
                  "fullName": "Nguyen Minh Khoa",
                  "email": "khoa.nguyen@gmail.com",
                  "phone": "0906789123",
                  "address": "456 Le Loi Street, District 1, Ho Chi Minh City",
                  "notes": "Interested in VF8 Premium, prefers white color, needs delivery within 2 months"
                }
              }
            }
          }
        },
        "responses": { "201": { "description": "Customer created" } }
      }
    },
    "/api/customers/{id}": {
      "get": {
        "tags": ["Customers"],
        "summary": "Lấy chi tiết khách hàng theo ID",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Customer details" } }
      },
      "patch": {
        "tags": ["Customers"],
        "summary": "Cập nhật khách hàng",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "fullName": { "type": "string" },
                  "email": { "type": "string" },
                  "phone": { "type": "string" },
                  "address": { "type": "string" },
                  "notes": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": { "200": { "description": "Customer updated" } }
      },
      "delete": {
        "tags": ["Customers"],
        "summary": "Xóa khách hàng",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Customer deleted" } }
      }
    },
    "/api/test-drives": {
      "get": {
        "tags": ["TestDrives"],
        "summary": "Liệt kê lịch lái thử",
        "responses": { "200": { "description": "Test drive list" } }
      },
      "post": {
        "tags": ["TestDrives"],
        "summary": "Tạo lịch lái thử",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "customer": { "type": "string", "description": "Customer ID", "example": "68f90ebebeaef72ecf6e005a" },
                  "dealer": { "type": "string", "description": "Dealer ID", "example": "68f90ebebeaef72ecf6e005b" },
                  "variant": { "type": "string", "description": "VehicleVariant ID", "example": "68f90ebebeaef72ecf6e005c" },
                  "preferredTime": { "type": "string", "format": "date-time", "example": "2024-12-25T14:00:00Z" },
                  "status": { "type": "string", "enum": ["pending", "confirmed", "done", "cancelled"], "example": "pending" },
                  "assignedStaff": { "type": "string", "description": "User ID of assigned staff", "example": "68f90ebebeaef72ecf6e005d" },
                  "result": {
                    "type": "object",
                    "properties": {
                      "feedback": { "type": "string", "example": "Customer very satisfied with performance" },
                      "interestRate": { "type": "number", "example": 90 }
                    }
                  }
                },
                "required": ["customer", "dealer", "variant", "preferredTime"],
                "example": {
                  "customer": "68f90ebebeaef72ecf6e005a",
                  "dealer": "68f90ebebeaef72ecf6e005b",
                  "variant": "68f90ebebeaef72ecf6e005c",
                  "preferredTime": "2024-12-26T10:00:00Z",
                  "status": "confirmed",
                  "assignedStaff": "68f90ebebeaef72ecf6e005d"
                }
              }
            }
          }
        },
        "responses": { "201": { "description": "Test drive created" } }
      }
    },
    "/api/test-drives/{id}": {
      "get": {
        "tags": ["TestDrives"],
        "summary": "Lấy chi tiết lịch lái thử theo ID",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Test drive details" } }
      },
      "patch": {
        "tags": ["TestDrives"],
        "summary": "Cập nhật lịch lái thử",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "preferredTime": { "type": "string", "format": "date-time" },
                  "status": { "type": "string", "enum": ["pending", "confirmed", "done", "cancelled"] },
                  "assignedStaff": { "type": "string", "description": "User ID" },
                  "result": {
                    "type": "object",
                    "properties": {
                      "feedback": { "type": "string" },
                      "interestRate": { "type": "number" }
                    }
                  }
                },
                "example": {
                  "status": "done",
                  "result": {
                    "feedback": "Customer loved the autopilot feature and smooth acceleration",
                    "interestRate": 95
                  }
                }
              }
            }
          }
        },
        "responses": { "200": { "description": "Test drive updated" } }
      },
      "delete": {
        "tags": ["TestDrives"],
        "summary": "Xóa lịch lái thử",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Test drive deleted" } }
      }
    },
    "/api/quotes": {
      "get": {
        "tags": ["Quotes"],
        "summary": "Liệt kê báo giá",
        "responses": { "200": { "description": "Quote list" } }
      },
      "post": {
        "tags": ["Quotes"],
        "summary": "Tạo báo giá",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "customer": { "type": "string", "description": "Customer ID", "example": "68f90ebebeaef72ecf6e005a" },
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "variant": { "type": "string", "description": "VehicleVariant ID" },
                        "color": { "type": "string", "description": "VehicleColor ID" },
                        "qty": { "type": "number", "example": 1 },
                        "unitPrice": { "type": "number", "example": 6500000000 }
                      }
                    }
                  },
                  "subtotal": { "type": "number", "example": 6500000000 },
                  "discount": { "type": "number", "example": 650000000 },
                  "total": { "type": "number", "example": 5850000000 },
                  "validUntil": { "type": "string", "format": "date", "example": "2024-12-31" },
                  "notes": { "type": "string", "example": "Special discount for VIP customer - 10% off" }
                },
                "required": ["customer", "items"],
                "example": {
                  "customer": "68f90ebebeaef72ecf6e005a",
                  "items": [
                    {
                      "variant": "68f90ebebeaef72ecf6e005c",
                      "color": "68f90ebebeaef72ecf6e005d",
                      "qty": 1,
                      "unitPrice": 6500000000
                    }
                  ],
                  "subtotal": 6500000000,
                  "discount": 650000000,
                  "total": 5850000000,
                  "validUntil": "2024-12-31",
                  "notes": "VF8 Premium in Pearl White - Summer promotion 10% discount applied"
                }
              }
            }
          }
        },
        "responses": { "201": { "description": "Quote created" } }
      }
    },
    "/api/quotes/{id}": {
      "get": {
        "tags": ["Quotes"],
        "summary": "Lấy chi tiết báo giá theo ID",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Quote details" } }
      },
      "patch": {
        "tags": ["Quotes"],
        "summary": "Cập nhật báo giá",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "status": { "type": "string", "enum": ["draft", "sent", "accepted", "rejected"] },
                  "subtotal": { "type": "number" },
                  "discount": { "type": "number" },
                  "total": { "type": "number" },
                  "validUntil": { "type": "string", "format": "date" },
                  "notes": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": { "200": { "description": "Quote updated" } }
      },
      "delete": {
        "tags": ["Quotes"],
        "summary": "Xóa báo giá",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Quote deleted" } }
      }
    },
    "/api/quotes/{id}/convert": { "put": { "tags": ["Quotes"], "summary": "Chuyển báo giá thành đơn hàng", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Đã tạo đơn hàng từ báo giá" } } } },
    "/api/orders": {
      "get": {
        "tags": ["Orders"],
        "summary": "Liệt kê đơn hàng",
        "responses": { "200": { "description": "Order list" } }
      },
      "post": {
        "tags": ["Orders"],
        "summary": "Tạo đơn hàng",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "customer": { "type": "string", "description": "Customer ID", "example": "68f90ebebeaef72ecf6e005a" },
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "variant": { "type": "string", "description": "VehicleVariant ID" },
                        "color": { "type": "string", "description": "VehicleColor ID" },
                        "qty": { "type": "number", "example": 1 },
                        "unitPrice": { "type": "number", "example": 6500000000 }
                      }
                    }
                  },
                  "paymentMethod": { "type": "string", "enum": ["cash", "finance"], "example": "finance" },
                  "deposit": { "type": "number", "example": 1950000000, "description": "30% deposit for finance" }
                },
                "required": ["customer", "items"],
                "example": {
                  "customer": "68f90ebebeaef72ecf6e005a",
                  "items": [
                    {
                      "variant": "68f90ebebeaef72ecf6e005c",
                      "color": "68f90ebebeaef72ecf6e005d",
                      "qty": 1,
                      "unitPrice": 6500000000
                    }
                  ],
                  "paymentMethod": "finance",
                  "deposit": 1950000000
                }
              }
            }
          }
        },
        "responses": { "201": { "description": "Order created" } }
      }
    },
    "/api/orders/{id}": {
      "get": {
        "tags": ["Orders"],
        "summary": "Lấy chi tiết đơn hàng theo ID",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Order details" } }
      },
      "patch": {
        "tags": ["Orders"],
        "summary": "Cập nhật đơn hàng",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "status": { "type": "string", "enum": ["new", "confirmed", "allocated", "invoiced", "delivered", "cancelled"] },
                  "paymentMethod": { "type": "string", "enum": ["cash", "finance"] },
                  "deposit": { "type": "number" },
                  "actualDelivery": { "type": "string", "format": "date" }
                }
              }
            }
          }
        },
        "responses": { "200": { "description": "Order updated" } }
      },
      "delete": {
        "tags": ["Orders"],
        "summary": "Xóa đơn hàng",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Order deleted" } }
      }
    },
    "/api/orders/{id}/status": { "put": { "tags": ["Orders"], "summary": "Cập nhật trạng thái đơn hàng", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": ["new", "confirmed", "allocated", "invoiced", "delivered", "cancelled"] } }, "required": ["status"], "example": { "status": "confirmed" } } } } }, "responses": { "200": { "description": "Cập nhật thành công" } } } },
    "/api/orders/{id}/payment": { "put": { "tags": ["Orders"], "summary": "Gắn thông tin thanh toán vào đơn hàng", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentId": { "type": "string" } }, "required": ["paymentId"], "example": { "paymentId": "68f9...0abc" } } } } }, "responses": { "200": { "description": "Đã ghi nhận thanh toán vào log đơn hàng" } } } },
    "/api/orders/{id}/delivery": { "put": { "tags": ["Orders"], "summary": "Gắn thông tin giao xe vào đơn hàng", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "actualDelivery": { "type": "string", "format": "date" }, "deliveryNote": { "type": "string" } }, "example": { "actualDelivery": "2024-12-28", "deliveryNote": "Delivered to customer home" } } } } }, "responses": { "200": { "description": "Đã cập nhật thông tin giao hàng" } } } },
    "/api/contracts": {
      "get": {
        "tags": ["Contracts"],
        "summary": "Liệt kê hợp đồng",
        "description": "Lấy danh sách tất cả hợp đồng bán hàng. Trả về kèm thông tin order, dealer, customer, và sales.",
        "responses": {
          "200": {
            "description": "Danh sách hợp đồng",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/SalesContract"
                  }
                }
              }
            }
          },
          "500": { "description": "Server error" }
        }
      },
      "post": {
        "tags": ["Contracts"],
        "summary": "Tạo hợp đồng",
        "description": "Tạo hợp đồng bán hàng mới cho một order",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "order": { "type": "string", "description": "Order ID (required)", "example": "6905cfa31994fa0215b2cb1f" },
                  "contractNo": { "type": "string", "description": "Số hợp đồng (required)", "example": "HD-2024-001" },
                  "signedDate": { "type": "string", "format": "date", "description": "Ngày ký hợp đồng", "example": "2024-01-15" },
                  "files": { 
                    "type": "array", 
                    "items": { "type": "string" },
                    "description": "Danh sách đường dẫn file hợp đồng",
                    "example": ["/uploads/contracts/hd-2024-001.pdf"]
                  },
                  "terms": { "type": "string", "description": "Điều khoản hợp đồng", "example": "Thanh toán 30% khi ký hợp đồng, 70% khi nhận xe" },
                  "status": { "type": "string", "enum": ["draft", "signed", "cancelled"], "description": "Trạng thái hợp đồng", "example": "draft", "default": "draft" }
                },
                "required": ["order", "contractNo"],
                "example": {
                  "order": "6905cfa31994fa0215b2cb1f",
                  "contractNo": "HD-2024-001",
                  "signedDate": "2024-01-15",
                  "terms": "Thanh toán 30% khi ký hợp đồng, 70% khi nhận xe. Giao xe trong vòng 30 ngày.",
                  "status": "draft"
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Hợp đồng đã được tạo",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SalesContract"
                }
              }
            }
          },
          "400": { "description": "Validation error" }
        }
      }
    },
    "/api/contracts/{id}": {
      "get": {
        "tags": ["Contracts"],
        "summary": "Lấy chi tiết hợp đồng theo ID",
        "description": "Lấy thông tin chi tiết của một hợp đồng bán hàng. Trả về kèm thông tin order, dealer, customer, và sales.",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "SalesContract ID" }],
        "responses": {
          "200": {
            "description": "Chi tiết hợp đồng",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SalesContract"
                }
              }
            }
          },
          "404": { "description": "Contract not found" }
        }
      },
      "put": {
        "tags": ["Contracts"],
        "summary": "Cập nhật hợp đồng (PUT)",
        "description": "Cập nhật toàn bộ thông tin hợp đồng. Role: DealerManager, Admin",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "SalesContract ID" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "order": { "type": "string", "description": "Order ID" },
                  "contractNo": { "type": "string", "description": "Số hợp đồng" },
                  "signedDate": { "type": "string", "format": "date" },
                  "files": { "type": "array", "items": { "type": "string" } },
                  "terms": { "type": "string" },
                  "status": { "type": "string", "enum": ["draft", "signed", "cancelled"] }
                },
                "example": {
                  "contractNo": "HD-2024-001",
                  "signedDate": "2024-01-15",
                  "terms": "Cập nhật điều khoản thanh toán",
                  "status": "signed"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Hợp đồng đã được cập nhật",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SalesContract"
                }
              }
            }
          },
          "400": { "description": "Validation error" },
          "404": { "description": "Contract not found" }
        }
      },
      "patch": {
        "tags": ["Contracts"],
        "summary": "Cập nhật hợp đồng (PATCH)",
        "description": "Cập nhật một phần thông tin hợp đồng. Role: DealerManager, Admin",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "SalesContract ID" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "contractNo": { "type": "string", "description": "Số hợp đồng" },
                  "signedDate": { "type": "string", "format": "date", "description": "Ngày ký hợp đồng" },
                  "files": { "type": "array", "items": { "type": "string" }, "description": "Danh sách file hợp đồng" },
                  "terms": { "type": "string", "description": "Điều khoản hợp đồng" },
                  "status": { "type": "string", "enum": ["draft", "signed", "cancelled"], "description": "Trạng thái hợp đồng" }
                },
                "example": {
                  "signedDate": "2024-01-20",
                  "terms": "Cập nhật điều khoản thanh toán: 40% khi ký, 60% khi nhận xe",
                  "status": "signed"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Hợp đồng đã được cập nhật",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SalesContract"
                }
              }
            }
          },
          "400": { "description": "Validation error" },
          "404": { "description": "Contract not found" }
        }
      }
    },
    "/api/payments": {
      "get": {
        "tags": ["Payments"],
        "summary": "Liệt kê thanh toán (có phân trang)",
        "description": "Lấy danh sách tất cả thanh toán với phân trang. Admin xem tất cả, DealerStaff/DealerManager chỉ xem thanh toán của dealer mình.",
        "parameters": [
          { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 }, "description": "Số trang" },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10 }, "description": "Số lượng mục mỗi trang" }
        ],
        "responses": {
          "200": {
            "description": "Danh sách thanh toán",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean", "example": true },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "_id": { "type": "string" },
                          "order": {
                            "type": "object",
                            "properties": {
                              "_id": { "type": "string" },
                              "orderNo": { "type": "string" },
                              "dealer": { "type": "string" },
                              "customer": {
                                "type": "object",
                                "properties": {
                                  "_id": { "type": "string" },
                                  "fullName": { "type": "string" },
                                  "phone": { "type": "string" }
                                }
                              }
                            }
                          },
                          "type": { "type": "string", "enum": ["deposit", "balance", "installment"] },
                          "amount": { "type": "number" },
                          "method": { "type": "string", "enum": ["cash", "bank", "card"] },
                          "transactionRef": { "type": "string" },
                          "paidAt": { "type": "string", "format": "date-time" },
                          "status": { "type": "string", "enum": ["pending", "confirmed", "failed"] },
                          "notes": { "type": "string" },
                          "createdAt": { "type": "string", "format": "date-time" },
                          "updatedAt": { "type": "string", "format": "date-time" }
                        }
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "properties": {
                        "page": { "type": "integer" },
                        "limit": { "type": "integer" },
                        "total": { "type": "integer" },
                        "pages": { "type": "integer" }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": { "description": "Tài khoản đại lý chưa được liên kết với đại lý nào" },
          "500": { "description": "Server error" }
        }
      },
      "post": {
        "tags": ["Payments"],
        "summary": "Tạo thanh toán",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "order": { "type": "string", "description": "Order ID", "example": "68f90ebebeaef72ecf6e005a" },
                  "type": { "type": "string", "enum": ["deposit", "balance", "installment"], "example": "deposit" },
                  "amount": { "type": "number", "example": 1950000000 },
                  "method": { "type": "string", "enum": ["cash", "bank", "card"], "example": "bank" },
                  "transactionRef": { "type": "string", "example": "TXN-2024-001234" },
                  "paidAt": { "type": "string", "format": "date-time", "example": "2024-12-20T10:30:00Z" },
                  "status": { "type": "string", "enum": ["pending", "confirmed", "failed"], "example": "confirmed" },
                  "notes": { "type": "string", "example": "30% deposit payment via bank transfer" }
                },
                "required": ["order", "type", "amount", "method"],
                "example": {
                  "order": "68f90ebebeaef72ecf6e005a",
                  "type": "deposit",
                  "amount": 1950000000,
                  "method": "bank",
                  "transactionRef": "TXN-2024-001234",
                  "paidAt": "2024-12-20T10:30:00Z",
                  "status": "confirmed",
                  "notes": "30% deposit for VF8 Premium - Customer: Nguyen Minh Khoa"
                }
              }
            }
          }
        },
        "responses": { "201": { "description": "Payment created" } }
      }
    },
    "/api/payments/{orderId}": { "get": { "tags": ["Payments"], "summary": "Lấy thanh toán theo đơn hàng", "parameters": [{ "name": "orderId", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Danh sách thanh toán của đơn" } } } },
    "/api/payments/{id}/status": { "put": { "tags": ["Payments"], "summary": "Cập nhật trạng thái thanh toán", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": ["pending", "confirmed", "failed"] } }, "required": ["status"], "example": { "status": "confirmed" } } } } }, "responses": { "200": { "description": "Cập nhật thành công" } } } },
    "/api/dealers": {
      "get": {
        "tags": ["Dealers"],
        "summary": "Liệt kê đại lý",
        "responses": { "200": { "description": "Dealer list" } }
      },
      "post": {
        "tags": ["Dealers"],
        "summary": "Tạo đại lý",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": { "type": "string", "example": "Hanoi EV Premium Dealer" },
                  "code": { "type": "string", "example": "HAN002" },
                  "region": { "type": "string", "example": "North" },
                  "address": { "type": "string", "example": "789 Lang Ha Street, Dong Da District, Hanoi" },
                  "contacts": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": { "type": "string", "example": "Nguyen Van Manager" },
                        "phone": { "type": "string", "example": "0904567890" },
                        "email": { "type": "string", "example": "manager@hanoievdealer.com" }
                      }
                    },
                    "example": [
                      {
                        "name": "Nguyen Van Manager",
                        "phone": "0904567890",
                        "email": "manager@hanoievdealer.com"
                      },
                      {
                        "name": "Tran Thi Sales",
                        "phone": "0905678901",
                        "email": "sales@hanoievdealer.com"
                      }
                    ]
                  },
                  "creditLimit": { "type": "number", "example": 1500000000 },
                  "status": { "type": "string", "enum": ["active", "inactive"], "example": "active" }
                },
                "required": ["name", "code"],
                "example": {
                  "name": "Hai Phong EV Dealer",
                  "code": "HP001",
                  "region": "North",
                  "address": "456 Tran Phu Street, Hong Bang, Hai Phong",
                  "contacts": [
                    {
                      "name": "Le Van Director",
                      "phone": "0907890123",
                      "email": "director@haiphongevdealer.com"
                    }
                  ],
                  "creditLimit": 1200000000,
                  "status": "active"
                }
              }
            }
          }
        },
        "responses": { "201": { "description": "Dealer created" } }
      }
    },
    "/api/dealers/{id}": {
      "get": {
        "tags": ["Dealers"],
        "summary": "Lấy chi tiết đại lý theo ID",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Dealer details" } }
      },
      "patch": {
        "tags": ["Dealers"],
        "summary": "Cập nhật đại lý",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": { "type": "string" },
                  "code": { "type": "string" },
                  "region": { "type": "string" },
                  "address": { "type": "string" },
                  "contacts": { "type": "array", "items": { "type": "object" } },
                  "creditLimit": { "type": "number" },
                  "status": { "type": "string", "enum": ["active", "inactive"] }
                }
              }
            }
          }
        },
        "responses": { "200": { "description": "Dealer updated" } }
      },
      "delete": {
        "tags": ["Dealers"],
        "summary": "Xóa đại lý",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Dealer deleted" } }
      }
    },
    "/api/dealers/{id}/inventory": { "get": { "tags": ["Dealers"], "summary": "Xem tồn kho tại đại lý", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Tồn kho đại lý" } } } },
    "/api/dealers/{id}/target": { "put": { "tags": ["Dealers"], "summary": "Cập nhật chỉ tiêu doanh số", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "salesTarget": { "type": "number" } }, "required": ["salesTarget"], "example": { "salesTarget": 100 } } } } }, "responses": { "200": { "description": "Đã cập nhật chỉ tiêu" } } } },
    "/api/reports/sales": {
      "get": {
        "tags": ["Reports"],
        "summary": "Báo cáo doanh số",
        "description": "Lấy báo cáo doanh số theo khoảng thời gian và đại lý",
        "parameters": [
          { "name": "startDate", "in": "query", "schema": { "type": "string", "format": "date" } },
          { "name": "endDate", "in": "query", "schema": { "type": "string", "format": "date" } },
          { "name": "dealerId", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Sales report data" } }
      }
    },
    "/api/reports/inventory": {
      "get": {
        "tags": ["Reports"],
        "summary": "Báo cáo tồn kho",
        "description": "Lấy báo cáo tồn kho kèm cảnh báo sắp hết hàng",
        "responses": { "200": { "description": "Inventory report data" } }
      }
    },
    "/api/reports/debt": {
      "get": {
        "tags": ["Reports"],
        "summary": "Báo cáo công nợ",
        "description": "Lấy báo cáo công nợ của đại lý",
        "responses": { "200": { "description": "Debt report data" } }
      }
    },
    "/api/deliveries": { "post": { "tags": ["Deliveries"], "summary": "Tạo phiếu giao xe", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "order": { "type": "string" }, "address": { "type": "string" }, "scheduledAt": { "type": "string", "format": "date-time" }, "notes": { "type": "string" } }, "required": ["order"], "example": { "order": "68f9...abcd", "address": "123 Trần Hưng Đạo, Hà Nội", "scheduledAt": "2024-12-27T09:00:00Z" } } } } }, "responses": { "201": { "description": "Đã tạo phiếu giao xe" } } } },
    "/api/deliveries/{id}/status": { "put": { "tags": ["Deliveries"], "summary": "Cập nhật tiến độ giao xe", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": ["pending", "in_progress", "delivered"] } }, "required": ["status"], "example": { "status": "in_progress" } } } } }, "responses": { "200": { "description": "Đã cập nhật trạng thái" } } } },
    "/api/deliveries/{orderId}": { "get": { "tags": ["Deliveries"], "summary": "Xem thông tin giao hàng theo đơn", "parameters": [{ "name": "orderId", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Danh sách phiếu giao cho đơn" } } } },
    "/api/feedbacks": { "get": { "tags": ["Feedbacks"], "summary": "Danh sách phản hồi", "responses": { "200": { "description": "Danh sách phản hồi" } } }, "post": { "tags": ["Feedbacks"], "summary": "Tạo phản hồi khách hàng", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer": { "type": "string" }, "dealer": { "type": "string" }, "content": { "type": "string" } }, "required": ["content"], "example": { "customer": "68f9...00cc", "content": "Nhân viên tư vấn rất nhiệt tình" } } } } }, "responses": { "201": { "description": "Đã tạo phản hồi" } } } },
    "/api/feedbacks/{id}/status": { "put": { "tags": ["Feedbacks"], "summary": "Cập nhật xử lý phản hồi", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": ["new", "in_progress", "resolved"] } }, "required": ["status"], "example": { "status": "resolved" } } } } }, "responses": { "200": { "description": "Đã cập nhật trạng thái" } } } },
    "/api/dashboard/summary": { "get": { "tags": ["Dashboard"], "summary": "Tổng quan hệ thống", "responses": { "200": { "description": "Số liệu tổng quan" } } } },
    "/api/dashboard/trends": { "get": { "tags": ["Dashboard"], "summary": "Xu hướng bán hàng 30 ngày", "responses": { "200": { "description": "Dữ liệu theo ngày" } } } },
    "/api/users": { "get": { "tags": ["Users"], "summary": "Danh sách tài khoản", "responses": { "200": { "description": "User list" } } } },
    "/api/users/{id}": { 
      "put": { 
        "tags": ["Users"], 
        "summary": "Cập nhật thông tin user", 
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], 
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "role": { 
                    "type": "string", 
                    "enum": ["Admin", "EVMStaff", "DealerManager", "DealerStaff"], 
                    "example": "DealerStaff" 
                  },
                  "profile": {
                    "type": "object",
                    "properties": {
                      "name": { "type": "string", "example": "Nguyen Van A" },
                      "phone": { "type": "string", "example": "0901234567" }
                    }
                  },
                  "dealer": { 
                    "type": "string", 
                    "description": "Dealer ID (required for DealerManager/DealerStaff)", 
                    "example": "68f90ebebeaef72ecf6e005a" 
                  },
                  "status": { 
                    "type": "string", 
                    "enum": ["active", "locked"], 
                    "example": "active" 
                  }
                },
                "example": {
                  "role": "DealerStaff",
                  "profile": {
                    "name": "Nguyen Van A",
                    "phone": "0901234567"
                  },
                  "dealer": "68f90ebebeaef72ecf6e005a",
                  "status": "active"
                }
              }
            }
          }
        },
        "responses": { "200": { "description": "User updated" } } 
      }, 
      "delete": { 
        "tags": ["Users"], 
        "summary": "Xóa tài khoản", 
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], 
        "responses": { "200": { "description": "User deleted" } } 
      } 
    },
    "/api/vehicle-models": {
      "get": {
        "tags": ["VehicleModels"],
        "summary": "Liệt kê các dòng xe (models)",
        "responses": { "200": { "description": "Vehicle model list" } }
      },
      "post": {
        "tags": ["VehicleModels"],
        "summary": "Tạo dòng xe (model)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": { "type": "string", "example": "VF8" },
                  "brand": { "type": "string", "example": "EVM" },
                  "segment": { "type": "string", "example": "Mid-size" },
                  "description": { "type": "string", "example": "Premium electric SUV with advanced features" },
                  "active": { "type": "boolean", "example": true }
                },
                "required": ["name"],
                "example": {
                  "name": "VF9",
                  "brand": "EVM",
                  "segment": "Full-size",
                  "description": "Luxury 7-seater electric SUV",
                  "active": true
                }
              }
            }
          }
        },
        "responses": { "201": { "description": "Vehicle model created" } }
      }
    },
    "/api/vehicle-models/{id}": {
      "get": {
        "tags": ["VehicleModels"],
        "summary": "Lấy chi tiết dòng xe theo ID",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Vehicle model details" } }
      },
      "patch": {
        "tags": ["VehicleModels"],
        "summary": "Cập nhật dòng xe",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": { "type": "string" },
                  "brand": { "type": "string" },
                  "segment": { "type": "string" },
                  "description": { "type": "string" },
                  "active": { "type": "boolean" }
                }
              }
            }
          }
        },
        "responses": { "200": { "description": "Vehicle model updated" } }
      },
      "delete": {
        "tags": ["VehicleModels"],
        "summary": "Xóa dòng xe",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Vehicle model deleted" } }
      }
    },
    "/api/vehicle-colors": {
      "get": {
        "tags": ["VehicleColors"],
        "summary": "Liệt kê màu xe",
        "responses": { "200": { "description": "Vehicle color list" } }
      },
      "post": {
        "tags": ["VehicleColors"],
        "summary": "Tạo màu xe",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": { "type": "string", "example": "Pearl White" },
                  "code": { "type": "string", "example": "PW" },
                  "hex": { "type": "string", "example": "#FFFFFF" },
                  "extraPrice": { "type": "number", "example": 0 },
                  "active": { "type": "boolean", "example": true }
                },
                "required": ["name"],
                "example": {
                  "name": "Midnight Black",
                  "code": "MB",
                  "hex": "#000000",
                  "extraPrice": 0,
                  "active": true
                }
              }
            }
          }
        },
        "responses": { "201": { "description": "Vehicle color created" } }
      }
    },
    "/api/vehicle-colors/{id}": {
      "get": {
        "tags": ["VehicleColors"],
        "summary": "Lấy chi tiết màu xe theo ID",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Vehicle color details" } }
      },
      "patch": {
        "tags": ["VehicleColors"],
        "summary": "Cập nhật màu xe",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": { "type": "string" },
                  "code": { "type": "string" },
                  "hex": { "type": "string" },
                  "extraPrice": { "type": "number" },
                  "active": { "type": "boolean" }
                }
              }
            }
          }
        },
        "responses": { "200": { "description": "Vehicle color updated" } }
      },
      "delete": {
        "tags": ["VehicleColors"],
        "summary": "Xóa màu xe",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Vehicle color deleted" } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    },
    "schemas": {
      "SalesContract": {
        "type": "object",
        "properties": {
          "_id": {
            "type": "string",
            "description": "Contract ID"
          },
          "order": {
            "oneOf": [
              { "type": "string" },
              {
                "type": "object",
                "description": "Populated Order object with dealer, customer, and sales",
                "properties": {
                  "_id": { "type": "string" },
                  "orderNo": { "type": "string" },
                  "dealer": {
                    "oneOf": [
                      { "type": "string" },
                      {
                        "type": "object",
                        "properties": {
                          "_id": { "type": "string" },
                          "name": { "type": "string" }
                        }
                      }
                    ]
                  },
                  "customer": {
                    "oneOf": [
                      { "type": "string" },
                      {
                        "type": "object",
                        "properties": {
                          "_id": { "type": "string" },
                          "name": { "type": "string" },
                          "email": { "type": "string" },
                          "phone": { "type": "string" }
                        }
                      }
                    ]
                  },
                  "sales": {
                    "oneOf": [
                      { "type": "string" },
                      {
                        "type": "object",
                        "properties": {
                          "_id": { "type": "string" },
                          "name": { "type": "string" },
                          "email": { "type": "string" }
                        }
                      }
                    ]
                  },
                  "status": { "type": "string" },
                  "total": { "type": "number" }
                }
              }
            ],
            "description": "Order ID or populated Order object"
          },
          "contractNo": {
            "type": "string",
            "description": "Số hợp đồng",
            "example": "HD-2024-001"
          },
          "signedDate": {
            "type": "string",
            "format": "date",
            "description": "Ngày ký hợp đồng",
            "nullable": true
          },
          "files": {
            "type": "array",
            "items": { "type": "string" },
            "description": "Danh sách đường dẫn file hợp đồng",
            "default": []
          },
          "terms": {
            "type": "string",
            "description": "Điều khoản hợp đồng",
            "nullable": true
          },
          "status": {
            "type": "string",
            "enum": ["draft", "signed", "cancelled"],
            "description": "Trạng thái hợp đồng",
            "default": "draft"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "Ngày tạo"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Ngày cập nhật"
          }
        },
        "required": ["order", "contractNo"]
      }
    }
  }
}