164 lines
3.8 KiB
Markdown
164 lines
3.8 KiB
Markdown
# kua-money-trace
|
|
|
|
Servicio separado para reconstruir el arbol de origen y destino del dinero.
|
|
|
|
No reemplaza contabilidad ni aprobacion humana. Guarda hechos, propone enlaces y permite ver de donde vino la plata que termino financiando cada gasto.
|
|
|
|
## Primer MVP
|
|
|
|
- Ledger en JSON local.
|
|
- Motor de grafo con enlaces explicitos y enlaces FIFO por cuenta.
|
|
- Trazabilidad hacia atras desde cualquier movimiento, documento o evento economico.
|
|
- API HTTP minima sin dependencias externas.
|
|
- CLI para resumen y pruebas rapidas.
|
|
|
|
## Ejecutar
|
|
|
|
```bash
|
|
npm test
|
|
npm run summarize
|
|
npm run demo
|
|
npm run serve
|
|
```
|
|
|
|
Luego:
|
|
|
|
```bash
|
|
curl http://localhost:3910/health
|
|
curl http://localhost:3910/nodes/event:black-spa-10804/origin-tree
|
|
```
|
|
|
|
## Descargar correos
|
|
|
|
Primera cuenta configurada:
|
|
|
|
```text
|
|
vjoati-gmail -> vjoati@gmail.com
|
|
kdoi-email -> kdoi@email.com
|
|
```
|
|
|
|
La clave no se guarda en el repo. Para Gmail se debe usar una app password/OAuth y exponerla solo en el entorno:
|
|
|
|
```bash
|
|
export VJOATI_GMAIL_APP_PASSWORD='...'
|
|
npm run mail:dry-run
|
|
npm run mail:download -- --limit 25 --since 2025-01-01
|
|
```
|
|
|
|
### Gmail API OAuth
|
|
|
|
El camino recomendado para Gmail es OAuth con permiso solo lectura. Necesita un OAuth Client de Google Cloud
|
|
con redirect URI `http://127.0.0.1:3912/oauth2callback` y la Gmail API habilitada.
|
|
|
|
```bash
|
|
export GOOGLE_OAUTH_CLIENT_ID='...apps.googleusercontent.com'
|
|
export GOOGLE_OAUTH_CLIENT_SECRET='...'
|
|
npm run mail:gmail-oauth
|
|
```
|
|
|
|
El comando imprime una URL, espera el callback local y guarda el refresh token en:
|
|
|
|
```text
|
|
data/mail-oauth/vjoati-gmail.token.json
|
|
```
|
|
|
|
Luego descarga desde Google, no desde Apple Mail:
|
|
|
|
```bash
|
|
npm run mail:gmail-download -- --limit 100 --since 2025-01-01
|
|
```
|
|
|
|
El archivo queda en:
|
|
|
|
```text
|
|
data/mail-archive/vjoati-gmail/
|
|
raw-eml/yyyy/mm/*.eml
|
|
attachments/yyyy/mm/*
|
|
manifests/emails.ndjson
|
|
```
|
|
|
|
Para probar sin tocar Gmail:
|
|
|
|
```bash
|
|
npm run mail:fixture
|
|
```
|
|
|
|
Si Gmail no permite app password, hay dos caminos ya soportados:
|
|
|
|
### Apple Mail local
|
|
|
|
Lista cuentas/carpetas locales de Mail.app:
|
|
|
|
```bash
|
|
npm run mail:list-apple
|
|
```
|
|
|
|
Importa una carpeta `.mbox` local de Apple Mail:
|
|
|
|
```bash
|
|
node src/mailCli.js import-apple-mail \
|
|
--account vjoati-gmail \
|
|
--source '/Users/kavi/Library/Mail/V10/.../INBOX.mbox' \
|
|
--limit 25
|
|
```
|
|
|
|
Para cuentas ya configuradas en macOS, es mejor usar el indice de Mail. Esto resuelve la cuenta desde
|
|
`~/Library/Accounts/Accounts4.sqlite`, lee `Envelope Index`, y archiva los `.emlx` locales por id de mensaje:
|
|
|
|
```bash
|
|
node src/mailCli.js import-apple-mail-index \
|
|
--account vjoati-gmail \
|
|
--mailbox all \
|
|
--since 2025-01-01 \
|
|
--limit 100
|
|
```
|
|
|
|
En Gmail, `--mailbox all` usa `[Gmail]/Todos` cuando existe y si no cae a `INBOX`.
|
|
Para la cuenta `kdoi-email`, el importador detecta la IMAP directa con mensajes y usa `INBOX`.
|
|
|
|
Atajos:
|
|
|
|
```bash
|
|
npm run mail:import-apple-index -- --limit 100 --since 2025-01-01
|
|
npm run mail:import-kdoi -- --limit 100 --since 2025-01-01
|
|
```
|
|
|
|
### Google Takeout / MBOX
|
|
|
|
Exporta Gmail desde Google Takeout como archivo `.mbox`, luego:
|
|
|
|
```bash
|
|
node src/mailCli.js import-mbox \
|
|
--account vjoati-gmail \
|
|
--file '/ruta/al/archivo.mbox' \
|
|
--limit 1000
|
|
```
|
|
|
|
## Idea central
|
|
|
|
Un pago con tarjeta no es el origen final. El arbol correcto puede ser:
|
|
|
|
```text
|
|
DTE / gasto Muralla
|
|
└─ cargo Visa Darwin
|
|
└─ pago Visa desde cuenta corriente Darwin
|
|
└─ ingreso puro Darwin
|
|
```
|
|
|
|
Y para cuentas europeas:
|
|
|
|
```text
|
|
Gasto con debito Revolut
|
|
└─ saldo Revolut EUR
|
|
└─ carga Revolut con Visa Chile
|
|
└─ pago Visa desde cuenta corriente Chile
|
|
└─ ingreso puro
|
|
```
|
|
|
|
## Proximos pasos
|
|
|
|
- Importadores para cartolas Banco de Chile, Santander, Revolut, Mercado Pago y SII RCV.
|
|
- Archivo de correos y adjuntos en Storagebox.
|
|
- Extraccion IA de PDFs/correos con estado `propuesto`, nunca aprobado automaticamente.
|
|
- Persistencia Postgres con auditoria de decisiones.
|