Blue Usage Wallet

# Blue Usage Wallet

Núcleo reutilizável de saldo, reserva e ledger para produtos cobrados por consumo no Odoo 19.

## Escopo

• carteira por cliente, empresa e código;
• saldo disponível e reservado;
• crédito, reserva, captura, liberação e estorno;
• ledger imutável;
• idempotência por empresa;
• isolamento multiempresa;
• alerta de saldo baixo.

O módulo não conhece consultas, IA, MCP, n8n, Asaas ou assinatura. Esses domínios devem integrar por bridges opcionais.

## Fluxo econômico

`text credit -> available reserve -> available to reserved capture -> consumes reserved release -> returns remainder refund -> returns captured value `

## Chaves idempotentes sugeridas

`text ai:<usage-id>:reserve ai:<usage-id>:capture api:<request-id>:capture mcp:<tool-call-id>:capture workflow:<execution-id>:capture asaas:<payment-id>:credit `

## Origem e melhorias

Port seletivo de ConexaoAzulDigital/BlueApps19#64, consolidado no repositório canônico. Nesta versão:

• os campos derivados do ledger foram incorporados diretamente ao modelo;
• referências incompatíveis a res.groups.category_id foram removidas para Odoo 19;
• o tratamento de concorrência em get_or_create captura somente IntegrityError;
• o módulo permanece independente dos produtos consumidores.

## Validação runtime

```bash python odoo-bin -c odoo.conf -d wallet_test

-i blue_usage_wallet --test-enable --test-tags /blue_usage_wallet --stop-after-init

```

Antes de produção, validar concorrência real no PostgreSQL e bridges de cobrança em base efêmera.