# Gaps detectados durante geração de protótipos

Log vivo de **impactos descobertos durante geração de protótipos** que precisam ajuste em DB, feature, ADR, flowmap, telemetry ou design-system. Bidirecionalidade obrigatória — protótipos não saem aprovados com gap em aberto.

---

## Categorias

- **schema-db** — coluna nova, FK, RLS, index, constraint
- **feature-arch** — port faltando, fluxo Inngest, cache, real-time
- **adr** — decisão arquitetural nova ou conflict
- **flowmap** — estado/transição não previsto
- **telemetry** — evento novo a registrar em `events.md`
- **design-system** — token novo, componente novo, off-scale

## Severidade

- 🔴 **alta** — bloqueia surface ou viola ADR/regra de negócio
- 🟡 **média** — funciona mas exige ajuste antes de F1.0 codar
- 🟢 **baixa** — polish ou edge case, pode ser deferido

## Status

- ⏳ **aberto** — pendente decisão
- ✅ **resolvido** — aplicado em docs/* + protótipo re-rodado
- ❌ **descartado** — decidido não tocar (com razão)

---

## Template

```markdown
### [⏳/✅/❌] gap-XXX — <título curto>

**Detectado em:** prototypes/<pasta>/<slug>.html
**Categoria:** schema-db | feature-arch | adr | flowmap | telemetry | design-system
**Severidade:** 🔴 alta | 🟡 média | 🟢 baixa
**Data:** YYYY-MM-DD

**Descrição:**
O que foi observado durante geração.

**Impacto:**
Onde precisa propagar (caminho exato dos arquivos).

**Decisão pendente:**
Pergunta clara pra Gabriel responder.

**Resolução (preencher quando ✅):**
- Doc atualizado: `path/to/file.md`
- ADR criado: `0XXX-titulo.md`
- Schema migration: `migrations/XXXX_titulo.sql`
- Protótipo re-rodado: `prototypes/.../slug.html`
```

---

## Gaps em aberto

_(Nenhum gap em aberto no momento — 4 originais resolvidos em 2026-04-26.)_

---

## Gaps resolvidos

### ✅ gap-001 — Real-time push Ably listagem sem flowmap dedicado

**Detectado em:** `prototypes/04-painel/04.1-listagem-populated.html`
**Categoria:** flowmap + telemetry
**Severidade:** 🟡 média
**Data:** 2026-04-26 · **Resolvido:** 2026-04-26

**Descrição original:** Protótipo mostra "live status" + "atualizado há 2s" indicando real-time push via Ably channel `company_invoices:{company_id}`. Reconciliação assíncrona via Inngest está em flowmap 06, mas o canal Ably específico pra listagem (push de status novo SEM refresh manual) não tinha flowmap dedicado. Faltava também eventos de telemetria.

**Decisão Gabriel:** SIM — refinar flowmap 13 + adicionar 5 eventos.

**Resolução:**
- ✅ Flowmap 13 (`docs/flowmaps/13-painel-cliente-inicial.md`) seção "Real-time push status" refinada com sub-seção "UX da listagem" (badge "ao vivo" + microcopy "atualizado há Xs" + botão refresh fallback + UX de atualização em-place + status badge transition + loss of connection handling).
- ✅ 5 eventos novos adicionados em `docs/telemetry/events.md` seção 4.1 "Listing & Real-time": `invoice.list.viewed`, `invoice.list.realtime_update_received`, `invoice.list.refresh_clicked`, `invoice.detail.opened`, `invoice.action.kebab_opened` (convenção `invoice.*` consistente com 15 eventos existentes; `realtime_update_received` em axiom pra latência push, demais em posthog).
- ✅ Comentário do protótipo 04.1 atualizado pra referenciar seção 4.1.

---

### ✅ gap-002 — Header display: razao_social vs apelido

**Detectado em:** `prototypes/04-painel/04.1-listagem-populated.html`
**Categoria:** schema-db
**Severidade:** 🟢 baixa
**Data:** 2026-04-26 · **Resolvido:** 2026-04-26

**Descrição original:** Switcher CNPJ + page header mostram razão social truncada. Mock data tinha `apelido` mas schema-db.md não. Faltava regra UI canônica de display.

**Decisão Gabriel:** Razão social é default (todos terão), apelido é display friendly opcional. Lógica: `apelido ?? razao_social`.

**Resolução:**
- ✅ Coluna `apelido` adicionada em `companies` (extensão simétrica de ADR-0013) — `docs/schema-db.md` linhas 153-154.
- ✅ ADR-0013 (`docs/adr/0013-clientes-extensoes-apelido-manual-toggle-painel.md`) ganhou nota sobre extensão simétrica em `companies` (nullable, sem unique constraint, sem PII redaction — razão social é dado público no CNPJ).
- ✅ Helper `displayCompany(empresa, maxLen=40)` adicionado em `design-system/shared/mock-data.js` — implementa `apelido ?? razaoSocial` com truncate.
- ✅ Protótipo 04.1 consome `M.displayCompany(empresaAtiva)` no header + page-head.

---

### ✅ gap-003 — Coluna Data sem timezone explícito

**Detectado em:** `prototypes/04-painel/04.1-listagem-populated.html`
**Categoria:** feature-arch
**Severidade:** 🟢 baixa
**Data:** 2026-04-26 · **Resolvido:** 2026-04-26

**Descrição original:** `fmtData()` usava BRT implícito via `toLocaleString('pt-BR')`. CLAUDE.md gotcha SEFAZ menciona "BRT real (-3:00) em data_emissao". User pode estar em fuso diferente e ver hora "errada".

**Decisão Gabriel:** Timezone padrão BRT, mas user pode mudar pra timezone da região dele nas configurações da conta.

**Resolução:**
- ✅ Coluna `users.timezone` adicionada em `docs/schema-db.md` (text NOT NULL default 'America/Sao_Paulo'; IANA timezone; user altera em surface 08.1-configuracoes-perfil; per-user, não account — multi-user em UFs diferentes possível).
- ✅ `fmtData(iso, tz)` em `mock-data.js` aceita timezone arg (default BRT).
- ✅ `fmtDataTooltip(iso, tz)` novo helper retorna data ISO 8601 completa + offset pra tooltip on hover.
- ✅ Mock users ganharam campo `timezone: 'America/Sao_Paulo'`.
- ✅ Protótipo 04.1 consome `tz = user.timezone` em todos `fmtData` calls + `<span title="${fmtDataTooltip(...)}">` em cada data exibida (tabela + cards).

---

### ✅ gap-004 — Bottom nav "Mais" vs sidenav "Configurações"

**Detectado em:** `prototypes/04-painel/04.1-listagem-populated.html`
**Categoria:** flowmap
**Severidade:** 🟢 baixa
**Data:** 2026-04-26 · **Resolvido:** 2026-04-26

**Descrição original:** Bottom nav mobile tinha 4º item "Mais" (drawer agrupando) vs sidenav desktop "Configurações" — divergência.

**Decisão Gabriel:** Por hora padronizar como "Configurações" (decide depois ao ver UI real).

**Resolução:**
- ✅ Bottom nav 4º item alterado de "Mais" → "Configurações" em `prototypes/04-painel/04.1-listagem-populated.html` (ícone troca de `more-horizontal` pra `settings`).
- ✅ `data-todo` atualizado de `08-configuracoes/08.3-mais-drawer` → `08-configuracoes/08.1-perfil` (consistente com sidenav).
- ✅ Surface `08.3-configuracoes-mais-drawer` mantida no `_BACKLOG.md` pra reavaliação futura.

---

## Gaps descartados

_(vazio)_