DeskcommCRM/docs/specs/RECONCILIATION-LOG.md

title, version, status, date, owner

title	version	status	date	owner
Specs Reconciliation Log	1.1	ativo	2026-04-28	Rafael Melgaço

Specs Reconciliation Log

Registro canônico das reconciliações entre Specs/Epics quando conflitos são detectados durante consolidation passes. Decisões aqui sobrescrevem texto em arquivos individuais que conflite — texto antigo permanece pra histórico mas as edições foram aplicadas in-place.

R-01 — Nomenclatura de canal Realtime: plural

Conflito: Spec 04 §4.2 usava useChannelSession com canal nomeado org-{orgId}-channel-session (singular). Spec 09 §6 padronizou plural alinhado ao nome da tabela.

Decisão canônica: canal é channel-sessions-{orgId} (plural).

Aplicação: Spec 04 §4.2 atualizado in-place.

---

R-02 — Error code canônico para "sem credencial válida"

Conflito: Spec 01 §7.5 catalogou auth_required (401). Specs informais usaram unauthenticated.

Decisão canônica: auth_required é o único error code aceito pra HTTP 401. unauthenticated é proibido como código.

Aplicação: Spec 01 §7.5 — nota canônica adicionada.

---

R-03 — Error codes ausentes em Spec 01 §7.5

Conflito: Specs 02, 04 e 09 referenciavam codes que não estavam no catálogo canônico.

Decisão canônica: 6 novos error codes adicionados a Spec 01 §7.5: conversation_already_claimed, pipeline_immutable_use_clone, lost_reason_required, lost_reason_invalid, phone_must_be_e164, merge_irreversible.

Aplicação: Spec 01 §7.5 — tabela ampliada.

---

R-04 — OCC com expected_updated_at em mutations de leads

Conflito: Spec 02 sugeriu OCC via If-Unmodified-Since ou body expected_updated_at. Pergunta: a coluna existe e é confiável?

Decisão canônica: CONFIRMADO. crm_leads.updated_at existe via migration 0003 com trigger fn_set_updated_at. Pode ser usada como token OCC. Em conflito, retorna 409 com error code concurrent_update.

Aplicação: sem mudança em código/spec — comportamento já correto.

---

R-05 — connectNuvemshop como Server Action

Conflito: Spec 06 §4.2 documentou OAuth start como rota REST. Spec 09 ADR-02 prescreveu Server Actions.

Decisão canônica: Server Action connectNuvemshop() é o caminho default da UI. A rota REST permanece como fallback legacy.

Aplicação: Spec 06 §4.2 atualizado + Spec 09 §11 listou Server Actions catalog.

---

R-06 — Ciclo de dependência EPIC-09 ↔ EPIC-10

Conflito: Durante o consolidation pass dos epics (2026-04-28), EPIC-09 (Team) e EPIC-10 (Audit + Settings) declararam um o outro como depends_on, criando ciclo:

• EPIC-09 declarava depends_on: [EPIC-00, EPIC-01, EPIC-10] justificando que precisava do helper auditLog()
• EPIC-10 declarava depends_on: [EPIC-01, EPIC-09] (sem justificativa estrutural — viewer de audit log não depende de Team)

Causa raiz: o helper auditLog() é um utilitário de baixo nível (INSERT em api_audit_log). Não é uma capacidade de Settings — é uma camada de foundation que vários epics consomem.

Decisão canônica: helper auditLog() (SQL + TS wrapper) é exposto pelo EPIC-01 Auth & App Shell (faz sentido — é onde a infra de auth + audit fica wired) e fica disponível pra todos a partir daí.

Aplicação:

• ✅ EPIC-09 — depends_on: [EPIC-00, EPIC-01] (removeu EPIC-10)
• ✅ EPIC-10 — depends_on: [EPIC-00, EPIC-01] (removeu EPIC-09)
• 🔁 EPIC-01 deve expor lib/audit/auditLog.ts como utilitário (cobrir em uma das suas 12 stories — provavelmente na S-01.06 ao desenhar useAuth + audit context, ou story dedicada se necessário)

Justificativa: quebra o ciclo, mantém topological order, permite EPIC-09 e EPIC-10 rodarem em paralelo após EPIC-01.

---

Política pra próximas reconciliações

1. Conflitos detectados durante implementação devem ser logados aqui com IDs sequenciais (R-07, R-08, ...)
2. Decisões canônicas sobrescrevem texto em arquivos individuais — edição in-place + nota cruzada
3. Wave de implementação que tocar uma área conflitada deve ler este log antes de codar
4. Reconciliações que mudam contratos públicos versionam o changelog em CHANGELOG.md

Próximas reconciliações esperadas (a verificar)

• Naming de hooks (useFoo vs useFooQuery vs useFooMutation) — ADR a registrar
• Convenção de slug pra rotas dinâmicas ([id] vs [fooId]) — registrar quando primeira tela for implementada
• Política de cache TanStack Query (staleTime, gcTime) por tipo de recurso