Podpora21 — System Overview

System Context Diagram

📊 Diagram: design/diagrams/podpora21-system-context.png

Architecture Overview Diagram

📊 Diagram: design/diagrams/podpora21-architecture-overview.png

System Context

Podpora21.cz je dedikovaná aplikace zákaznické podpory v EP21 ekosystému.

Problem: Klientské a studentské požadavky na EP21 služby jsou nestrukturované, bez SLA trackovení a bez formálního helpdesk procesu.

Solution boundary:

• IN SCOPE: Helpdesk tickety (vytváření, lifecycle, konverzace), SLA politiky, klientské záznamy, kategorie podpory, audit log, agent dashboard
• OUT OF SCOPE: Fakturace a smlouvy (SoT = Firma21), projektové portfolio (SoT = Projekty21), správa kurzů (SoT = Vzdělávání21), ERP operace

Podpora21 je konzumentem dat z Firma21 (CustomerAccount, SupportCoverage) a vystaví support historii jako event log do TEK/AMQP pro ostatní EP21 systémy.

Actors & External Systems

Architecture Layers

Aplikace je postavena na Nette MVC architektuře s těmito vrstvami:

1. PRESENTATION (app/Presenters/ + templates/)

• Presentery dědí z BasePresenter / BasePresenterSecure
• Latte templates s Bootstrap 4 + Material Icons
• Formuláře přes Nette Forms

2. APPLICATION (app/Service/)

• Services orchestrují business logiku přes více modelů
• DI inject přes neon konfiguraci

3. DOMAIN (app/Model/)

• Models dědí z BaseModel, přistupují do DB přes Nette Database Explorer
• Pattern: $this->db->table(TABLE_NAME)
• Bez ORM, bez typed return hints na getDetail() override

4. INFRASTRUCTURE

• PostgreSQL 16, schema: podpora21 (+ core/public pro sdílené entity)
• Phinx migrace ve třech konfiguracích: core, podpora21, data
• AMQP (RabbitMQ) pro TEK bridge events
• Docker-first: web (PHP/Apache), postgres, rabbitmq, keycloak

5. CLI / SCRIPTS

• Python scripts pro TEK task engine, error registry, metadata
• PHP CLI přes Nette console

Data Flow

Primární tok:

1. Klient nebo agent vytvoří ticket (web form / email)

2. TicketPresenter -> TicketModel.create() -> support_ticket INSERT

3. SLA policy přiřazena automaticky podle priority

4. Agent vidí ticket v dashboardu, přidá komentář -> support_ticket_comment

5. Každá změna statusu / přiřazení -> support_ticket_history (audit log)

6. TEK bridge publikuje events do AMQP při klíčových změnách (volitelné)

Integrační tok (Firma21):

• podpora21 čte client/account data z Firma21 API nebo sdílené DB views
• SoT pro support coverage zůstává v Firma21; podpora21 pouze konzumuje

Key Data Structure

app/
  Presenters/
    TicketPresenter.php        # dashboard, list, detail, new, reply, changeStatus
    BasePresenter.php
    BasePresenterSecure.php
  Model/
    TicketModel.php            # support_ticket, _comment, _history CRUD
    BaseModel.php
  Service/
  config/
    common.neon, services.neon, rabbit.neon

phinx/
  phinx-podpora21.php
  db/podpora21_migrations/
    20260408100000_helpdesk_initial.php   # 6 helpdesk tabulek + seed

design/
  .dak/kit.json
  docs/  adr/  output/

meta/tasks/  meta/errors/  meta/url-catalog/
scripts/tasks.py  scripts/error_registry_*.py

Deployment Model

Local dev: Docker Compose (web + postgres + rabbitmq)

APP_PORT=8080, CONTROL_PORT=9021, POSTGRES_PORT=15432

DB: podpora21 / user: podpora21 / schema: podpora21

Produkce: Docker na EP21 infra (stejný image, ENV_INST=prod)

Remote: ssh://git@gitssh.ep21.cz:2222/app/core/app-podpora21.git

Klíčové ENV: POSTGRES_DB, DB_SCHEMA, NETTE_DEBUG, ENV_INST, AMQP_URL

Security Model

• Autentizace: Nette Security (DbAuthenticator) + volitelný Keycloak SSO

• Autorizace: RBAC přes DbAuthorizator — role: admin, agent, client

• Presenter akce chráněny přes BasePresenterSecure.actionRedirectIfNotLogged()

• SQL injection: Nette Database Explorer parametrizované dotazy

• XSS: Latte auto-escape všech výstupů

• Secrets: pouze v docker/.env, nikdy v kódu

• WEBHOOK_SECRET_EXTERNAL_ISSUE: hmac ověření příchozích webhooků

• Audit log: support_ticket_history pro všechny změny

Observability

• PHP výjimky: Tracy -> log/exception.log -> error registry (meta/errors/)

• Error remediation pipeline: make daily -> crawl -> sync -> prompt

• TEK bridge: events do AMQP, konzumovány TEK master controllerem

• URL katalog: meta/url-catalog/ (persistent, E2E crawl)

• Playwright E2E: make e2e / make e2e-auth

• Docker logs: make logs / make logs-web / make logs-db

Roadmap & Known Gaps

• DI registrace TicketModel + TicketPresenter v services.neon [blocker pro start]

• Router: přidat Ticket: routes do app/Router/RouterFactory.php

• RBAC: přidat ticket/* resources do AuthorizatorFactory

• Firma21 integrace: číst CustomerAccount a SupportCoverage

• Klientský portál: veřejná stránka pro vlastní tickety (token-based)

• Email notifikace: odesílání při změně statusu

• Attachment upload: podpora příloh

• Reporting: SLA compliance, průměrné doby řešení

• ADR migrace: existující projekty21 ADRy → DAK JSON formát

ADR Index