110 lines
3.0 KiB
Markdown
110 lines
3.0 KiB
Markdown
# 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
|
|
|
|
1. Todo archivo original se conserva intacto.
|
|
2. Todo analisis de IA es una propuesta revisable.
|
|
3. Todo movimiento tiene tipo economico.
|
|
4. Un pago de tarjeta no es gasto: liquida deuda de tarjeta.
|
|
5. Un fondeo de billetera o cuenta extranjera no es ingreso operacional.
|
|
6. La plata en una cuenta es fungible; si no hay enlace exacto, se usa FIFO por cuenta y moneda.
|
|
7. Cada enlace tiene metodo, confianza y estado.
|
|
|
|
## Pipeline
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
vjoati@gmail.com
|
|
```
|
|
|
|
Config local:
|
|
|
|
```text
|
|
config/mail-accounts.json
|
|
```
|
|
|
|
Credencial esperada:
|
|
|
|
```text
|
|
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
|
|
|
|
1. **Apple Mail local (`.emlx`)**: si la cuenta ya esta sincronizada en Mail.app, importamos los mensajes locales sin pedir credenciales nuevas.
|
|
2. **Google Takeout (`.mbox`)**: sirve para carga historica masiva sin OAuth ni IMAP.
|
|
3. **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
|
|
|
|
```text
|
|
/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:
|
|
|
|
```text
|
|
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
|
|
```
|