feat(api,ui): MFA/TOTP, Inventory, Support, HR-Timeclock, Fiscal, Billing e Design System
Leva grande, pedida como "pelo menos mais 20 etapas, use subagentes":
fecha a pendência de MFA/TOTP da Fase 1 (feito diretamente, autenticação é
sensível demais para delegar) e lança 5 subagentes em paralelo em 2 ondas
(eden-inventory, eden-support, eden-hr-timeclock; depois eden-finance,
eden-fiscal, eden-frontend), cada um em worktree isolado, com integração
seletiva manual (barrel, app.module.ts, migrations renomeadas/aplicadas,
build/typecheck/teste ao vivo antes de cada merge).
## Backend
- MFA/TOTP (`apps/api/src/auth/mfa.service.ts`, `crypto/field-encryption.service.ts`):
login em duas etapas quando `mfa_enabled=true`, `FieldEncryptionService`
genérico (AES-256-GCM versionado, ADR-0005) reaproveitado por outros
segredos reversíveis (ex. credencial de equipamento Control iD).
- Inventory: warehouses, stock_movements (ledger append-only), serialized_assets,
asset_assignments, stock_reservations — invariante "serial/patrimônio/MAC
nunca duplicado entre ativos ativos" reforçada por índices únicos parciais
no banco (Master Prompt §15.3).
- Support/Service Desk: tickets com máquina de estados, SLA com pausa/retomada
em `waiting_customer`/`waiting_third_party` (funções puras testáveis).
- HR-Timeclock (fundação): dispositivos Control iD (senha cifrada), import de
AFD com parser + CRC-16/KERMIT, `afd_records` imutável sem exceção nem
para super_admin (sem válvula de escape, diferente de audit_log).
- Fiscal: NCM/CFOP/municípios/naturezas de operação (eden.md módulo 5, MVP de
5 das ~19 tabelas), product_fiscal_profiles com invariante de único
profile ativo por billing_component.
- Billing: subscription→billing_run→invoice idempotente (regenerar em draft
substitui, nunca duplica) e imutável após consolidar (ADR-0008: nunca
confunde faturamento/documento fiscal/recebimento).
- FKs cruzadas fechadas: quotes/client_registrations/contracts.
## Frontend — primeira leva
- `packages/ui`: Design System real extraído do tema DreamsERP comprado —
achado que mudou o escopo: o tema já vem em React+Tailwind (não só
Angular), tokens visuais reais portados (cores, Geist como fonte real,
divergindo da doc antiga que citava Nunito/Poppins).
- `apps/core-web`: login real (com suporte a MFA), sessão, shell autenticado
via `AppShell` — substitui a tela estática "Bootstrap da Fase 1".
## Bugs reais encontrados e corrigidos (todos via teste ao vivo, não leitura)
1. **Segurança**: o token de desafio MFA era aceito como access token normal
pelo `JwtAuthGuard` (mesma assinatura, nenhuma checagem da claim
`purpose`) — bypass total do segundo fator. Explorado e fechado ao vivo
contra o container real; teste de regressão em `test/mfa.spec.ts`.
2. Crase solta dentro de comentário SQL na migration de hr-timeclock quebrava
o template literal JS (`SyntaxError` ao rodar a migration).
3. CORS ausente por completo na API.
4. `turbo.json` não declarava `VITE_API_BASE_URL` como input de build — o
Turborepo cacheava o bundle do frontend ignorando mudança na env var.
5. `compose.yaml` usava `${VITE_API_BASE_URL:-/api/v1}`, que colidia com a
variável de mesmo nome do `.env` local — o default nunca era aplicado.
6. Não existia `.dockerignore` — todo build copiava node_modules/.git/
worktrees de subagentes (665MB) para dentro do contexto Docker.
Decisão do operador incorporada: a API nunca tem domínio público próprio
(só IP interno) — os 3 frontends chamam por caminho relativo `/api/v1`,
proxy externo roteia same-origin; CORS só é relevante para dev local.
Verificado: `pnpm turbo run typecheck build` (28/28), `pnpm --filter
@eden/api test` (30/30, cresceu de 15), todo o lote testado ao vivo via
curl contra os containers reais reconstruídos, incluindo os 6 bugs acima
já fechados e confirmados, e a trilha de auditoria conferida no Postgres.
Claude-Session: https://claude.ai/code/session_01BcWWuKfykGtUweXmHD6cKx
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
185
packages/database/migrations/1788457629203_billing.cjs
Normal file
185
packages/database/migrations/1788457629203_billing.cjs
Normal file
@@ -0,0 +1,185 @@
|
||||
/**
|
||||
* Billing bounded context (recurring billing engine) — Master Prompt
|
||||
* §6.10, docs/adr/0008-billing-finance-fiscal-separation.md. ADR-0008 is
|
||||
* explicit: Billing (this module) calculates *what is owed* and produces
|
||||
* an internal invoice; it is strictly separate from Finance/AR-AP
|
||||
* (collecting/paying — títulos, boletos, dunning, conciliação) and from
|
||||
* Fiscal (documento fiscal). Neither of those is built here.
|
||||
*
|
||||
* ADR-0008 lists nine Billing tables (billing_accounts, billing_cycles,
|
||||
* subscriptions/services, charge_components, usage_charges, invoices,
|
||||
* invoice_items, invoice_adjustments, billing_runs). This migration
|
||||
* builds the coherent MVP subset needed for a working, testable
|
||||
* subscription -> billing_run -> invoice flow:
|
||||
*
|
||||
* - billing_subscriptions (this migration)
|
||||
* - billing_runs (this migration)
|
||||
* - invoices (this migration)
|
||||
* - invoice_items (this migration)
|
||||
*
|
||||
* Explicitly DEFERRED, not forgotten:
|
||||
* - billing_accounts — this MVP hangs subscriptions/invoices directly
|
||||
* off `reseller_id`; a billing_account (grouping multiple subscriptions
|
||||
* under one consolidated bill) is deferred until there's a real need
|
||||
* to bill more than one subscription together.
|
||||
* - billing_cycles as its own table — this MVP derives the cycle from
|
||||
* the (billing_day, reference_year, reference_month) triple on the
|
||||
* run/subscription rather than a calendar table of cycle instances.
|
||||
* - charge_components / usage_charges — consumption/telephony billing;
|
||||
* needs the usage-rating module (out of scope), so every subscription
|
||||
* in this MVP bills a single flat `monthly_value` with no metered
|
||||
* component.
|
||||
* - invoice_adjustments / credit_debit_adjustments — the sanctioned way
|
||||
* to correct a *consolidated* invoice (never a silent edit); deferred,
|
||||
* so today a consolidated billing_run's invoices are simply immutable
|
||||
* from the application layer (see billing.ts's assertRunIsMutable).
|
||||
* - billing_run_logs — this MVP uses the shared `audit_log`
|
||||
* (auditRepo.appendAuditEvent) for every billing_run/invoice mutation
|
||||
* instead of a dedicated structured log table.
|
||||
* - proration — every subscription always bills the full monthly_value;
|
||||
* no day-proportional calculation for a subscription that started or
|
||||
* was cancelled mid-cycle. `invoice_items.item_type` already reserves
|
||||
* the 'proration' vocabulary value for when this lands, so it won't
|
||||
* need a migration of its own.
|
||||
*
|
||||
* Deferred cross-context foreign keys (no REFERENCES, plain UUID, same
|
||||
* pattern used by Quotes/Contracts/ClientRegistrations for tables owned by
|
||||
* a module built in a different worktree — see contracts' migration
|
||||
* header for precedent):
|
||||
* - billing_subscriptions.contract_id — `contracts` (Commercial/§6.6) is
|
||||
* not guaranteed to exist in every worktree this batch might land on.
|
||||
* - billing_subscriptions.reseller_id / invoices.reseller_id —
|
||||
* `resellers` is not present in THIS worktree's migration set either
|
||||
* (bootstrap-only checkout). Both FKs are integration work for
|
||||
* whoever merges this alongside the resellers/contracts migrations.
|
||||
*/
|
||||
|
||||
exports.shorthands = undefined;
|
||||
|
||||
exports.up = (pgm) => {
|
||||
pgm.sql(`
|
||||
-- =====================================================================
|
||||
-- billing_subscriptions — a recurring billing subscription derived
|
||||
-- from an active contract
|
||||
-- =====================================================================
|
||||
CREATE TABLE billing_subscriptions (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
created_by UUID REFERENCES users(id),
|
||||
updated_by UUID REFERENCES users(id),
|
||||
contract_id UUID NOT NULL,
|
||||
reseller_id UUID,
|
||||
monthly_value NUMERIC(14,2) NOT NULL CHECK (monthly_value >= 0),
|
||||
billing_day INTEGER NOT NULL CHECK (billing_day BETWEEN 1 AND 28),
|
||||
status TEXT NOT NULL DEFAULT 'active'
|
||||
CHECK (status IN ('active', 'suspended', 'cancelled')),
|
||||
started_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
cancelled_at TIMESTAMPTZ
|
||||
);
|
||||
COMMENT ON TABLE billing_subscriptions IS
|
||||
'Assinatura de cobrança recorrente derivada de um contrato ativo (Master Prompt §6.10). contract_id e reseller_id são UUID simples sem REFERENCES — mesmo padrão de FK cruzada adiada de Quotes/Contracts/ClientRegistrations: contracts/resellers não existem garantidamente neste worktree (checkout de bootstrap). A FK real é trabalho de integração central, não desta migration.';
|
||||
COMMENT ON COLUMN billing_subscriptions.monthly_value IS
|
||||
'Snapshot do valor mensal no momento da criação da subscription — NUNCA recalculado automaticamente se o contrato de origem mudar depois (isso seria uma reversão silenciosa de fatura, proibida pelo Master Prompt §24 invariante nº4). Uma mudança de valor exige cancelar e recriar a subscription (ou, quando existir, um endpoint explícito de reajuste) — nesta leva não há reajuste, só criação/cancelamento.';
|
||||
COMMENT ON COLUMN billing_subscriptions.billing_day IS
|
||||
'Dia do mês do ciclo de cobrança, limitado a 1-28 deliberadamente para nunca cair em um mês sem esse dia (evita a ambiguidade de dia 29-31 em fevereiro/meses de 30 dias) — não há regra de "último dia do mês" nesta leva.';
|
||||
COMMENT ON COLUMN billing_subscriptions.cancelled_at IS
|
||||
'Setado uma única vez, quando status transiciona para cancelled (camada de repositório) — nunca sobrescrito depois.';
|
||||
CREATE INDEX idx_billing_subscriptions_reseller ON billing_subscriptions(reseller_id);
|
||||
CREATE INDEX idx_billing_subscriptions_status_day ON billing_subscriptions(status, billing_day);
|
||||
CREATE INDEX idx_billing_subscriptions_contract ON billing_subscriptions(contract_id);
|
||||
|
||||
CREATE TRIGGER trg_billing_subscriptions_updated_at BEFORE UPDATE ON billing_subscriptions
|
||||
FOR EACH ROW EXECUTE FUNCTION set_updated_at();
|
||||
|
||||
-- =====================================================================
|
||||
-- billing_runs — one billing-close execution for a
|
||||
-- (reference_year, reference_month, billing_day) period
|
||||
-- =====================================================================
|
||||
CREATE TABLE billing_runs (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
reference_year INTEGER NOT NULL CHECK (reference_year BETWEEN 2000 AND 2100),
|
||||
reference_month INTEGER NOT NULL CHECK (reference_month BETWEEN 1 AND 12),
|
||||
billing_day INTEGER NOT NULL CHECK (billing_day BETWEEN 1 AND 28),
|
||||
status TEXT NOT NULL DEFAULT 'draft'
|
||||
CHECK (status IN ('draft', 'consolidated', 'failed')),
|
||||
consolidated_at TIMESTAMPTZ,
|
||||
triggered_by UUID REFERENCES users(id),
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
|
||||
);
|
||||
COMMENT ON TABLE billing_runs IS
|
||||
'Execução de fechamento de billing para um período + billing_day (Master Prompt §6.10). draft é reexecutável: rodar de novo com os mesmos (reference_year, reference_month, billing_day) sobre um run ainda draft SUBSTITUI (delete+reinsert, mesma transação) as invoices geradas em vez de duplicar — implementado em packages/database/src/repositories/billing.ts, generateOrRegenerateBillingRun(). consolidated é terminal e imutável pela aplicação (ver invoices.status e assertRunIsMutable). failed é reservado para quando esta leva ganhar um passo que possa falhar de forma parcial (ex. rating de consumo) — nada nesta leva efetivamente produz failed.';
|
||||
COMMENT ON COLUMN billing_runs.triggered_by IS
|
||||
'Ator (usuário) que disparou a criação/regeneração deste run — atualizado a cada regeneração em draft para refletir quem rodou por último.';
|
||||
CREATE INDEX idx_billing_runs_period ON billing_runs(reference_year, reference_month, billing_day);
|
||||
|
||||
-- Idempotência: no máximo um run 'draft' por (ano, mês, billing_day) —
|
||||
-- índice único parcial em vez de UNIQUE(reference_year, reference_month,
|
||||
-- billing_day, status) puro, porque este último permitiria dois runs
|
||||
-- 'consolidated' distintos para o mesmo período sem impedir a corrida
|
||||
-- de dois 'draft' concorrentes ao mesmo tempo (o problema real que essa
|
||||
-- invariante precisa resolver). A regra "não criar novo run para um
|
||||
-- período já consolidado" (refaturamento controlado é deferido) é
|
||||
-- reforçada na camada de aplicação, não aqui, porque múltiplos runs
|
||||
-- 'consolidated' históricos para o mesmo período não são logicamente
|
||||
-- impossíveis no schema (só indesejados pelo fluxo atual).
|
||||
CREATE UNIQUE INDEX uq_billing_runs_one_draft_per_period
|
||||
ON billing_runs(reference_year, reference_month, billing_day)
|
||||
WHERE status = 'draft';
|
||||
|
||||
-- =====================================================================
|
||||
-- invoices — internal invoice generated by a billing_run for one
|
||||
-- billing_subscription
|
||||
-- =====================================================================
|
||||
CREATE TABLE invoices (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
billing_run_id UUID NOT NULL REFERENCES billing_runs(id) ON DELETE CASCADE,
|
||||
billing_subscription_id UUID NOT NULL REFERENCES billing_subscriptions(id),
|
||||
reseller_id UUID,
|
||||
amount NUMERIC(14,2) NOT NULL CHECK (amount >= 0),
|
||||
reference_year INTEGER NOT NULL,
|
||||
reference_month INTEGER NOT NULL CHECK (reference_month BETWEEN 1 AND 12),
|
||||
status TEXT NOT NULL DEFAULT 'draft'
|
||||
CHECK (status IN ('draft', 'consolidated', 'cancelled')),
|
||||
due_date DATE,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
UNIQUE (billing_run_id, billing_subscription_id)
|
||||
);
|
||||
COMMENT ON TABLE invoices IS
|
||||
'Fatura interna (Billing) gerada por um billing_run — DISTINTA de um título de AR/AP (Finance) e de um documento fiscal (Fiscal), ADR-0008. status espelha o status do run no momento da geração (draft -> pode ser apagada/regerada enquanto o run ainda é draft; consolidated -> imutável pela aplicação, ver invariante em billing.ts). UNIQUE(billing_run_id, billing_subscription_id) é uma segunda barreira de idempotência a nível de banco: o mesmo run nunca pode gerar duas invoices para a mesma subscription.';
|
||||
COMMENT ON COLUMN invoices.reseller_id IS
|
||||
'Denormalizado a partir de billing_subscriptions.reseller_id no momento da geração — evita join obrigatório para filtrar por revenda em listagens/relatórios; nunca é a fonte da verdade (a subscription é). Sem REFERENCES pelo mesmo motivo de billing_subscriptions.reseller_id (ver cabeçalho da migration).';
|
||||
COMMENT ON COLUMN invoices.due_date IS
|
||||
'Nesta leva, due_date = dia billing_day do mês de referência (reference_year/reference_month) — regra de vencimento mais sofisticada (ex. carência após o fechamento) é responsabilidade do módulo Finance/AR-AP (ADR-0008), fora de escopo aqui.';
|
||||
CREATE INDEX idx_invoices_run ON invoices(billing_run_id);
|
||||
CREATE INDEX idx_invoices_subscription ON invoices(billing_subscription_id);
|
||||
CREATE INDEX idx_invoices_reseller_status ON invoices(reseller_id, status);
|
||||
CREATE INDEX idx_invoices_period ON invoices(reference_year, reference_month);
|
||||
|
||||
-- =====================================================================
|
||||
-- invoice_items — invoice line items (generic vocabulary; this MVP
|
||||
-- only ever generates 'recurring' automatically)
|
||||
-- =====================================================================
|
||||
CREATE TABLE invoice_items (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
invoice_id UUID NOT NULL REFERENCES invoices(id) ON DELETE CASCADE,
|
||||
description TEXT NOT NULL,
|
||||
amount NUMERIC(14,2) NOT NULL,
|
||||
item_type TEXT NOT NULL
|
||||
CHECK (item_type IN ('recurring', 'proration', 'implementation', 'adjustment')),
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
|
||||
);
|
||||
COMMENT ON TABLE invoice_items IS
|
||||
'Linhas da fatura, modeladas de forma genérica para não exigir migration nova quando proration/implementation/adjustment passarem a ser gerados automaticamente — nesta leva, a camada de aplicação só cria itens item_type=recurring (um por invoice, espelhando billing_subscriptions.monthly_value no momento da geração do run).';
|
||||
CREATE INDEX idx_invoice_items_invoice ON invoice_items(invoice_id);
|
||||
`);
|
||||
};
|
||||
|
||||
exports.down = (pgm) => {
|
||||
pgm.sql(`
|
||||
DROP TABLE IF EXISTS invoice_items;
|
||||
DROP TABLE IF EXISTS invoices;
|
||||
DROP TABLE IF EXISTS billing_runs;
|
||||
DROP TABLE IF EXISTS billing_subscriptions;
|
||||
`);
|
||||
};
|
||||
Reference in New Issue
Block a user