feat: service scaffold, k8s test infra, health

FastAPI + SQLAlchemy async + Alembic scaffold, src-layout (mirrors the
sowai-fiscal lib's own convention), pyproject wired to sowai-fiscal@v0.1.0
via git+https (uv.lock pins the commit). Makefile mirrors auto/Makefile's
k8s-test workflow: syncs into /app/fiscal-svc in the SAME auto-tests pod,
against a dedicated fiscal_svc_test database on the shared Postgres
sidecar, serialized by the SAME lock file the auto uses on purpose so the
two repos' test runs never race in the pod. Dockerfile installs git (the
git+https dependency needs it at uv sync time) and splits the dependency
layer from the project's own editable install for build caching.

GET /v1/health -> {"status": "ok"}, verified green via `make k8s-test`.

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

@@ -0,0 +1,68 @@
+# 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).

docs/specs/2026-07-17-sowai-fiscal-svc-design.md

@@ -0,0 +1,112 @@
+# sowai-fiscal-svc — serviço fiscal compartilhado — Design
+
+**Data:** 2026-07-17 · **Decisão de origem:** Estágio 2 / Caminho B (Jonatan, 2026-07-17).
+**Onde este spec vive:** no repo do auto (primeiro consumidor) até o repo do serviço
+existir; então é copiado para lá e este vira ponteiro.
+
+## Objetivo
+
+Emissão fiscal (NF-e 55 agora; NFS-e Nacional e NFC-e 65 depois) como **serviço
+compartilhado** entre produtos SowAI, consumido via REST. A 1b.2 (transporte SEFAZ +
+DANFE + reconciliador) **nasce dentro dele**. Python **permanente** (a comunidade OCA
+mantém o leiaute NT — nfelib/erpbrasil; Go descartado para este serviço por decisão
+registrada).
+
+## Decisões batidas (2026-07-17 — não re-litigar)
+
+1. **Dois repos novos (Gitea):** `sowai-fiscal` (lib — núcleo puro extraído do auto:
+   `resolver`, `xml_builder`, `chave_acesso`, `domains`, `presets`, `tpag`; versionada
+   SemVer; **EMENDA F1 2026-07-17: consumida via `git+https@tag` — pinada por hash no
+   lock — em vez de registry PyPI do Gitea**; o registry fica como opção futura se o nº
+   de consumidores crescer. Consequência operacional: `git` precisa existir nas imagens
+   que rodam `uv sync` — Dockerfile do auto ajustado) e `sowai-fiscal-svc` (FastAPI + SQLAlchemy
+   async + Alembic + `uv`, gabarito e convenções do auto — incluindo lock de pod de teste
+   e teste de migration real).
+2. **Banco:** schema próprio `fiscal_svc` na MESMA instância Postgres do cluster (dev);
+   instância separada é decisão de produção futura. `fiscal_documents`,
+   `fiscal_certificates`, `fiscal_document_series` **mudam de dono**: nascem no serviço
+   via migrations dele; os dados de teste do auto migram por script one-shot; as tabelas
+   do auto são dropadas ao fim do corte.
+3. **O motor de regras FICA no produto.** `TaxRule`/`TaxProfile`/resolver rodam no auto
+   (config de imposto é do produto); o serviço recebe o **`FiscalResult` já resolvido**
+   dentro do `DadosEmissao`. O serviço valida coerência estrutural (somas, campos
+   obrigatórios do leiaute), nunca recalcula imposto.
+4. **Tenancy:** `(product_id, tenant_ref, branch_ref)` — refs OPACAS (o serviço não
+   conhece o modelo de org de nenhum produto). O vínculo forte é o **CNPJ** da filial,
+   validado contra o certificado no upload e contra o emitente na emissão.
+5. **Auth:** API key por produto (`X-Api-Key`, hash argon2/bcrypt no banco, uma por
+   `product_id`), sem ingress público — ClusterIP + NetworkPolicy no namespace.
+   Webhooks assinados com HMAC (segredo por produto).
+6. **Idempotência:** `Idempotency-Key` obrigatória no `POST /v1/emissoes` (o produto usa
+   `sale_id` + tentativa). Chave repetida → devolve o documento existente (200), nunca
+   emite duas vezes.
+7. **Os 3 seguros de portabilidade** fazem parte do "pronto" de toda fase:
+   (a) suíte de contrato HTTP language-agnostic (bate na API, não no interior);
+   (b) **corpus golden** `DadosEmissao (JSON) → XML PRÉ-ASSINATURA esperado` como
+   fixtures (**EMENDA F1**: pré-assinatura para determinismo byte a byte com dh_emi/cnf
+   pinados. GAP REGISTRADO: o caminho de ASSINATURA fica sem seguro golden — a F2 DEVE
+   acrescentar goldens assinados com certificado de TESTE fixo do repo, viável porque
+   RSA PKCS#1v1.5 é determinístico dado input+chave iguais);
+   (c) OpenAPI versionado como fonte de verdade do contrato.
+8. **Invariantes herdados do 1b.1 permanecem intactos DENTRO do serviço:** outbox
+   (alocar nNF + persistir documento num commit), cNF persistido (anti-539), chave
+   módulo-11, certificado Fernet decifrado só em memória, um certificado vivo por
+   branch_ref (índice parcial único), imutabilidade pós-ASSINADO, fail-closed com 409
+   estruturado.
+9. **Transmissão (1b.2, dentro do serviço):** síncrona `indSinc=1` (SVRS rejeita lote
+   assíncrono de 1 — Rej. 452), timeout → retransmitir o MESMO XML → 204 →
+   `NfeConsultaProtocolo`; reconciliador = CronJob k8s → endpoint interno varrendo
+   `TRANSMITINDO`/`PENDENTE_CONSULTA`. Homologação primeiro, com o **A1 da própria
+   SowAI** (CNPJ 63329985000113; senha só o Jonatan digita, no upload).
+10. **Auto consome via port `FiscalEmitter`:** duas implementações — `InProcessEmitter`
+    (a atual, morre no corte) e `HttpEmitter` (client do serviço). Corte por flag/env;
+    rollback = voltar a flag.
+
+## API v1 (contrato)
+
+| Rota | O quê |
+|---|---|
+| `POST /v1/emissoes` | `DadosEmissao` completo + `Idempotency-Key`. Fluxo: valida → aloca → monta → assina → persiste (ASSINADO) → transmite (1b.2) → devolve estado final (`AUTORIZADA`/`REJEITADA`) ou `PENDENTE_CONSULTA` (timeout). Erros de config → 409 estruturado (`fiscal_config_missing` etc., os mesmos códigos do 1b.1). |
+| `GET /v1/documentos/{id}` | estado + metadados (chave, número, protocolo, rejeição). |
+| `GET /v1/documentos/{id}/xml` · `/danfe` | XML assinado/autorizado · DANFE PDF (1b.2). |
+| `GET /v1/documentos?tenant_ref=&branch_ref=&status=` | listagem paginada. |
+| `POST /v1/certificados` (por `branch_ref`) · `GET` (metadados) · `DELETE` | ciclo do A1 (as validações do 1b.1: senha/CNPJ/validade). |
+| `POST /v1/series` · `GET` · `PATCH` | numeração por `branch_ref`+modelo (guard retroativo `next_number > max(numero)` vem junto). |
+| `POST /v1/webhooks` | registro de callback por produto; eventos `documento.status_changed` com HMAC; retry com backoff; o produto mantém polling de reconciliação como fallback. |
+
+`DadosEmissao` v1 = o dataclass do 1b.1 congelado (emitente, destinatário,
+itens+FiscalResult por item, pagamento, ambiente) + `product_id/tenant_ref/branch_ref`.
+Congelar nomes = contrato; mudanças = v2.
+
+## Sequência de entrega (cada fase = plano próprio, ciclo completo com Fable)
+
+1. **F1 — lib `sowai-fiscal`:** extração do núcleo puro (o guard `test_fiscal_core_purity`
+   do auto garante que continua extraível) + **goldens gerados do 1b.1 atual** (N casos:
+   Padrão intra/inter, ST, devolução, com/sem UB) + publicação no registry. Auto passa a
+   depender da lib (deleta o código duplicado).
+2. **F2 — serviço com paridade 1b.1** (pronto inclui: OpenAPI **commitado como
+   artefato versionado** — o seguro (c) — e os goldens ASSINADOS do gap da emenda 7b;
+   `ver_proc` vira parâmetro por produto no contrato, não default da lib): repo, schema `fiscal_svc`, migrations, tenancy,
+   API v1 (sem transmissão), certificados, séries. **Prova de paridade: os goldens do F1
+   passam byte a byte.** Suíte de contrato HTTP nasce aqui.
+3. **F3 — corte do auto:** `HttpEmitter` atrás do port, migração one-shot dos dados de
+   teste, flag virada, tabelas fiscais do auto dropadas (migration), frontend intocado
+   (o contrato do auto com o frontend não muda — o auto proxia).
+4. **F4 — 1b.2 no serviço:** transporte SEFAZ homologação (SVRS), estados
+   AUTORIZADA/REJEITADA/PENDENTE_CONSULTA, reconciliador CronJob, DANFE, webhooks.
+   Validação de ponta: primeira nota AUTORIZADA em homologação com o A1 da SowAI.
+5. **F5 — NFS-e Nacional no serviço** (spec próprio; deadline do cliente 01/09).
+
+## Fora de escopo (deste spec)
+NFC-e/contingência (1b.4), eventos (1b.3), cálculo IBS/CBS (R1 — fica no motor do
+produto), produção SEFAZ (após homologação validada), multi-região.
+
+## Riscos e mitigações
+- **Paridade de XML na extração** → goldens byte a byte (F1/F2) — regressão fiscal é
+  impossível de passar silenciosa.
+- **Corte do auto** → port + flag + rollback trivial; dados de teste migrados por script
+  idempotente conferido por contagem+chaves.
+- **Webhook perdido** → polling de reconciliação no produto (o status cacheado na venda
+  nunca é a fonte de verdade; a fonte é o serviço).
+- **Reforma/NTs** → a lib versionada absorve upgrades de nfelib; produtos sobem a lib,
+  o serviço sobe primeiro.