2026-08-04 15:00:33 +02:00
|
|
|
---
|
|
|
|
|
okf: "0.1"
|
|
|
|
|
type: phase
|
|
|
|
|
visibility: private
|
|
|
|
|
status: active
|
|
|
|
|
updated: 2026-07-02
|
|
|
|
|
links: []
|
|
|
|
|
---
|
|
|
|
|
|
2026-07-02 15:09:40 +02:00
|
|
|
# Modul 5 — Ingest dokumentow -> koperta KB
|
|
|
|
|
|
|
|
|
|
> Adapter obu zrodel (Paperless API + Nextcloud WebDAV) -> koperta KB. Domyka filar #2
|
|
|
|
|
> w warstwie 2 (preprocess+index). Zalezy od: 2 (Paperless), 4 (Nextcloud).
|
|
|
|
|
|
|
|
|
|
## Cel
|
|
|
|
|
Wciagnac dokumenty z Paperless i Nextcloud do spine KB (envelope w kb-postgres@PIHA),
|
|
|
|
|
z OCR-textem + metadanymi, budujac pierwszy cross-source link (correspondent->maile).
|
|
|
|
|
|
|
|
|
|
## Wymogi
|
|
|
|
|
- `jobs/documents-ingest/` — job CLI (wzorzec jak jobs/gmail-bulk-import/), pip install -e.
|
|
|
|
|
- Dwa adaptery:
|
|
|
|
|
- **Paperless API**: pobierz dokumenty (doc-id, correspondent, tags, created, OCR-content).
|
|
|
|
|
`raw_ref` = REFERENCJA (doc-id) — Paperless=zrodlo prawdy. NIE kopiuj bajtow.
|
|
|
|
|
- **Nextcloud WebDAV**: listuj pliki, pobierz. `raw_ref` = KOPIA do archiwum KB
|
|
|
|
|
(snapshot, bo pliki znikaja). Wykrywaj zmiany (etag/mtime) -> nowa koperta (append).
|
|
|
|
|
- Mapping -> koperta (`packages/kb-mail` wzorzec, moze `packages/kb-documents`):
|
|
|
|
|
- `source` = `paperless` | `nextcloud`
|
|
|
|
|
- `id` = stabilny (paperless doc-id | nextcloud fileid+etag)
|
|
|
|
|
- `ts` = data dokumentu (Paperless: created/z tresci; Nextcloud: mtime)
|
|
|
|
|
- `geo` = null (dokumenty zwykle bez geo; opcjonalnie z tresci pozniej)
|
|
|
|
|
- `raw_ref` = referencja (paperless) | sciezka-archiwum (nextcloud)
|
|
|
|
|
- `entities[]` = OCR-text (do embed), correspondent, tags, filename, content_type
|
|
|
|
|
- **Selektywny index** (jak maile): archiwizuj/referuj wszystko, embeduj sensowne
|
|
|
|
|
(OCR-text -> bge-m3 na SOLARIA -> pgvector). Pomijaj smiecie (puste skany? duplikaty?).
|
|
|
|
|
|
|
|
|
|
## Graf encji (warstwa 3 — cienki start, PIERWSZY cross-source)
|
|
|
|
|
- **correspondent** (Paperless: kto wystawil) = encja. Zmapuj do encji z maili
|
|
|
|
|
(ten sam nadawca faktury i maila = ta sama osoba/firma). To DOWOD zasady kb-00 #7
|
|
|
|
|
(cienka warstwa 4 po drugim zrodle udowadnia cross-source linking).
|
|
|
|
|
- Zapisz link w grafie encji (schema z warstwy 3 — jesli nie istnieje, cienki start tutaj).
|
|
|
|
|
|
|
|
|
|
## Domkniecie dlugu z maili (faza-2-zalacznikow)
|
|
|
|
|
- 70k zalacznikow z importu Gmaila (manifest w entities[] kopert mailowych).
|
|
|
|
|
- Faktury/umowy/PDFy -> wyslij do Paperless (jego OCR + correspondent-detection),
|
|
|
|
|
potem wciagnij z powrotem przez adapter Paperless. NIE osobny pipeline OCR.
|
|
|
|
|
- Sizing: batch, partie (modul 3 OCR-worker na SOLARIA miele).
|
|
|
|
|
|
|
|
|
|
## Do zweryfikowania przez CC
|
|
|
|
|
- Paperless API: endpointy (documents, correspondents, tags), auth (token), paginacja.
|
|
|
|
|
- Nextcloud WebDAV: listowanie rekurencyjne, etag, pobieranie, auth.
|
|
|
|
|
- Czy `packages/kb-mail` da sie reuzyc czy potrzeba `packages/kb-documents` (koperta wspolna!).
|
|
|
|
|
- Jak wykrywac zmiany w Nextcloud (polling etag? webhooks?) dla re-ingestu.
|
|
|
|
|
- Deduplikacja: dokument w Paperless I jako zalacznik maila — ten sam? (sha256 match).
|
|
|
|
|
|
|
|
|
|
## Kryteria ukonczenia
|
|
|
|
|
- Dokumenty z Paperless + Nextcloud w tabeli envelope (kb-postgres@PIHA).
|
|
|
|
|
- OCR-text zembedowany (pgvector), correspondent jako encja.
|
|
|
|
|
- Min. jeden cross-source link correspondent<->mail zademonstrowany.
|
|
|
|
|
- Idempotentny (re-run nie duplikuje — wzorzec z gmail-bulk-import ON CONFLICT).
|
|
|
|
|
- Testy jednostkowe (wzorzec jobs/gmail-bulk-import/).
|
|
|
|
|
- Faza-2-zalacznikow: przetestowana na probce (kilka faktur z maili -> Paperless -> ingest).
|
