Info: weboldal felderítése (web crawl → Info elemek)

Ez a dokumentum az Info modul webes betöltését írja le: egy vagy több URL-ről a rendszer feltérképezi a weboldalt, majd a talált oldalakból Info elemeket hoz létre (oldalanként 1 rekord), és elindítja az indexelést.

---

Mit csinál a web crawl?

• Bemenet: 1 vagy több seed URL (csak http/https).
• Felderítés: max depth mélységig, max max_pages oldal.
• Eredmény: minden letöltött (tartalmat adó) oldalból külön Info item készül.
• LLM feldolgozás: a rekord mentése előtt lefut (cím/leírás/markdown), így az Info elemek nem “nyers” HTML tartalommal kerülnek elmentésre.
• Biztonság: URL validáció (localhost / private IP tiltás), allowlist/denylist domain és regex opciók.
• Fail-safe: max futási idő (timeout), és biztos megszakítás (cancel).

---

Endpointok

1) Web crawl indítása

• path: POST /api/admin/info/from-url/
• auth: JWT
• required role: SYSTEM_ADMIN, TENANT_ADMIN, EDITOR

Request body (példa):

{
  "url": "https://example.com",
  "depth": 2,
  "max_pages": 50,
  "scope": "public"
}

Mezők:

• url: string – kötelező (ha urls nincs megadva). Tipp: ide be lehet paste-elni több URL-t is (újsor/szóköz/vessző alapján szétszedjük).
• urls: string[] – opcionális seed lista (ha több belépő URL kell).
• depth: number – 1..10.
• max_pages: number – 1..2000.
• scope: "internal" vagy "public" – az így létrejövő Info elemek scope-ja.

Response:

{
  "job_id": "uuid",
  "message": "Web crawl elindítva..."
}

---

2) Job státusz és események lekérése (poll)

• path: GET /api/admin/info/from-url/{job_id}/
• auth: JWT
• required role: SYSTEM_ADMIN, TENANT_ADMIN, EDITOR, VIEWER

Query paraméterek:

• events_limit: default 200, max 1000
• events_offset: default 0
• include_page_text: default false – csak debug esetén kapcsold be, mert nagy lehet.

Poll válasz – aktuális HTTP (wire)

A GET /api/admin/info/from-url/{job_id}/ válasz gyökere ma így néz ki:

• job: objektum – legalább id (UUID string), status, stats (objektum, pl. crawler visited / skipped / failed, kész jobnál result_info_item_ids), további meta (URL, időbélyegek, result_markdown stb.).
• events: tömb – minden elem: id, ts (ISO idő), event_type, payload (a crawler / ingest esemény nyers mezői).

{
  "job": {
    "id": "uuid",
    "status": "RUNNING",
    "stats": {
      "visited": 12,
      "skipped": 0,
      "failed": 0
    }
  },
  "events": [
    {
      "id": "event-row-uuid",
      "ts": "2026-04-24T20:47:38+00:00",
      "event_type": "status",
      "payload": {
        "event_type": "status",
        "status": "RUNNING"
      }
    }
  ]
}

A payload tartalma eseménytípusonként változik (page → page.url, page.title, page.status_code …; done → stats; error → error / url stb.).

Számlálók a UI összegzéshez: a normalizált stats.pages_crawled értelmezése tipikusan job.stats.visited; a stats.created_info_items pedig a job.stats.result_info_item_ids tömb hossza (ha a job már létrehozta az Info elemeket).

Web crawl job események – UI szerződés (normalizált)

Az admin UI / integráció számára célszerű, ha a fenti events[] sorokból egységes naplóobjektumot építetek (vagy ha a backend később erre egységesít). Az alábbi szerkezet a célforma; megfeleltetés példa: timestamp ← ts, type ← event_type, a többi mező a payload + job.status kombinációjából tölthető.

Kötelező mezők minden event objektumban:

Mező	Típus	Leírás
timestamp	string	ISO-8601
type	string	status | heartbeat | page | error | done | cancelled
status	string	RUNNING | DONE | FAILED | CANCELLED (a job pillanatnyi / eseményhez kapcsolt állapota)
message	string	Szabad szöveg (lehet üres)
page	object | null	Csak type=page esetén kötelező tartalom; egyébként null

page objektum (type=page esetén):

Mező	Kötelező	Típus	Megjegyzés
url	igen	string	Letöltött oldal URL-je
title	nem	string	Oldalcím
http_status	nem	number	HTTP státuszkód
content_type	nem	string	Pl. text/html
bytes	nem	number	Válasz méret bájtban

A nyers API payload.page objektumában a crawler status_code, text (a poll alapból kiszedi a text-et), depth, fetch_mode mezőket is küldhet; a fenti http_status / bytes / content_type nevek a megjelenítéshez egységesített mezők (értéküket a kliens tölti ki, ha elérhető).

Példa – type: status

{
  "timestamp": "2026-04-24T20:47:38Z",
  "type": "status",
  "status": "RUNNING",
  "message": "Crawler elindult",
  "page": null
}

Példa – type: page

{
  "timestamp": "2026-04-24T20:47:41Z",
  "type": "page",
  "status": "RUNNING",
  "message": "Oldal feldolgozva",
  "page": {
    "url": "https://example.com/docs/intro",
    "title": "Intro",
    "http_status": 200,
    "content_type": "text/html",
    "bytes": 48213
  }
}

Példa – type: done

{
  "timestamp": "2026-04-24T20:48:12Z",
  "type": "done",
  "status": "DONE",
  "message": "Crawl sikeresen befejezve",
  "page": null
}

Megjegyzés: a UI alapból nem kapja meg a teljes letöltött oldal szövegét (a page.text ki van szedve), hogy ne fagyjon le nagy crawl esetén.

---

3) Megszakítás (cancel)

• path: POST /api/admin/web-crawl/{job_id}/cancel
• auth: JWT
• required role: SYSTEM_ADMIN, TENANT_ADMIN, EDITOR

Response:

{
  "cancelled": true,
  "task_cancelled": true,
  "message": "Cancel requested."
}

---

Konfiguráció (env / settings)

Az alábbi változók a web crawl viselkedését szabályozzák:

• WEB_CRAWL_MAX_CONCURRENT_PER_TENANT: 0 = nincs limit; >0 esetén tenantonként ennyi párhuzamos crawl futhat.
• WEB_CRAWL_MAX_RUNTIME_SECONDS: max futási idő (pl. 1200 = 20 perc).
• WEB_CRAWL_ALLOWED_DOMAINS: vesszővel elválasztott allowlist (üres = nincs allowlist).
• WEB_CRAWL_DENIED_DOMAINS: vesszővel elválasztott denylist.
• WEB_CRAWL_ALLOWED_URL_REGEX: regex (üres = nincs).
• WEB_CRAWL_DENIED_URL_REGEX: regex (üres = nincs).

---

Tipikus flow (admin)

1. Indítás: POST /api/admin/info/from-url/ → job_id.
2. Poll: GET /api/admin/info/from-url/{job_id}/ amíg status terminal (DONE/FAILED/CANCELLED).
3. A létrejött Info elemek a listában megjelennek; az indexelés automatikusan indul (PENDING → PROCESSING → INDEXED).

---

Kapcsolódó dokumentumok

• Info admin + /info chat: 47-info-chat-and-admin.md
• Dokumentációs konvenciók: 39-documentation-conventions.md