00de8107ea
public (wzorce/schematy, bez IP/portow/sciezek hostow): observer, capability-model, event-system, standards, agent-operating-procedures, service-model, action-approval-model. private: recon-multiagent, fleet-inventory, fleet-inventory-verify, kb-mail-pillar, kb-documents-pillar, topology, agent-system. deprecated (martwe stuby z 2026-04-15) — visibility private wg rozstrzygniecia 6: access-model, core-stack, legacy-services-list, networking. git mv + frontmatter, tresc nietknieta. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
121 lines
5.5 KiB
Markdown
121 lines
5.5 KiB
Markdown
---
|
|
okf: "0.1"
|
|
type: subsystem
|
|
visibility: private
|
|
status: active
|
|
updated: 2026-07-01
|
|
links: []
|
|
---
|
|
|
|
# KB filar #2 — Dokumenty (Nextcloud + Paperless) — design
|
|
|
|
> Dokument-master filaru dokumentow. Stoi pod `kb-00-overview.md`.
|
|
> Cel: kazda sesja / Claude Code startuje z pelnym kontekstem decyzji.
|
|
> Status: ARCHITEKTURA ZAMKNIETA (2026-07-01), implementacja modulowa czeka.
|
|
> Moduly implementacyjne: `docs/kb/modules/0X-*.md` — puszczane CC jeden po drugim.
|
|
|
|
---
|
|
|
|
## Kontekst — miejsce w architekturze KB
|
|
|
|
Filar #2 z czterech (maile > **dokumenty** > zdjecia > transakcje). Reuzywa ~80%
|
|
wzorca maili (text RAG + archiwum + embeddingi na SOLARIA), dokłada OCR i wlasna
|
|
migracje Drive -> self-host. Wpina sie w te sama koperte (`id/source/ts/geo/raw_ref/
|
|
entities[]`) i ten sam spine (Postgres+pgvector na PIHA).
|
|
|
|
Dwa zrodla dokumentow (dwa adaptery ingest):
|
|
- **Nextcloud** — zamiennik Drive, dowolne pliki + sync (WebDAV)
|
|
- **Paperless-ngx** — skany/faktury/umowy z OCR (Paperless API)
|
|
|
|
---
|
|
|
|
## Decyzje ZAMKNIETE
|
|
|
|
### Tozsamosc / SSO = Forgejo-OIDC
|
|
Forgejo (biega na PIHA, always-on, zweryfikowane docker ps) jest IdP. Nextcloud/
|
|
Paperless/Immich wpinaja sie przez natywny OIDC — wzorzec jak Vikunja (jedyny
|
|
dzisiejszy konsument). Authentik/forward-auth = otwarta przyszla opcja dla infra
|
|
(panele/monitoring bez OIDC), POZA zakresem KB. Spec: `modules/01-sso-forgejo-oidc.md`.
|
|
|
|
### Ingress = LAN/Tailscale only, ZERO public
|
|
Dokumenty to dane wrazliwe (faktury/umowy/prywatne pliki) — zasada kb-00 #4 local-first.
|
|
Wpinaja sie w **npm na PIHA** (LAN ingress :80/:443), NIE w npm na VPS (public).
|
|
Dostep spoza domu = przez Tailscale mesh. Zero certow public dla tych serwisow.
|
|
|
|
### Archiwum = HYBRYDA (kopia vs referencja per zrodlo)
|
|
- **Nextcloud -> KOPIA** do archiwum KB (pliki w Nextcloud znikaja/zmieniaja sie;
|
|
KB robi snapshot przy ingescie, wersjonowanie przez append koperty)
|
|
- **Paperless -> REFERENCJA** (jego storage = zrodlo prawdy; KB trzyma raw_ref + OCR-text)
|
|
- **WARUNEK BRZEGOWY**: backup Paperless storage OBOWIAZKOWY (bo referencja = KB zalezy
|
|
od zywotnosci Paperlessa; bez backupu = pojedynczy punkt awarii)
|
|
|
|
### Host = SPLIT serwis/OCR (rozwiazuje kolizje moc-vs-always-on)
|
|
Zadny pojedynczy node nie jest jednoczesnie mocny I always-on:
|
|
- VPS: RAM wyczerpany (121Mi wolne) — OUT
|
|
- PIHA: always-on ale ciasno (3.1Gi available, swap juz 2G uzyty)
|
|
- SOLARIA: mocarz (62Gi RAM, GPU, 315G) ale dostepnosc sesyjna (nie 24/7)
|
|
|
|
Rozwiazanie — rozdziel warstwy wg wymogu dostepnosci:
|
|
- **Paperless-serwis** (UI+API+Postgres+Redis) na **PIHA** — always-on, lekki w spoczynku,
|
|
dostepny 24/7 dla zapytan KB. Miesci sie w 3.1Gi available (ciasno).
|
|
- **OCR-worker** na **SOLARIA** — CPU/GPU-glodny OCR batch (70k zalacznikow), podpiety
|
|
do kolejki Redis@PIHA. 62Gi RAM stoi odlogiem.
|
|
- **FALLBACK**: SOLARIA spi -> OCR-worker na PIHA domiela wolno, ALBO zadania czekaja
|
|
w kolejce Redis az SOLARIA wstanie (dokumenty nie sa pilne w sekundach).
|
|
|
|
Uzasadnienie splitu: OCR jest batch/async (fallback trywialny — kolejka czeka).
|
|
Stateful-serwis (baza) NIE fallbackuje latwo (replikacja pg = kruche) -> stoi w jednym
|
|
miejscu (PIHA). Wzorzec: "serwis always-on + compute-worker on-demand z fallback".
|
|
|
|
### PREREKWIZYT: odchudzic PIHA
|
|
PIHA na styku RAM (swap 2G uzyty). Przed deployem Paperlessa — audyt 33 shadow-kontenerow
|
|
(inwentaryzacja 2026-06-30): kandydaci do usuniecia/przeniesienia (elasticsearch 1Gi?
|
|
diskover? duplikaty exporterow?). Laczy sie z backlogiem grupy C. Spec: `modules/00-piha-slim.md`.
|
|
|
|
---
|
|
|
|
## Mapa modulow (kolejnosc egzekucji)
|
|
|
|
| # | Modul | Plik | Zalezy od |
|
|
|---|---|---|---|
|
|
| 0 | Odchudzic PIHA (prerekwizyt) | `modules/00-piha-slim.md` | — |
|
|
| 1 | SSO Forgejo-OIDC (decyzja+wzorzec) | `modules/01-sso-forgejo-oidc.md` | — |
|
|
| 2 | Paperless serwis (PIHA) | `modules/02-paperless-service.md` | 0,1 |
|
|
| 3 | Paperless OCR-worker (SOLARIA+fallback) | `modules/03-paperless-ocr-worker.md` | 2 |
|
|
| 4 | Nextcloud (WebDAV+OIDC) | `modules/04-nextcloud.md` | 0,1 |
|
|
| 5 | Ingest -> koperta | `modules/05-documents-ingest.md` | 2,4 |
|
|
|
|
Kazdy modul = samodzielny spec do puszczenia CC ("czytaj i implementuj krok po kroku").
|
|
|
|
---
|
|
|
|
## Ingest -> koperta (warstwa 2, wspolna dla obu zrodel)
|
|
|
|
Kazdy dokument -> koperta KB:
|
|
- `source` = `nextcloud` | `paperless`
|
|
- `id` = stabilny (Paperless doc-id | Nextcloud file-id+etag)
|
|
- `ts` = data dokumentu (Paperless wykrywa z tresci! lepsze niz mtime)
|
|
- `raw_ref` = Nextcloud: sciezka do KOPII w archiwum KB | Paperless: referencja doc-id
|
|
- `entities[]` = OCR-text + correspondent + tags (z Paperless API)
|
|
|
|
## Graf encji (warstwa 3, cienki start)
|
|
- **correspondent** (kto wystawil dokument) = encja -> link do maili (ten sam nadawca
|
|
w mailu i fakturze = ta sama encja). PIERWSZY cross-source link (dowod zasady kb-00 #7).
|
|
- data dokumentu = klucz czasowy do zlaczen spatio-temporalnych.
|
|
|
|
## Domkniecie dlugu z maili
|
|
Faza-2-zalacznikow (70k zalacznikow / 15.4GB z importu Gmaila): faktury/umowy/PDFy
|
|
routuja do Paperless (jego OCR + correspondent-detection), NIE osobny pipeline.
|
|
Realizowane po modulach 2-3 (Paperless dziala) jako job w module 5.
|
|
|
|
---
|
|
|
|
## OTWARTE kwestie
|
|
|
|
- **Nextcloud host** — PIHA (ciasno) czy SOLARIA (drive nie musi byc 24/7 tak twardo
|
|
jak indeks KB)? Do rozstrzygniecia przy module 4. Wstepnie: rozwazyc SOLARIA, bo
|
|
Nextcloud ciezszy (PHP+baza+storage sync) niz Paperless-serwis.
|
|
- **Sizing OCR-batch** — ile trwa OCR 70k zalacznikow na SOLARIA, czy dzielic na partie.
|
|
- **Backup Paperless** — gdzie (PIHA NVMe? SOLARIA? offsite?), jaka retencja. Warunek
|
|
brzegowy hybrydy — do zaprojektowania w module 2.
|