# Protótipos navegáveis ZapNotei

App estático de protótipos clicáveis (HTML + CSS + JS), feito **antes do desenvolvimento real** pra validar arquitetura, schema DB, fluxos e features sem custo de codar React.

> **Status:** fase pré-F1.0 — protótipos NÃO são código de produção. São documentação executável.

> **Localização:** `docs/flowmaps/wireframes/prototypes/` — protótipos vivem dentro dos wireframes pq são implementação navegável dos wireframes textuais (mesma numeração de pastas, `.html` + `.md` lado a lado por surface).

> **Norte canônico:** [`docs/arquitetura/principios-hexagonal-tokenizacao.md`](../../../arquitetura/principios-hexagonal-tokenizacao.md) — TODA decisão técnica/visual nos protótipos deve ser auditável contra esse doc. Aplica regras de Hexagonal (domain → port → adapter, 10 ports formais, DI factory) + Tokenização (`var(--token)` only, componentes do DS como anatomy canônica) + bidirecionalidade tripla.

---

## ⚠️ Princípio fundamental — bidirecionalidade tripla

**Protótipos refletem fielmente:**
1. **Documentação ZapNotei** (`docs/`) — schema, ADRs, flowmaps, telemetry
2. **Design System** (`design-system/`) — tokens, componentes, assets, mock-data
3. **Wireframes textuais** (`docs/flowmaps/wireframes/<pasta>/*.md`) — spec por surface

E vice-versa: mudança em qualquer um propaga pros outros dois.

### Regras de propagação

| Mudança de origem | Propagar OBRIGATORIAMENTE |
|---|---|
| **Protótipo** descobre necessidade nova (campo, fluxo, estado, port, gate) | `docs/schema-db.md`, `docs/flowmaps/`, `docs/adr/` (novo ADR), `docs/telemetry/events.md`, wireframe `.md` da surface — registrar em [`_GAPS-DETECTADOS.md`](./_GAPS-DETECTADOS.md) |
| **`docs/`** muda regra (schema, ADR, flowmap, port) | Re-rodar protótipos afetados — atualizar `mock-data.js` (se schema), HTML das surfaces tocadas |
| **`design-system/`** atualiza token / componente / asset | Re-rodar protótipos consumidores (todos importam de `design-system/foundations/` + `components/` + `shared/` + `assets/`). Componente novo no protótipo? **Adicionar primeiro ao DS** seguindo governança em [`design-system/README.md`](../../../../design-system/README.md) |
| **Wireframe `.md`** atualiza spec textual | Re-rodar protótipo correspondente; estados/IA/eventos novos viram código no `.html` |

### Por que essa fase importa

- Pega gaps em DB / feature / port / fluxo ANTES de gastar sprints codando React/Drizzle errado
- Stress-testa o DS (componentes/tokens) em uso real cross-surface
- Materializa decisões de ADR pra validar visualmente (ADR-0019 sem badge ambiente, ADR-0020 aggregate, ADR-0017 demo, etc)
- Documentação executável — auditor/contratado abre `index.html` e navega o produto inteiro

---

## Estrutura

```
docs/flowmaps/wireframes/prototypes/
├── README.md                   este arquivo
├── _BACKLOG.md                 surfaces a gerar (priorizadas por fase)
├── _GAPS-DETECTADOS.md         log vivo de impactos em DB / feature / ADR / flowmap / DS
├── 01-auth/                    login + OTP + 2FA (Auth.js sem senha)
├── 02-onboarding/              cadastro empresa + A1 upload (KMS day-0)
├── 03-form/                    form NFS-e + NF-e + recovery 3 camadas
├── 04-painel/                  listagem + detalhe + aggregate-emit-modal
├── 05-chat/                    chat conversacional (F1.1+)
├── 06-clientes/                CRM (PJ + PF) + apelido + DSR LGPD
├── 07-admin/                   multi-CNPJ + switcher aberto + notificações
├── 08-configuracoes/           perfil + plano + certificado A1
├── 09-ops/                     painel ops (acesso só URL direto, desktop-first OK)
├── 10-marketing/               LP + demo público (ADR-0017)
└── 11-blog/                    blog público + admin Payload (ADR-0014)
```

**Numeração espelha [`docs/flowmaps/wireframes/`](../README.md) (pasta pai)** — cada surface tem `.md` companion textual + `.html` navegável na mesma pasta numerada.

**Assets compartilhados (`prototype-chrome.css`, `prototype-nav.js`, `mock-data.js`, `build-cloud.sh`) ficam em [`design-system/shared/`](../../../../design-system/shared/)** — fonte única do DS, não duplicada aqui.

---

## Como abrir

### Local

```bash
# Opção 1: abrir direto no browser (file://)
open docs/flowmaps/wireframes/prototypes/index.html

# Opção 2: servir via http (recomendado pra cross-screen nav)
cd docs/flowmaps/wireframes/prototypes && python3 -m http.server 8080
# → http://localhost:8080
```

Tudo funciona com `file://` puro (sem build step). IIFE em vez de ES modules pra evitar CORS local.

### Cloud — ATIVO (CF Pages)

| URL | Escopo |
|---|---|
| **https://app-prototype.zapnotei.site** | Surfaces user-facing (auth/onboarding/form/painel/chat/clientes/admin/configs/marketing/blog público) |
| **https://ops-prototype.zapnotei.site** | Surfaces ops-only (dashboard/cross-account/impersonate/ambiente-avancado/blog admin Payload) |
| https://zapnotei-prototypes.pages.dev | URL CF Pages direta (mostra todas surfaces, sem filtro) |

Mesmo bucket CF Pages serve ambos domains. Filtro de escopo é client-side (JS detecta hostname).

**Setup técnico:**
- Projeto CF Pages: `zapnotei-prototypes`
- Build script: [`design-system/shared/build-cloud.sh`](../../../../design-system/shared/build-cloud.sh) — copia `docs/flowmaps/wireframes/prototypes/` + `design-system/` → `_dist/` + ajusta paths via sed
- Output dir CF: `_dist/`
- DNS: 2 CNAMEs CF Pages (`app-prototype` + `ops-prototype` → `zapnotei-prototypes.pages.dev`, proxied)
- SSL: CF Universal cert ativo

**Re-deploy:**
```bash
cd _projects/ZapNotei && \
bash design-system/shared/build-cloud.sh && \
set -a && source ../../.env && set +a && \
npx wrangler pages deploy _dist --project-name=zapnotei-prototypes --branch=main --commit-dirty=true
```

`_dist/` está em `.gitignore` (build artifact, não commita).

---

## Convenções de protótipo

### HTML mínimo

```html
<!DOCTYPE html>
<html lang="pt-BR">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>ZapNotei · {Surface}</title>
  <link rel="stylesheet" href="../../../../design-system/foundations/tokens.css">
  <link rel="stylesheet" href="../../../../design-system/foundations/utilities.css">
  <link rel="stylesheet" href="../../../../design-system/shared/prototype-chrome.css">
  <script src="../../../../design-system/shared/mock-data.js" defer></script>
  <script src="../../../../design-system/shared/prototype-nav.js" defer></script>
</head>
<body data-slug="04.1-painel-listagem-populated"
      data-title="Painel — Listagem (populated)">
  <!-- conteúdo da surface -->
</body>
</html>
```

> **Paths relativos:** depth 4 da raiz do repo (`docs/flowmaps/wireframes/prototypes/<pasta>/<arquivo>.html`), portanto `../../../../design-system/...` pra alcançar o DS. No deploy CF Pages, build script ajusta automaticamente pra `../_design-system/...`.

### Reuso obrigatório (base de design = `design-system/`)

A base de design dos protótipos vem **integralmente** do `design-system/`. Nada inventado ad-hoc. Se algo falta no DS, **adicionar primeiro ao DS** (governança em [`design-system/README.md`](../../../../design-system/README.md)).

- **Tokens:** 100% `var(--token)` de [`design-system/foundations/tokens.css`](../../../../design-system/foundations/tokens.css). Zero hex hardcoded.
- **Utilities:** [`design-system/foundations/utilities.css`](../../../../design-system/foundations/utilities.css) (focus-visible, skip-link, reduced-motion, print)
- **Componentes:** copiar anatomy do `*.html` correspondente em [`design-system/components/`](../../../../design-system/components/) (header-app, switcher-cnpj, status-badge, toast, empty-state, error-page, skeletons, discard-draft-modal, quiz-form, banner-system, component-pack-18). Trocar dados estáticos por `window.ZNMock`.
- **Assets:** logos sempre via `<img>` apontando pra [`design-system/assets/`](../../../../design-system/assets/). Hero textures via tokens (`--bg-hero`, `--bg-balance-card`, etc).
- **Mock data:** [`design-system/shared/mock-data.js`](../../../../design-system/shared/mock-data.js) — empresas, NFs, users, clientes (espelha schema-db). Helpers: `displayCompany()`, `fmtData(iso, tz)`, `fmtDataTooltip(iso, tz)`, `fmtMoeda()`, `fmtCnpj()`, `getActiveUser()`, etc.
- **Lucide icons:** `<script src="https://unpkg.com/lucide@latest"></script>` + `lucide.createIcons()` (stroke 1.5, linecap/linejoin round — Regra DS).

### REGRAS FUNDAMENTAIS (não-negociáveis)

#### Regra 1 — Mobile-first universal

- TODO protótipo começa em 375px e escala pra cima
- Media queries SEMPRE `@media (min-width: ...)` — **proibido** `@media (max-width: ...)` em surfaces user-facing
- Touch targets 44×44 mínimo no mobile
- **Exceção formal:** `09-ops/` (responsivo, mas desktop-first OK — ops opera em desktop primário)

#### Regra 2 — Logo correta

Usar SEMPRE arquivos de [`design-system/assets/`](../../../../design-system/assets/):

| Arquivo | Uso |
|---|---|
| `logo.svg` | Brand completo (mark + texto "ZapNotei") light mode — landing, footer, marketing header |
| `logo-light.svg` | Brand completo dark mode (mark lime + texto branco) |
| `logo-mark.svg` | Mark só (squircle deep green + chat bubble lime) — header app/sidenav apertado, favicon |
| `logo-mark-circle.svg` | Mark variante circle — uso opcional em avatares branded |

**Padrão recomendado:**

- **Sidenav desktop (top brand):** dual-image com CSS swap via `[data-theme]`
  ```html
  <img src="../../../../design-system/assets/logo.svg" alt="ZapNotei" height="32" class="logo-light-mode">
  <img src="../../../../design-system/assets/logo-light.svg" alt="ZapNotei" height="32" class="logo-dark-mode">
  ```

- **Header mobile/tablet (espaço apertado):**
  ```html
  <img src="../../../../design-system/assets/logo-mark.svg" alt="ZapNotei" width="36" height="36">
  ```

**PROIBIDO:** `<div class="logo">Z</div>`, `<div class="brand-mark">Z</div>`, ou qualquer placeholder textual da marca. Componentes/seções/elementos que não estão atualizados com identidade visual adequada precisam de atualização.

#### Regra 3 — Sem anotações marginais sketchy

A partir de 2026-04-26, **NÃO usar** anotações inline tipo `<div class="proto-annot">` apontando setas pros componentes. Razões:

- Poluem visual + competem com hierarquia da própria UI
- Decisões de design pertencem ao wireframe `.md` companion (mesma pasta numerada) — fonte textual permanente, versionada
- Design system "fala por si" — se precisar explicar visualmente o que algo faz, é sinal que IA/anatomy ainda não está clara o suficiente

**Pra documentar decisão de design:** editar wireframe `.md` correspondente em `docs/flowmaps/wireframes/<pasta>/<slug>.md` com seção "Decisões e racional", linkar ADRs aplicáveis. Mantém audit trail textual permanente.

### Navegação entre telas

- Links nativos: `<a href="../03-form/03.2-form-emissao-nfe.html?id=nf_001">`
- Programático: `window.ZNProto.navTo('../05-chat/05.1-onboarding.html')`
- Querystring carrega ID de mock data: protótipo lê `URLSearchParams` → `ZNMock.getNfById(id)`
- Estado persistente cross-screen via `localStorage` (CNPJ ativo, dark mode)

---

## Workflow

1. **Surface entra em backlog** ([`_BACKLOG.md`](./_BACKLOG.md)) com prioridade (F1.0 P0, P1, etc) + ADRs aplicáveis + componentes do DS a consumir
2. **Validar wireframe `.md`** existe em `docs/flowmaps/wireframes/<pasta>/<slug>.md` (companion textual). Se não existe, criar com base em [`docs/flowmaps/wireframes/_template.md`](../_template.md)
3. **Gerar HTML** consumindo DS (`foundations/` + `components/` + `assets/` + `shared/mock-data.js`)
4. **Auto-audit** durante geração:
   - ADRs respeitados?
   - Componentes do DS reusados (não inventados sem governança)?
   - Tokens existentes (sem novos silenciosos)?
   - Schema-db cobre todos campos exibidos?
   - Eventos de telemetria já em `events.md`?
   - Mobile-first puro (Regra 1)?
   - Logo correta (Regra 2)?
   - Zero anotações marginais (Regra 3)?
5. **Gaps detectados** → registrar em [`_GAPS-DETECTADOS.md`](./_GAPS-DETECTADOS.md) com categoria, severidade, decisão pendente
6. **Validação user** → ajustes
7. **Aprovado** → sincronizar:
   - Wireframe `.md` companion (spec textual derivada do protótipo final)
   - `docs/schema-db.md` se gap virou alteração
   - `docs/adr/` se decisão arquitetural emergiu
   - `docs/telemetry/events.md` se evento novo
   - `design-system/components/` se componente novo (governança DS)

---

## Documentos linkados

- [CLAUDE.md ZapNotei](../../../../CLAUDE.md) — regras gerais (incluindo seção sobre `prototypes/`)
- [docs/flowmaps/wireframes/](../README.md) — spec textual `.md` por surface (companion dos protótipos, pasta pai)
- [docs/flowmaps/](../../) — fluxos UX e conversa (18 flowmaps)
- [docs/adr/](../../../adr/) — decisões arquiteturais (20+ ADRs)
- [docs/schema-db.md](../../../schema-db.md) — modelo de dados Postgres + RLS
- [docs/telemetry/events.md](../../../telemetry/events.md) — catálogo eventos canônicos
- [design-system/](../../../../design-system/) — **fonte da verdade visual** (consumido integralmente por todos os protótipos)
- [design-system/components/](../../../../design-system/components/) — 11 componentes HTML referência canônica
- [design-system/shared/](../../../../design-system/shared/) — assets compartilhados (chrome, nav, mock-data, build-cloud)