# PlusFacility.cz – Rozšířená systémová dokumentace pro AI agenty

> Kompletní technická specifikace, datový model, stavový diagram a aplikační rozhraní platformy pro správu a údržbu nemovitostí.

---

## 1. Architektura a principy fungování

PlusFacility.cz je postaven jako modulární monolit v Next.js 14 (App Router) s relační databází PostgreSQL 18 a Prisma ORM.

### Klíčové principy:
1. **Zero-friction reporting:** Nájemníci nemusí instalovat nativní aplikaci ani zakládat účet. Každá jednotka má unikátní QR token (např. `masaryk-byt-03`).
2. **Bezpečný magic tracking:** Po odeslání hlášení nájemník obdrží jednorázový odkaz `/sledovat/[token]`. Token je v databázi uložen výhradně jako kryptografický hash (SHA-256).
3. **Multi-tenant organizace:** Nemovitosti a data jsou striktně odděleny mezi jednotlivými pronajímateli (např. Bytová správa Ostrava Centrum s.r.o. vs. Residomo Poruba Invest a.s.).
4. **Celočíselná měna:** Veškeré částky jsou evidovány v celých jednotkách CZK bez zaokrouhlovacích chyb.

---

## 2. Životní cyklus hlášení / opravy (Stavový automat)

```
[NEW] (Nové hlášení od nájemníka)
  │
  ├──> [IN_REVIEW] (Dispečer posoudil hlášení a upravil kategorii/naléhavost)
  │      │
  │      ├──> [AWAITING_APPROVAL] (Vytvořena cenová nabídka nad limit pro pronajímatele)
  │      │      │
  │      │      ├──> [IN_PROGRESS] (Schváleno a předáno technikovi k realizaci)
  │      │      └──> [CANCELLED] (Pronajímatel nabídku zamítl / případ zrušen)
  │      │
  │      └──> [IN_PROGRESS] (Automaticky schváleno do limitu nebo přímo přiřazeno technikovi)
  │             │
  │             └──> [PENDING_INSPECTION] (Technik dokončil práci, čeká na kontrolu dispečinku)
  │                    │
  │                    └──> [RESOLVED_CLOSED] (Kontrola dokončena a případ uzavřen)
```

---

## 3. Kategorie a naléhavosti

### Kategorie závad (`category`):
- `PLUMBING`: Voda, odpady, kanalizace, sanitární technika
- `ELECTRICAL`: Elektroinstalace, jističe, zásuvky, osvětlení
- `HEATING`: Topení, radiátory, kotle, termostaty
- `GAS`: Plyn, plynové přípojky a spotřebiče (automaticky povýšeno na `EMERGENCY`)
- `DOORS_LOCKS`: Dveře, okna, zámky, kování
- `APPLIANCES`: Vestavěné a dodané spotřebiče, digestoře, sporáky
- `COMMON_AREAS`: Společné prostory domu (chodby, schodiště, výtah, osvětlení)
- `CLEANING`: Úklid a čistota společných prostor
- `OTHER`: Ostatní závady a drobné opravy

### Naléhavosti (`urgency`):
- `NORMAL`: Běžná závada nebo standardní údržba
- `URGENT`: Závažná vada vyžadující přednostní zásah
- `EMERGENCY`: Havárie (únik vody, plyn, výpadek proudu v zimě). Zobrazuje varování s kontaktem na tísňové linky a havarijní kontakt nemovitosti.

---

## 4. REST API Endpointy

### 4.1 Veřejné & Nájemnické endpointy
- `GET /api/qr/{token}`: Ověření platnosti QR kódu a načtení detailů jednotky (`uploadToken`, `location.{name,type,floor,propertyName,address,emergencyContact}`).
- `POST /api/incidents`: Odeslání nového hlášení závady.
  - Body: `{ qrToken, uploadToken, category, title, description, urgency, reporterName, reporterPhone, reporterEmail, preferredContact, accessNotes, attachmentIds, requestId }`
- `GET /api/incidents/lookup-by-token?token={token}` (nebo `POST` s `{ token }`, případně hlavička `x-tracking-token`): Načtení detailu opravy, časové osy a termínu návštěvy.
- `POST /api/incidents/{id}/comments`: Přidání komentáře (vyžaduje session nebo platný sledovací token).
- `POST /api/incidents/{id}/action`: Provedení akce na hlášení (např. potvrzení termínu nebo stavu).

### 4.2 Koordinace & Správa (vyžaduje přihlášení / `pf_session` cookie)
- `GET /api/properties`: Seznam nemovitostí a jednotek organizace.
- `GET /api/incidents`: Seznam hlášení s filtry (`status`, `urgency`, `propertyId`, `locationId`, `search`).
- `GET /api/technicians`: Síť dostupných řemeslníků a jejich specializace.
- `POST /api/quotes/{id}/approve`: Schválení nebo odmítnutí cenové nabídky pronajímatelem / schvalovatelem.
- `GET /api/costs/export`: CSV export nákladů organizace (vlastník, správce, účetní).
- `POST /api/auth/login`: Přihlášení uživatele (e-mail, heslo a volitelný 6místný `totpCode` při zapnutém 2FA).
- `POST /api/auth/change-password`: Změna hesla a správa TOTP 2FA (`SETUP_2FA_INIT`, `SETUP_2FA_CONFIRM`, `DISABLE_2FA`).

---

## 5. Model Context Protocol (MCP) a Agent Rozhraní

Rozhraní MCP (`https://plusfacility.cz/api/mcp`) i A2A (`https://plusfacility.cz/api/agent`) jsou připravena pro strojové integrace (`tools/list`, `tools/call`: `get_unit_by_qr`, `report_incident`, `get_incident_status`, `list_properties`). Během uzavřeného beta provozu (pokud není explicitně povoleno `ENABLE_MCP_AGENT=true`) vracejí HTTP `503`.

---

## 6. Role v systému a lokální testování

| Role | Autentizace | Popis |
|---|---|---|
| Superadmin / Dispečer | E-mail + heslo (+ TOTP 2FA) | Koordinace dispečinku, kalkulace nabídek, přiřazení techniků |
| Pronajímatel (Vlastník / Správce / Schvalovatel / Účetní / Čtenář) | E-mail + heslo (+ TOTP 2FA) | Správa portfolia, schvalování nabídek, exporty nákladů dle týmové role |
| Servisní technik | E-mail + heslo (+ TOTP 2FA) | Návrhy termínů návštěv, zápis práce, materiálu a fotodokumentace |

*Poznámka: V produkci jsou výchozí hesla i testovací přepínače vypnuté. QR štítky a testovací seed účty jsou dostupné pouze v lokálním vývojovém/testovacím prostředí.*