clawd/memory/kb/projects/roa2web-telegram-import/README.md

Proiect: Import Bonuri Fiscale via Telegram/WhatsApp → ROA

Data: 2026-02-03
Status: Analiză completă
Tags: @work @project

---

TL;DR

Sistem pentru importul bonurilor fiscale de achiziție din Telegram/WhatsApp în contabilitatea ROA. OCR prin Doctr (cost zero, local). Integrare cu Oracle prin proceduri existente (PACK_CONTAFIN).

---

1. Obiective

• Input: Bonuri fiscale trimise pe Telegram/WhatsApp (PDF/imagine)
• Procesare: OCR local (Doctr) - cost zero
• Output: Note contabile în Oracle (ACT, BAL, etc.)
• Aprobare: Opțional - contabil verifică înainte de salvare finală

---

2. Arhitectură

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  Telegram   │     │             │     │             │     │             │
│  WhatsApp   │────▶│  Clawdbot   │────▶│  roa2web    │────▶│  ROA Oracle │
└─────────────┘     │  (Bridge)   │     │  (OCR+API)  │     │  (PACK_     │
                    └─────────────┘     └─────────────┘     │  CONTAFIN)  │
                           │                   │            └─────────────┘
                           ▼                   ▼                   │
                    • Primește fișier    • Doctr OCR         • ACT_TEMP
                    • Forward la API     • PDF text layer    • ACT, BAL
                    • Răspuns user       • JSON extrase      • IREG_PART

---

3. Componente Existente

3.1 roa2web (LXC 171 - claude-agent)

Component	Status	Locație
OCR Engine	✅ Complet	/workspace/roa2web/backend/modules/data_entry/services/ocr_engine.py
Doctr	✅ Instalat	PyTorch backend, db_resnet50 + crnn_vgg16_bn
PaddleOCR	✅ Instalat	Backup engine
API OCR	✅ Funcțional	POST /api/data-entry/ocr/extract
Job Queue	✅ Complet	Async processing cu worker pool
Bot Telegram	⚠️ Parțial	Dashboard/sold, NU handler fișiere

3.2 Schema Date OCR (ExtractionData)

ExtractionData:
    partner_name: str       # nume furnizor
    cui: str               # CUI furnizor  
    receipt_date: date     # data bon
    receipt_number: str    # număr bon
    receipt_series: str    # serie bon
    amount: Decimal        # total
    tva_entries: List[TvaEntry]  # TVA pe cote (A=19%, B=9%, etc.)
    tva_total: Decimal     # total TVA
    payment_methods: List  # CARD/NUMERAR
    address: str           # adresă furnizor
    confidence_*: float    # scoruri încredere

3.3 Oracle (MARIUSM_AUTO)

Tabele principale:

Tabel	Scop
ACT	Note contabile
ACT_TEMP	Staging pentru note
RUL	Rulaje gestiuni
STOC	Solduri stoc
BAL	Balanță verificare
IREG_PARTENERI	Evidență parteneri
BALANTA_PARTENERI	Balanță parteneri
ATAS_ATASAMENTE	Fișiere atașate (BLOB)
ATAS_REFERINTE	Legături atașamente
NOM_FDOC	Nomenclator tipuri documente

Package-uri relevante:

Package	Scop
PACK_CONTAFIN	Salvare note contabile (principal)
PACK_FACTURARE	Exemple de salvare (pentru vânzări)
PACK_PARTENERI	Gestiune parteneri

---

4. Formula Contabilă - Bon Fiscal Achiziție

4.1 Bon simplu (plătit cash)

Cheltuială = Furnizor:    6xx  = 401    (valoare fără TVA)
TVA deductibil = Furn:    4426 = 401    (TVA)
Plată cash:               401  = 5311   (total cu TVA)

Exemplu bon benzină 119 RON (100 + 19 TVA):

-- Linia 1: Cheltuială combustibil
SCD='6022', SCC='401', SUMA=100.00

-- Linia 2: TVA deductibil
SCD='4426', SCC='401', SUMA=19.00, PROC_TVA=1.19

-- Linia 3: Plată din casă
SCD='401', SCC='5311', SUMA=119.00

4.2 Bon cu TVA la încasare

Cheltuială = Furnizor:    6xx  = 401
TVA neexigibil = Furn:    4428 = 401
Plată cash:               401  = 5311
Exigibilizare TVA:        4426 = 4428

4.3 Conturi cheltuieli uzuale

Tip	Cont	Descriere
Combustibil	6022	Combustibili
Materiale	6021	Materiale auxiliare
Rechizite	6021	Materiale auxiliare
Piese	6024	Piese schimb
Întreținere	611	Cheltuieli întreținere
Transport	624	Cheltuieli transport

---

5. Flux Oracle - Salvare Note Contabile

5.1 Proceduri PACK_CONTAFIN

-- 1. INIȚIALIZARE SESIUNE
PACK_CONTAFIN.INITIALIZEAZA_SCRIERE_ACT_RUL(
    TNIDUTIL           NUMBER,      -- ID utilizator
    TDDATAORA          DATE,        -- Data și ora
    TNAN               NUMBER,      -- An
    TNLUNA             NUMBER,      -- Luna
    TNSUPRASCRIERECOD  NUMBER,      -- 0/1
    TNSUPRASCRIEREANLUNA NUMBER,    -- 0/1
    TNSCRIESTERGE      NUMBER,      -- 0=scrie, 2=șterge
    TNIDSUCURSALA      NUMBER       -- ID sucursală
);

-- 2. INSERT ÎN ACT_TEMP (pentru fiecare linie)
INSERT INTO ACT_TEMP (
    LUNA, AN, COD,
    DATAIREG, DATAACT, DATASCAD,
    NRACT, SERIE_ACT,
    EXPLICATIA,
    SCD, ASCD,           -- cont debit, analitic
    SCC, ASCC,           -- cont credit, analitic
    SUMA,
    PROC_TVA,
    ID_FDOC,             -- tip document
    ID_PARTD, ID_PARTC,  -- parteneri
    ID_FACT,
    ID_VALUTA,
    ID_SUCURSALA
) VALUES (...);

-- 3. FINALIZARE (transferă în ACT, actualizează BAL, etc.)
PACK_CONTAFIN.FINALIZEAZA_SCRIERE_ACT_RUL(
    TNIDUTIL           NUMBER,      -- ID utilizator
    TNCOD              NUMBER,      -- Cod document
    TNSCRIESTERGE      NUMBER,      -- 0=scrie
    TNMODIFICARENOTA   NUMBER,      -- 0/1
    TNSCRIECUMPVANZ    NUMBER,      -- 0/1
    TCMESAJREFACERENOTA OUT VARCHAR2  -- Mesaj rezultat
);

5.2 Ce face FINALIZEAZA intern

-- La linia 8059 în PACK_CONTAFIN:
pack_contafin.SCRIE_IN_ACT(user);       -- ACT_TEMP → ACT + BAL
pack_contafin.SCRIE_IN_RUL(user);       -- RUL_TEMP → RUL (dacă există)
pack_contafin.SCRIE_IN_RUL_OBINV(user); -- pentru obiecte inventar

---

6. Structura ACT_TEMP

ACT_TEMP (
    LUNA NUMBER,
    AN NUMBER,
    COD NUMBER,
    DATAIREG DATE,
    NRACT NUMBER,
    DATAACT DATE,
    EXPLICATIA VARCHAR2(100),
    SCD VARCHAR2(10),        -- Cont DEBIT
    ASCD VARCHAR2(20),       -- Analitic debit
    SCC VARCHAR2(10),        -- Cont CREDIT
    ASCC VARCHAR2(20),       -- Analitic credit
    SUMA NUMBER,
    PROC_TVA NUMBER,         -- Procent TVA (1.19, 1.09, etc.)
    ID_FDOC NUMBER,          -- Tip document (din NOM_FDOC)
    ID_PARTD NUMBER,         -- Partner debit
    ID_PARTC NUMBER,         -- Partner credit
    ID_FACT NUMBER,          -- ID factură (opțional)
    ID_VALUTA NUMBER,
    ID_SUCURSALA NUMBER,
    SERIE_ACT VARCHAR2(10),
    TVA_INCASARE NUMBER,     -- 0/1 pentru TVA la încasare
    ...
)

---

7. Optimizări Propuse

7.1 PDF Text Layer Extraction

Adobe Scan creează PDF-uri cu text layer. Verificăm înainte de OCR:

import pdfplumber

def extract_text_or_ocr(pdf_path):
    with pdfplumber.open(pdf_path) as pdf:
        text = ""
        for page in pdf.pages:
            page_text = page.extract_text()
            if page_text:
                text += page_text
        
        if text.strip():
            # PDF are text layer - folosește-l direct
            return {"source": "pdf_layer", "text": text}
        else:
            # Nu are text - fallback la Doctr OCR
            return doctr_ocr(pdf_path)

Beneficii:

• Instant vs. 2-5 sec OCR
• 100% acuratețe vs. ~95% OCR
• Zero procesare GPU

7.2 Mapare CUI → Cont

Tabel pentru auto-detectare tip cheltuială:

CUI_CONT_MAP = {
    # Benzinării
    "RO1234567": "6022",  # OMV
    "RO2345678": "6022",  # Petrom
    "RO3456789": "6022",  # Mol
    
    # Magazine bricolaj
    "RO10562600": "6021", # Dedeman
    
    # Default
    "DEFAULT": "6028"     # Alte cheltuieli
}

---

8. Status Implementare (2026-02-03)

Component	Status	Note
OCR (Doctr/PaddleOCR)	✅ Testat	34 sec per PDF
Script OCR standalone	✅ Funcțional	/workspace/roa2web-telegram-test/
Python: INSERT ACT_TEMP	✅ Testat	3 linii: cheltuială + TVA + plată
Mapare CUI → cont	✅ Bază	6022=combustibil, 6021=materiale
Găsire partener	✅ Funcțional	Caută în NOM_PARTENERI
Conexiune Oracle	✅ Testat	Server 10.0.20.121
Handler WhatsApp	🔄 În pregătire	Clawdbot poate primi fișiere
CALL PACK_CONTAFIN	⏳ TODO	Finalizare cu procedurile Oracle
UI aprobare	⏳ TODO	Opțional

Scripturi create:

• /workspace/roa2web-telegram-test/process_and_save.py - OCR → Oracle
• /workspace/roa2web-telegram-test/save_to_oracle.py - test salvare Oracle

Test efectuat:

PDF "benzina 07 aug. 2024.pdf" → OCR → Oracle ACT_TEMP
  CUI: RO11201891
  Data: 2024-08-01
  Total: 263.28 RON
  TVA: 42.04 (19%)
  Note: 6022=401, 4426=401, 401=5311
  Status: DRY RUN OK

---

9. Plan Implementare

Faza 1: Handler Telegram (3-4h)

• MessageHandler pentru imagini/PDF în bot
• Forward la /api/data-entry/ocr/extract
• Răspuns cu datele extrase (preview)

Faza 2: PDF Optimization (1-2h)

• Verificare text layer în PDF
• Extracție directă dacă există
• Fallback la Doctr

Faza 3: Integrare Oracle (5-7h)

• Conexiune Oracle din roa2web
• Găsire/creare partener după CUI
• INSERT în ACT_TEMP
• Apel PACK_CONTAFIN proceduri
• Salvare atașament (ATAS_ATASAMENTE)

Faza 4: WhatsApp Bridge (4-6h)

• Clawdbot handler pentru fișiere
• Forward la roa2web API
• Răspuns pe canal

Faza 5: Aprobare & Polish (3-5h)

• Workflow aprobare (opțional)
• Mapare automată CUI → cont
• Logging și error handling

---

10. Credențiale Test

Oracle Test Server:

Host: 10.0.20.121
Port: 1521
SID: ROA
User: CONTAFIN_ORACLE
Pass: (în secrets/test.oracle_pass)
Schema: MARIUSM_AUTO

roa2web:

LXC: 171 (claude-agent)
Path: /workspace/roa2web
Start: ./start.sh test

---

11. Fișiere Proiect

roa2web-telegram-import/
├── README.md                 # Acest fișier
├── schema-oracle.md          # Detalii schema Oracle
├── flux-contabil.md          # Formule contabile detaliate
├── api-spec.md               # Specificații API (de creat)
└── implementation-notes.md   # Note implementare (de creat)

---

12. Întrebări Deschise

1. Workflow aprobare: E necesar ca un contabil să aprobe înainte de salvare?
2. Tip document (ID_FDOC): Ce valoare pentru bonuri fiscale achiziție?
3. Analitice: Sunt necesare analitice pe conturi (ASCD, ASCC)?
4. Sucursală: Valoare default pentru ID_SUCURSALA?
5. Atașamente: Unde se face legătura ATAS_REFERINTE (ID_ENTITATE = ID_ACT)?

---

Analiză generată de Echo • 2026-02-03