{
  "openapi": "3.1.0",
  "info": {
    "title": "PlusFacility.cz API",
    "description": "Mobilně orientovaná platforma pro hlášení závad, posouzení dispečinkem, schválení nákladů pronajímatelem a koordinaci údržby nemovitostí.",
    "version": "2.0.0",
    "contact": {
      "name": "PlusFacility Support",
      "email": "info@plusfacility.cz",
      "url": "https://plusfacility.cz"
    }
  },
  "servers": [
    {
      "url": "https://plusfacility.cz",
      "description": "Produkční server"
    }
  ],
  "paths": {
    "/api/health": {
      "get": {
        "summary": "Stav systému a databáze",
        "description": "Vrací stav zdraví aplikace a připojení k databázi.",
        "responses": {
          "200": {
            "description": "Systém je zdravý",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "example": "healthy" },
                    "service": { "type": "string", "example": "PlusFacility.cz" },
                    "version": { "type": "string", "example": "2.0.0" },
                    "timestamp": { "type": "string" },
                    "database": { "type": "string", "example": "connected" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/qr/{token}": {
      "get": {
        "summary": "Ověření QR kódu jednotky",
        "description": "Získá informace o nemovitosti, jednotce, havarijních kontaktech a krátkodobý uploadToken na základě veřejného tokenu.",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "description": "Veřejný token QR kódu",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Detaily jednotky",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "uploadToken": { "type": "string" },
                    "location": {
                      "type": "object",
                      "properties": {
                        "name": { "type": "string" },
                        "type": { "type": "string", "enum": ["UNIT", "COMMON_AREA"] },
                        "floor": { "type": "string", "nullable": true },
                        "propertyName": { "type": "string" },
                        "address": { "type": "string" },
                        "emergencyContact": { "type": "string", "nullable": true }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": { "description": "QR kód neexistuje nebo byl deaktivován" }
        }
      }
    },
    "/api/incidents": {
      "get": {
        "summary": "Seznam hlášení a oprav",
        "description": "Vrací seznam hlášení pro přihlášeného uživatele podle role a oprávnění.",
        "responses": {
          "200": { "description": "Seznam hlášení" },
          "401": { "description": "Neautorizovaný přístup" }
        }
      },
      "post": {
        "summary": "Nahlášení nové závady",
        "description": "Vytvoří nové hlášení závady na základě aktivního QR tokenu jednotky. Vyžaduje alespoň reporterEmail nebo reporterPhone.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["qrToken", "category", "title", "description", "reporterName"],
                "properties": {
                  "qrToken": { "type": "string", "example": "b9f8a12c4d5e" },
                  "uploadToken": { "type": "string" },
                  "category": {
                    "type": "string",
                    "enum": ["PLUMBING", "ELECTRICAL", "HEATING", "GAS", "DOORS_LOCKS", "APPLIANCES", "COMMON_AREAS", "CLEANING", "OTHER"]
                  },
                  "title": { "type": "string", "example": "Protékající toaleta" },
                  "description": { "type": "string", "example": "Voda neustále protéká do mísy po spláchnutí." },
                  "urgency": { "type": "string", "enum": ["NORMAL", "URGENT", "EMERGENCY"], "default": "NORMAL" },
                  "reporterName": { "type": "string", "example": "Petr Novák" },
                  "reporterPhone": { "type": "string", "example": "+420777888999" },
                  "reporterEmail": { "type": "string", "example": "petr.novak@example.cz" },
                  "preferredContact": { "type": "string", "enum": ["EMAIL", "PHONE"] },
                  "accessNotes": { "type": "string", "example": "Dopoledne bývám doma" },
                  "attachmentIds": {
                    "type": "array",
                    "items": { "type": "string", "format": "uuid" }
                  },
                  "requestId": { "type": "string", "format": "uuid" }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Hlášení úspěšně vytvořeno",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "incidentNumber": { "type": "string", "example": "INC-2026-0001" },
                    "trackingToken": { "type": "string" },
                    "trackingUrl": { "type": "string" },
                    "notificationStatus": { "type": "string" },
                    "replayed": { "type": "boolean" },
                    "message": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/incidents/lookup-by-token": {
      "get": {
        "summary": "Sledování incidentu přes magic token",
        "description": "Vrací kompletní stav incidentu, časovou osu a termíny pro nájemníka.",
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": false,
            "description": "Bezpečný přístupový token nájemníka (lze předat také v hlavičce x-tracking-token)",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": { "description": "Informace o incidentu" },
          "404": { "description": "Neplatný nebo vypršený token" }
        }
      },
      "post": {
        "summary": "Bezpečné vyhledání incidentu podle tokenu",
        "description": "Získá veřejné informace o incidentu pro nájemníka bez exponování tokenu v URL adrese.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["token"],
                "properties": {
                  "token": { "type": "string", "description": "Přístupový token nájemníka" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Informace o incidentu" },
          "404": { "description": "Neplatný nebo vypršený token" }
        }
      }
    },
    "/api/mcp": {
      "post": {
        "summary": "Model Context Protocol JSON-RPC Endpoint",
        "description": "Přímé strojové rozhraní pro AI agenty (tools/list, tools/call, resources/list).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "jsonrpc": { "type": "string", "example": "2.0" },
                  "method": { "type": "string", "example": "tools/call" },
                  "params": { "type": "object" },
                  "id": { "type": "string", "example": "1" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "JSON-RPC výsledek (pouze při ENABLE_MCP_AGENT=true)" },
          "503": { "description": "Rozhraní MCP je v uzavřeném betatestu dočasně pozastaveno" }
        }
      }
    },
    "/api/agent": {
      "post": {
        "summary": "Agent-to-Agent (A2A) Coordination Endpoint",
        "description": "Rozhraní pro koordinaci mezi externími agenty a PlusFacility (v uzavřeném betatestu pozastaveno).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["action"],
                "properties": {
                  "action": { "type": "string" },
                  "payload": { "type": "object" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Výsledek akce agenta (pouze při ENABLE_MCP_AGENT=true)" },
          "503": { "description": "Rozhraní A2A je v uzavřeném betatestu dočasně pozastaveno" }
        }
      }
    }
  }
}