sowai-fiscal-svc/docs/plans/2026-07-17-fiscal-svc-f2-servico.md

F2 — sowai-fiscal-svc com paridade 1b.1 — Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: O serviço fiscal existe: API v1 multi-produto que emite (sem transmitir — paridade 1b.1), guarda certificados e séries como DONO, com idempotência, goldens (incl. ASSINADOS), suíte de contrato HTTP e OpenAPI commitado.

Architecture: FastAPI + SQLAlchemy async + Alembic no repo novo (git.sowai.com.br/jonatan/sowai-fiscal-svc, já criado, vazio), embutindo a lib sowai-fiscal@v0.1.0. A lógica de emissão/certificado é PORTADA do auto (código nosso, já revisado 3x — portar com a tabela de adaptações abaixo, não reinventar). Tenancy (product_id, tenant_ref, branch_ref) com refs opacas. Testes no MESMO pod k8s do auto (database própria fiscal_svc_test no sidecar Postgres — o lock compartilhado serializa com as suítes do auto de graça).

Tech Stack: Python 3.11, uv, FastAPI, SQLAlchemy 2.0 async, Alembic, pydantic v2, sowai-fiscal @ git+https…@v0.1.0, erpbrasil.assinatura, cryptography.

Spec (governa): auto/docs/superpowers/specs/2026-07-17-sowai-fiscal-svc-design.md (F2 + decisões 1–8 + emendas F1). Este plano é COPIADO para o repo do serviço no Task 1 (docs/plans/) junto do spec.

Global Constraints

• Convenções do auto valem aqui: zero enum PG (String + enum Python), soft delete, Decimal com bounds espelhando colunas, max_length, 409 estruturado (shared/errors.py portado), migration real test (INSERT cru), AST guard do FOR UPDATE populate_existing (portar o teste), testes de detecção provados nas duas direções.
• Tabela de adaptações do porte (vale para TODO código portado do auto):

  No auto	No serviço
  organization_id: UUID (FK organizations)	product_id: UUID (FK products) + tenant_ref: String(64) + índices por (product_id, tenant_ref)
  branch_id: UUID (FK branches)	branch_ref: String(64) + cnpj: String(14) (o vínculo forte — validado contra certificado/emitente)
  require_permission(...)	require_product(...) (API key → Product)
  Sale/rotas por venda	não existem — a emissão recebe DadosEmissao completo
  anti-oracle 404 por org	anti-oracle 404 por (product_id, tenant_ref)

• ver_proc é OBRIGATÓRIO no payload de emissão (emenda F1 — nada de default "sowai-auto" da lib).
• Idempotência: Idempotency-Key header obrigatório no POST /v1/emissoes; repetida → 200 com o documento existente.
• O Dockerfile do serviço JÁ NASCE com git no apt (lição C1 da F1).
• OpenAPI: docs/openapi-v1.json COMMITADO + teste que falha se divergir do gerado (app.openapi()).
• Testes: Makefile próprio espelhando o do auto (lock compartilhado /tmp/auto-k8s-test.lock — MESMO arquivo, de propósito; sync para um diretório PRÓPRIO no pod /app/fiscal-svc; database fiscal_svc_test).
• Commits em inglês; sem push do auto (o auto não muda na F2).

---

Task 1: scaffold + test-infra + health

Files (repo /Volumes/MacHD1/sow/sowai-fiscal-svc): pyproject.toml (deps acima + dev: pytest, pytest-asyncio, httpx), src/fiscal_svc/{__init__,main,core/config,core/db}.py, Dockerfile (base slim + git + libs mínimas — SEM WeasyPrint por ora; DANFE é F4), Makefile (k8s-test/k8s-test-file/k8s-deps espelhados do auto, sync p/ /app/fiscal-svc, database fiscal_svc_test, MESMO lock), docs/ (copiar spec + este plano), tests/conftest.py (engine/session/override no padrão do auto), tests/test_health.py.

• Health: GET /v1/health → {"status":"ok"}; teste passa NO POD via make k8s-test; commit feat: service scaffold, k8s test infra, health.

Task 2: tenancy — products + API keys

Files: src/fiscal_svc/tenancy/{models,service,deps}.py, migration products (id, name, api_key_hash — bcrypt via passlib —, webhook_secret nullable p/ F4, timestamps/soft-delete), scripts/create_product.py (CLI: gera key aleatória, imprime UMA vez, salva hash), tests/test_tenancy.py.

• require_product dependency: X-Api-Key → Product vivo (hash check) ou 401; key ausente → 401; produto soft-deletado → 401. Migration real test. Commit.

Task 3: models + migrations (as tabelas mudam de dono)

Files: src/fiscal_svc/documents/models.py — portar FiscalCertificate, FiscalDocument, e FiscalSeries (novo dono da numeração: portar FiscalDocumentSeries de auto/backend/app/modules/tenants/models.py + o allocate_fiscal_number de tenants/service.py COM o contrato no-commit + populate_existing + o guard retroativo next_number > max(numero)), com a tabela de adaptações. Migrations + real tests (INSERT cru). Constraints preservadas: UNIQUE chave_acesso; índice parcial único cert-vivo-por-branch_ref; UNIQUE (product_id, tenant_ref, branch_ref, document_model, serie) na série.

• AST guard portado (tests/test_for_update_populate_existing.py adaptado ao src novo). Commit.

Task 4: certificados + séries (API v1)

Files: src/fiscal_svc/certificates/{service,router}.py (portar auto/.../fiscal/certificate.py + rotas: POST/GET/DELETE /v1/certificados por branch_ref+cnpj; Fernet com env FISCAL_CERT_ENCRYPTION_KEY própria; validações intactas: senha/CNPJ — agora contra o cnpj do payload —, vencido, not-yet-valid, replace atômico, corrida→409), src/fiscal_svc/series/router.py (POST/GET/PATCH /v1/series), tests/.

• Testes portados do auto (test_certificate, test_fiscal_series guard) adaptados. Cross-product/tenant → 404 anti-oracle. Commit.

Task 5: emissão v1 (paridade 1b.1) + idempotência

Files: src/fiscal_svc/emission/{schemas,service,router}.py — portar auto/.../fiscal/emissao.py com as adaptações: input é EmissaoRequest = DadosEmissaoPayload (pydantic espelhando o DadosEmissao da lib + tenant_ref/branch_ref + ver_proc OBRIGATÓRIO + serie + document_model) — o serviço NÃO monta dados de venda (decisão 3: recebe pronto), só valida completude estrutural (os mesmos 409 fiscal_config_missing), resolve NADA (o FiscalResult vem dentro), aloca (série própria), monta chave (cNF do serviço, persistido), build_nfe da lib, assina (certificado do branch_ref), persiste ASSINADO num commit. Idempotency-Key UNIQUE por (product_id): repetida → 200 existente. Rotas: POST /v1/emissoes, GET /v1/documentos/{id}, /xml, lista com filtros.

• Testes: caminho feliz com goldens da lib como payload-fonte; outbox prova (assinatura sabotada → nNF não queimado); idempotência (2x mesma key → 1 documento, 200); ver_proc ausente → 422; XSD válido. Commit.

Task 6: os seguros — goldens assinados + contrato HTTP + OpenAPI

Files: tests/fixtures/test_cert.pfx (gerado por script commitado, chave de TESTE — nunca real), tests/test_signed_goldens.py (para cada golden da lib: emitir via API com dh_emi/cnf pinados + cert de teste → XML ASSINADO determinístico comparado byte a byte com tests/goldens_signed/*.expected.xml gerados uma vez — RSA PKCS#1v1.5 é determinístico; fecha o gap da emenda 7b), tests/test_contract.py (a suíte de contrato: SÓ httpx contra o app — status codes, shapes, códigos 409 — zero import do interior; é a suíte que uma implementação Go teria que passar), docs/openapi-v1.json + tests/test_openapi_committed.py (gerado == commitado, senão falha mandando regenerar).

• Suíte completa verde no pod. Commit. Tag v0.1.0 do serviço.

---

Após as tasks

1. Review Opus (porte fiel? adaptações corretas? idempotência sem corrida?) + Fable (spec F2 vs construído; drift de porte).
2. Deploy dev: Deployment+Service ClusterIP no namespace autopecas-dev (por ora — namespace próprio quando um 2º produto chegar), Secret próprio (fiscal-svc-secrets: Fernet key NOVA + database URL), NetworkPolicy. Smoke: health + emissão de teste via port-forward.
3. Kanban (card dd1fa67c → F2) + memória. Próximo: F3 (corte do auto).