Document Service

Microsluzba pro spravu dokumentu — upload, ukladani, verzovani stavu a stahovani souboru. Postavena na Cloudflare Workers s D1 databazi a R2 ulovistem.

Obsah

• Architektura
• Zivotni cyklus dokumentu
• Upload souboru
• Docasne dokumenty
• CRON
• RPC akce
• Databazove schema
• Error Codes

Architektura

Sluzba se sklada z:

• Akce (Actions) — API endpointy pro upload, spravu stavu a stahovani dokumentu
• R2 Storage — Cloudflare R2 bucket pro fyzicke ukladani souboru
• D1 Database — Metadata dokumentu (entita, typ, status, filename)
• CRON — Automaticky cleanup docasnych dokumentu

Zivotni cyklus dokumentu

Dokument prochazi nasledujicimi stavy:

Upload s entityId ──→ UPLOADED ──→ VERIFIED
                                ──→ REJECTED
                                ──→ ARCHIVED

Upload bez entityId → TEMPORARY ──→ acknowledge ──→ UPLOADED ──→ ...
                          │
                          └──→ cleanup (CRON, 24h)

DocumentStatus

| Status | Popis | |--------|-------| | TEMPORARY | Nahrano bez prirazeni k entite — ceka na acknowledge-document | | UPLOADED | Prirazeno k entite, ceka na verifikaci | | VERIFIED | Overeno | | REJECTED | Zamitnuto | | ARCHIVED | Archivovano |

DocumentType

| Typ | Popis | |-----|-------| | kyc | KYC dokumenty | | contract | Smlouvy | | bank_account | Overeni bankovniho uctu | | invoice | Faktury | | avatar | Profilovy obrazek | | company_logo | Logo organizace |

EntityType

Dokumenty lze prirazit k entitam: client, order, transaction.

Upload souboru

Akce upload-document prijima soubor ve dvou formatech:

• Blob — { blob: Blob, name: string } (z prohlizece)
• Buffer — { bytes: Uint8Array, type: string, name: string, size: number } (worker-to-worker)

Upload input (soubor + metadata)
  │
  ▼
  Validace velikosti (MAX_UPLOAD_MB: 10/20 MB)
  │
  ▼
  Ulozeni do R2 (klic = documentId)
  │
  ▼
  Zapis metadat do D1 (status: UPLOADED)
  │
  ▼
  Return { documentId, storageUrl }

Limit velikosti

| Prostredi | Limit | |-----------|-------| | Local | 20 MB | | Dev / Test / Staging / Production | 10 MB |

Docasne dokumenty

Pro scenare kde entita jeste neexistuje (vicerokove formulare):

1. upload-temporary-document — upload bez entityId → status TEMPORARY
2. acknowledge-document — prirazeni entityId + zmena na UPLOADED
3. Neprirazene docasne dokumenty se automaticky mazu po 24 hodinach

upload-temporary-document (bez entityId)
  │
  ▼
  Dokument v DB (status: TEMPORARY, entityId: null)
  │
  ├─ acknowledge-document (entityId) → status: UPLOADED
  │
  └─ cleanup (24h) → smazani z DB + R2

CRON

| Schedule | Akce | Popis | |----------|------|-------| | 0 2 * * * | cleanup-temporary-documents | Maze docasne dokumenty starsi nez 24 hodin |

Cleanup je best-effort — selhani mazani z R2 neblokuje odstraneni z DB.

RPC akce

Document service je RPC worker — nema vlastni verejne HTTP endpointy. Vsechny akce jsou dostupne pouze pres Cloudflare Worker binding.

Upload a stahovani

| Akce | Popis | |------|-------| | upload-document | Upload souboru s prirazenim k entite | | upload-temporary-document | Upload bez entityId (status: TEMPORARY) | | get-file | Stahnout soubor z R2 (vraci ArrayBuffer, content-type, filename) |

Dotazy

| Akce | Popis | |------|-------| | get-document | Ziskat dokument podle ID | | get-documents-list | Seznam dokumentu s filtry (entityType, entityId, type) |

Sprava stavu

| Akce | Popis | |------|-------| | change-document-status | Genericka zmena statusu | | verify-document | Overit dokument (→ VERIFIED) | | reject-document | Zamitnout dokument (→ REJECTED) | | archive-document | Archivovat dokument (→ ARCHIVED) | | acknowledge-document | Prirazit entityId docasnemu dokumentu (→ UPLOADED) |

Metadata a udrzba

| Akce | Popis | |------|-------| | update-document-metadata | Aktualizace metadata dokumentu | | delete-document | Smazani z DB + R2 | | cleanup-temporary-documents | Mazani starych docasnych dokumentu |

Databazove schema

document

Metadata dokumentu — jeden zaznam na soubor.

Klicove sloupce: entityType, entityId, type (DocumentType), status (DocumentStatus), storageUrl (unikatni), filename, metadata (JSON).

Metadata — flexibilni JSON objekt typu Record<string, string | number | boolean | string[] | number[] | boolean[]>.

Error Codes

| Code | Status | Description | |------|--------|-------------| | — | 413 | File exceeds MAX_UPLOAD_MB limit | | — | 404 | Document not found | | — | 404 | File not found in R2 | | — | 500 | Failed to save document to database | | — | 500 | Failed to buffer file | | — | 500 | Failed to change document status |