Rozšíření AnthropicGatewayService o per-user kvótový systém (Redis rolling windows 5h + weekly) a fatigue state machine — Gateway před každým Anthropic callem zkontroluje spotřebu, určí stav únavy Marou (FRESH → ASLEEP) a podle něj prohodí model, omezí extended thinking nebo injektuje delay. FE dostává fatigue_envelope v každé Mara odpovědi a zobrazuje odpovídající avatar + notifikace.

• Navazuje na UC-08001 Anthropic Call Gateway — Gateway infrastruktura a api_usage_ledger jsou předpokladem pro tento UC.
• Tracking probíhá v Redis (rolling windows) + PG ledger (audit trail). Redis je pouze výpočetní vrstva; source of truth je ledger.
• Redis deployment: lokální dev / test používá samostatný Redis kontejner (redis:7-alpine, ~/Virtual/Redis/docker-compose.yml, port 6379). Spring Boot se připojuje přes spring.data.redis.host=localhost + spring.data.redis.port=6379. Pro integrační testy: @Testcontainers s redis:7-alpine. Produkční Redis (DO Managed Redis nebo self-hosted Redis pod v K8s) je out-of-scope tohoto UC — viz talkide-infra follow-up issue. Spring Data Redis RedisTemplate API je kompatibilní napříč všemi těmito runtime variantami.
• Configurable kill switch: talkide.gateway.fatigue.enabled (default true). Při false Gateway funguje jako pass-through — žádná kvóta, žádný model swap, žádný delay. Určeno pro lokální vývoj.
• Global emergency brake: při globálním měsíčním spend > 85 % cap → všichni uživatelé posunutí o 1 stupeň fatigue; > 95 % → zmrazení nových konverzací; ≥ 100 % → HTTP 503 pro všechny Anthropic cally.
• Kvóta se kontroluje před turnem (grace finish) — pokud obě windows mají headroom, celý turn proběhne i kdyby mezitím přesáhl limit. Viz ADR-020 Rozhodnutí 5.
• Žádný carry-over nepoužité kvóty — nevyužitý budget z expirované window propadá. Viz ADR-020 Rozhodnutí 3.
• Backend posílá pouze enum + timestamp; lokalizovaný text a message pool jsou výhradně FE zodpovědnost. Viz ADR-020 Rozhodnutí 8.

sequenceDiagram
    actor User

    User->>+FE: odešle zprávu v chatu

    FE->>+BE: POST /api/v1/projects/{projectId}/conversations/{conversationId}/messages <br> Authorization: Bearer {accessToken} <br> SendMessageRequest

    BE->>+SendMessageUseCase: execute(input)

    SendMessageUseCase->>SendMessageUseCase: načti konverzaci, sestav prompt kontext

    SendMessageUseCase->>+AnthropicGatewayService: callAnthropic(userId, GatewayRequest)

    AnthropicGatewayService->>AnthropicGatewayService: zkontroluj fatigue.enabled

    AnthropicGatewayService->>+QuotaCheckService: check(userId)
    Note over QuotaCheckService: Redis Lua script <br> atomická kontrola 5h + weekly

    alt stav ASLEEP (quota 100 %)
        QuotaCheckService-->>AnthropicGatewayService: throws MaraAsleepException(sleepUntilTs)
        AnthropicGatewayService-->>SendMessageUseCase: propaguje výjimku
        SendMessageUseCase-->>BE: propaguje výjimku
        BE-->>FE: 429 Too Many Requests <br> AsleepErrorResponse
        FE-->>User: zobraz "Mara spí" screen + countdown
    end

    QuotaCheckService-->>-AnthropicGatewayService: QuotaStatus(used5hPct, usedWeeklyPct)

    AnthropicGatewayService->>+FatigueResolver: resolve(used5hPct, usedWeeklyPct)
    Note over FatigueResolver: effectiveState = max(5h%, weekly%) <br> FRESH/WARMED_UP/TIRED/GROGGY/EXHAUSTED

    FatigueResolver-->>-AnthropicGatewayService: FatigueState

    AnthropicGatewayService->>AnthropicGatewayService: SlowdownPolicy.apply(state) <br> (model swap, thinking cap, delay)

    alt delay > 0 (GROGGY=500ms, EXHAUSTED=5s)
        AnthropicGatewayService->>AnthropicGatewayService: Mono.delay / Thread.sleep
    end

    AnthropicGatewayService->>+MaraExecutor: startProcess(modifiedRequest)
    Note over MaraExecutor: model swappován dle fatigue state

    MaraExecutor->>Anthropic API: API call (swapped model)
    Anthropic API-->>MaraExecutor: streaming response + usage object
    MaraExecutor-->>-AnthropicGatewayService: onComplete(fullText, usage)

    AnthropicGatewayService->>AnthropicGatewayService: PricingConfig.computeCost(usage)

    AnthropicGatewayService->>+QuotaCheckService: decrementAtomic(userId, costCents)
    Note over QuotaCheckService: Lua script — decrement 5h + weekly atomicky
    QuotaCheckService-->>-AnthropicGatewayService: OK

    AnthropicGatewayService->>DB: INSERT api_usage_ledger <br> (+ fatigue_state_at_request)

    AnthropicGatewayService-->>-SendMessageUseCase: GatewayResponse(content, fatigueEnvelope)

    SendMessageUseCase->>DB: INSERT message (role=PM, content)
    SendMessageUseCase->>DB: UPDATE conversation updatedAt

    SendMessageUseCase-->>-BE: SendMessageOutput

    BE-->>-FE: SSE event: message <br> MessageDto (+ fatigue_envelope)

    FE->>FE: useFatigueStore.update(fatigue_envelope)
    FE->>FE: avatar swap + animace

    alt dosažení prahu notifikace (50 % / 80 %)
        FE-->>User: subtle banner notifikace
    end

    FE-->>-User: zobraz PM odpověď v chatu

HTTP Kontrakt — rozšíření existujícího endpointu

Tento UC neobsahuje nový HTTP endpoint. Modifikuje response existujícího endpointu z UC-04003 Send Message přidáním pole fatigue_envelope.

Úspěšná odpověď — rozšíření MessageDto

200 OK nebo SSE event: message MessageDto (rozšíření stávajícího DTO):

{
  "id": 42,
  "conversationId": 7,
  "role": "PM",
  "content": "Jasně, tady je návrh architektury...",
  "createdAt": "2026-05-08T10:15:30Z",
  "fatigue_envelope": {
    "fatigue_level": "GROGGY",
    "window_5h_pct": 88,
    "window_weekly_pct": 71,
    "sleep_until_ts": null
  }
}

ASLEEP response — 429

429 Too Many Requests AsleepErrorResponse:

{
  "code": "MARA_ASLEEP",
  "message": "Mara je momentálně unavená. Zkus to znovu za chvíli.",
  "sleep_until_ts": "2026-05-08T16:34:00Z",
  "retry_after_seconds": 3240
}

Global emergency brake — 503

503 Service Unavailable ErrorResponse (při globálním monthly cap ≥ 100 %):

{
  "code": "PLATFORM_MAINTENANCE",
  "message": "Platforma je dočasně nedostupná. Zkus to brzy znovu."
}

fatigue_envelope — popis polí

Konfigurační properties

Slowdown policy dle fatigue state

Redis Schema

Žádná nová PostgreSQL tabulka — tracking se zapisuje do existující api_usage_ledger (UC-08001), rozšířené o sloupec fatigue_state_at_request. Redis slouží jako výpočetní vrstva pro real-time kvótu.

Redis keys

Poznámky:

• TTL na window keys zajistí automatický reset bez explicitního cron jobu. Po expiry Redis klíč zmizí → příští request startuje nové okno.
• Atomic check + decrement probíhají v jednom Lua scriptu (EVALSHA) — race-condition free i při souběžných requestech stejného uživatele.
• global:monthly_used_cents se resetuje na začátku každého billing měsíce přes scheduled job (ShedLock protected).

DB rozšíření — api_usage_ledger

Přidání sloupce do existující tabulky z UC-08001 (pre-production, drop-first režim — modifikovat existující Liquibase migraci in-place):

ALTER TABLE api_usage_ledger
    ADD COLUMN fatigue_state_at_request VARCHAR(20);

Frontend

Validations

Backend

Validations

Test Cases

UX Guidelines

Mara avatar — vizuální stavy

Avatar Marou je klíčový UX prvek — vizuálně komunikuje stav bez nutnosti číst text. Každý stav má vlastní CSS class, která se aplikuje na avatar kontejner.

Zdroj assetů: TODO — FE developer vytvoří / sežene ilustrace Marou pro každý stav. Doporučený formát: SVG nebo PNG (2x density), min. 64×64 px pro sidebar, 128×128 px pro sleep screen.

Animace přechodu: CSS transition opacity 0.3s ease + filter saturate() — jemná, neflashující změna při přechodu mezi stavy. Mara spící avatar má background pulse animaci (subtilní @keyframes opacity 0.7–1.0 v cyklu 3s).

Mara zprávy — i18n message pool

FE vybírá náhodnou variantu z pool při renderu komponenty (ne při příchodu zprávy). Klíče v locales/cs.json a locales/en.json.

CS varianty (3–5 per stav):

{countdown} = dynamický interpolovaný string, např. “2 h 34 min”. {time} = formátovaný čas z sleep_until_ts, např. “14:23”.

Countdown formát

• Více než 1 hodina: “za X h YY min” (příklad: “za 2 h 07 min”)
• Méně než 1 hodina: “za YY min” (příklad: “za 34 min”)
• Méně než 1 minuta: “za chvíli” (příklad: 45 sekund zbývá)
• Tick: refresh každých 60 sekund (stačí minutová granularita), ne setInterval na každou sekundu

Banner notifikace

Bannery zobrazit jen jednou za session (state v Pinia — bannerShown50, bannerShown80). Modal při přechodu do ASLEEP jednorázový — po potvrzení se zobrazí sleep screen.

”Mara spí” screen

Plnohodnotná náhrada chat oblasti (ne error overlay). Zobrazí se když fatigue_level === 'ASLEEP'.

Layout (orientační):

┌─────────────────────────────────────────────────────┐
│                                                     │
│          [Mara spící avatar — velký, 128px]         │
│                                                     │
│         Mara si odpočívá                            │
│         Vrátí se za  2 h 07 min  (countdown)        │
│                                                     │
│  ──────────────────────────────────────────────     │
│                                                     │
│  Mezitím si můžeš prohlédnout svoje projekty →      │
│                                                     │
└─────────────────────────────────────────────────────┘

• Countdown se aktualizuje každou minutu (setInterval 60s)
• Po countdown = 0 FE automaticky odemkne chat (bez refreshe) — volání useFatigueStore.checkWakeUp() nebo watch na sleep_until_ts
• “Prohlédnout projekty” = odkaz na /projects (dashboard)
• Chat input disabled, aria-disabled="true", placeholder “Mara odpočívá…”

Accessibility

• aria-live="polite" na avatar status text — screen reader oznámí změnu stavu (ne při každé aktualizaci, pouze při změně state)
• aria-label na avatar obrázek popisující stav: např. aria-label="Mara — unavená"
• Countdown region: aria-live="off" (ticker nepotřebuje screen reader update každou minutu; pouze při přechodu do ASLEEP)
• Barevné rozlišení stavů NESMÍ být jediným rozlišovacím prvkem — každý stav má i textový popis a avatar výraz
• Chat input při ASLEEP: disabled atribut + aria-disabled="true" + tooltip při hoveru / focus

Pinia store — useFatigueStore

// Orientační rozhraní — FE developer implementuje
interface FatigueStore {
  level: FatigueLevel | null        // aktuální stav
  window5hPct: number               // 0–100+
  windowWeeklyPct: number           // 0–100+
  sleepUntilTs: string | null       // ISO timestamp nebo null
  bannerShown50: boolean
  bannerShown80: boolean
  // actions
  update(envelope: FatigueEnvelope): void
  checkWakeUp(): void               // volat po countdown = 0
}

Store je hydratován po každém Mara turnu z fatigue_envelope v SSE eventu / HTTP response.

Reference

• UC-08001 Anthropic Call Gateway — Gateway infrastruktura, api_usage_ledger, GatewayResponse data class
• specification/mara-fatigue-fup.md — Detailní spec quota mechanismu, state machine, Redis keys, global emergency brake
• adr/ADR-020 — Architektonická rozhodnutí: rolling windows, no carry-over, grace finish, i18n na FE