## id
doc_ingesta_documents_comptables

## nom
Com arriben els documents comptables a FiskAppCloud — manual vs. automàtic

## descripcio
Consulta aquest document quan calgui explicar amb detall els diferents camins pels quals un
document comptable (factura de compra, factura de venda, rebut de despesa o d'ingrés) arriba a
FiskAppCloud — pujada manual amb IA, entrada 100% manual, o ingesta automàtica per correu — i què
passa quan la lectura automàtica no té prou informació. Aplica igual a compres i vendes. No és una
guia de cap pantalla concreta del formulari (per als camps, vegeu `flux_alta_factura_compra`,
`flux_alta_rebut_despesa`, `flux_alta_factura_venda` o `flux_alta_rebut_ingres`).

## contingut
### Els dos camins manuals

Des del botó "Afegir" (Compres i Despeses, o Vendes i Ingressos — el mateix mecanisme a totes
dues):

1. **Amb fitxer**: es puja un PDF o un XML (format UBL — encara poc utilitzat en la pràctica,
   gairebé cap proveïdor l'emet avui). FiskAppCloud en fa una lectura automàtica (OCR per al PDF,
   lectura estructurada pel XML) i proposa proveïdor/client, dates, línies de concepte i IVA en un
   formulari editable — l'usuari revisa i corregeix abans de desar.
2. **Sense fitxer**: es pot continuar directament al formulari manual, sense pujar cap document.

En tots dos casos, desar crea el document comptable en estat "pendent de validar" — validar-lo és
sempre un pas separat i posterior.

### El camí automàtic

Quan arriba un correu al repositori de documents de l'empresa (de compres o de vendes), un procés
en segon pla s'encarrega de tot això sense intervenció humana inicial:

1. Un primer procés detecta els fitxers nous i els posa en una cua de treball.
2. Un segon procés els processa un per un: en fa la mateixa lectura automàtica (OCR/UBL) que el
   camí manual amb fitxer, i intenta identificar qui és el proveïdor o client a partir del NIF que
   hi apareix.
3. Si reconeix el NIF com un proveïdor/client ja existent (no l'auxiliar "per defecte"), infereix
   el Tipus de Factura pel precedent — **no el llegeix del document**. No és simplement "el de
   l'última factura": mira les últimes 10 factures d'aquest proveïdor/client i tria el Tipus de
   Factura més freqüent entre elles; si n'hi ha un empat de freqüència, desempata pel més recent.
4. Si a més troba una data vàlida dins l'exercici i no és una factura duplicada (mateix
   proveïdor/client + mateix número ja comptabilitzat), **comptabilitza el document tot sol** —
   queda igualment "pendent de validar", amb el mateix mecanisme que si l'hagués creat una
   persona.
5. Si li falta el compte comptable habitual per a aquell proveïdor/client, comptabilitza igualment
   la part que pot (el document i l'IVA), però sense la línia de despesa/ingrés — caldrà
   completar-ho a mà.
6. Si no compleix els requisits mínims (NIF no reconegut, sense precedent de Tipus de Factura,
   data fora d'exercici, o duplicat), **no es comptabilitza** — es rebutja i el fitxer queda
   disponible al repositori d'errors per revisar-lo a mà.

### Resoldre un document rebutjat

El botó de documents pendents/errors de la pantalla (Compres i Despeses o Vendes i Ingressos)
mostra únicament els documents que el procés automàtic **ja ha rebutjat** — no els que encara
s'estan processant. En seleccionar-ne un, FiskAppCloud obre el mateix modal de creació manual amb
el fitxer ja precarregat — es continua exactament pel camí "amb fitxer" descrit més amunt.

## font_tecnica
- Workers: `Workers/DocumentsPendentsScanWorker.cs` (detecta fitxers nous, cada 5 minuts —
  recorre compres, vendes i nòmines de cada empresa), `Workers/DocumentsPendentsProcessWorker.cs`
  (processa la cua, comptabilitza o rebutja), `Workers/DocumentsPendentsQueueKick.cs`
  (coordinació entre els dos anteriors)
- Inferència del Tipus de Factura per precedent: `Services/DocumentComptabilitzacioService.cs` —
  `ObtenirIdTDCPerPrecedentAsync` (línia 1089): agafa les últimes 10 factures del proveïdor/client,
  agrupa per `IdTDC`, tria la freqüència més alta i desempata per la més recent
- Endpoints: `Controllers/FacturesController.cs` — `AnalitzarFacturaAzure`, `LlistarErrors`,
  `DescarregarError`, `EliminarError`
- JS: `wwwroot/js/documents/factures/factura-create.js`; modal "Repositori Pendents" a
  `Views/Shared/Modals/Factures.cshtml`