3.0 KiB

Raw Blame History

Arquitectura

Alcance

kua-money-trace mantiene una fuente unica de verdad para:

movimientos financieros
documentos tributarios y no tributarios
archivos/correos originales
enlaces entre movimientos
arboles de origen de fondos
decisiones humanas de revision

Principios

Todo archivo original se conserva intacto.
Todo analisis de IA es una propuesta revisable.
Todo movimiento tiene tipo economico.
Un pago de tarjeta no es gasto: liquida deuda de tarjeta.
Un fondeo de billetera o cuenta extranjera no es ingreso operacional.
La plata en una cuenta es fungible; si no hay enlace exacto, se usa FIFO por cuenta y moneda.
Cada enlace tiene metodo, confianza y estado.

Pipeline

IMAP / archivos manuales / APIs banco
  -> archivo raw en Storagebox
  -> extraccion de adjuntos
  -> parser deterministico
  -> clasificador IA
  -> ledger normalizado
  -> grafo de dinero
  -> revision humana
  -> export contable

Ingesta inicial Gmail

Cuenta inicial:

vjoati@gmail.com

Config local:

config/mail-accounts.json

Credencial esperada:

VJOATI_GMAIL_APP_PASSWORD

Por seguridad, el downloader solo guarda:

correo original .eml
adjuntos originales
hash SHA-256
manifiesto NDJSON
preview de texto

La IA debe leer desde este archivo y crear propuestas separadas. No debe modificar los originales.

Alternativas cuando Gmail no permite app password

Apple Mail local (.emlx): si la cuenta ya esta sincronizada en Mail.app, importamos los mensajes locales sin pedir credenciales nuevas.
Google Takeout (.mbox): sirve para carga historica masiva sin OAuth ni IMAP.
Gmail API OAuth: camino correcto para sync continuo si no hay app password. Usaria gmail.readonly y users.messages.get(format=raw).

Servicios existentes

kua-mail: reutilizable como referencia para IMAP, sync, folders, threads, mailparser.
kua-notify: no sirve para inbound mail, pero si como referencia de servicio Fastify con Vault, auditoria, healthcheck y auth.
Storagebox: reutilizar patron SFTP via ssh2-sftp-client.

Storagebox sugerido

/accounting-mail/
  raw-eml/{mailbox}/{yyyy}/{mm}/{message_hash}.eml
  attachments/{yyyy}/{mm}/{sha256}-{original_filename}
  normalized/{source}/{entity}/{account}/{period}/{sha256}.json
  manifests/documents.ndjson
  manifests/extractions.ndjson

Nodos del grafo

movement:*: cartola, tarjeta, Mercado Pago, Revolut, etc.
document:*: factura, boleta, invoice, recibo, transferencia.
event:*: gasto real, ingreso real, deuda, reembolso, ajuste.
file:*: archivo original en Storagebox.

Enlaces del grafo

Direccion: from financia, explica o liquida to.

Ejemplo:

movement:darwin-income-001 -> movement:darwin-bank-pay-visa-001
movement:darwin-bank-pay-visa-001 -> movement:darwin-visa-black-spa-001
movement:darwin-visa-black-spa-001 -> event:black-spa-10804
document:black-spa-10804 -> event:black-spa-10804

3.0 KiB Raw Blame History