Plano V2 — Estrutura TDD espelhando a árvore da aplicação

Objetivo: A pasta TDD deve refletir a organização da app — navegação e contenção de funcionalidades. Ao percorrer as pastas, o leitor segue o mesmo caminho que seguiria na interface.

Princípio: A árvore de pastas = árvore de navegação/contenção da aplicação.

---

1. Árvore da aplicação (como está hoje)

Com base no código atual:

HomePage (rota /)
├── Help (Ícone ajuda → popup)
│   └── DebugHelpPopup
│       ├── Snapshot (/platform)
│       ├── Aplicar estrutura
│       └── Comando Firestore
├── Conta (Avatar → popup)
│   └── ProfileDialog
│       ├── Tab Dados
│       ├── Tab Perfil na EBD
│       ├── Tab Avatar
│       └── Tab Ações (sair, solicitar cargo, etc.)
├── Entrar (→ LoginPage)
│   └── Registrar (→ RegisterPage)
│       └── Signup por email (start, verify, resend)
├── NavTabs (Início, Frequência, Aulas)
└── ActionCards (Registrar presença, Minhas aulas)

---

2. Proposta: estrutura de pastas TDD

A estrutura de pastas espelha a árvore acima. Cada pasta contém os TDDs daquele ponto da árvore.

docs/architecture/tdd/
├── README.md
├── _category_.json
│
├── home/                          # HomePage
│   ├── _category_.json
│   ├── README.md                  # Visão geral da Home; NavTabs; ActionCards
│   │
│   ├── help/                      # Popup de ajuda
│   │   ├── _category_.json
│   │   ├── README.md              # Visão do Help
│   │   └── debug/                 # Ferramentas de debug ( dentro do Help )
│   │       ├── _category_.json
│   │       ├── tdd-snapshot.md
│   │       ├── tdd-apply-structure.md
│   │       └── tdd-firestore-command.md
│   │
│   └── profile-dialog/            # Diálogo de perfil (aberto pelo avatar)
│       ├── _category_.json
│       ├── README.md              # Visão do ProfileDialog
│       ├── tdd-dados.md           # Tab Dados
│       ├── tdd-perfil-ebd.md      # Tab Perfil na EBD (roles, igreja)
│       ├── tdd-avatar.md          # Tab Avatar
│       └── tdd-acoes.md           # Tab Ações (sair, solicitar cargo)
│
├── auth/                          # Fluxos de autenticação ( entrada via Home )
│   ├── _category_.json
│   ├── README.md
│   ├── login/
│   │   ├── _category_.json
│   │   └── tdd-login.md
│   └── register/
│       ├── _category_.json
│       ├── tdd-register.md
│       └── signup-email/
│           ├── _category_.json
│           ├── tdd-signup-start.md
│           ├── tdd-signup-verify.md
│           └── tdd-signup-resend.md
│
└── api/                           # Contratos cross-cutting ( não são "tela" )
    ├── _category_.json
    ├── tdd-my-profile.md          # GET /myProfile ( usado por Home, ProfileDialog )
    ├── tdd-gateway-usuario.md     # POST userGateway ( usado por vários )
    ├── tdd-igrejas-publicas.md    # GET publicChurches ( usado no signup )
    ├── tdd-register-pending.md    # Callable registerPendingAccount
    └── tdd-healthcheck.md         # GET healthcheck ( infra )

---

3. Navegação = árvore

Caminho na pasta	Equivalente na app
tdd/home/	HomePage (tela principal)
tdd/home/help/	Botão Ajuda
tdd/home/help/debug/	Conteúdo do popup: ferramentas de debug
tdd/home/profile-dialog/	Botão Conta → ProfileDialog
tdd/auth/login/	Tela de login
tdd/auth/register/signup-email/	Fluxo de signup por email dentro do registro

A pasta api/ fica à parte porque não é um "lugar" na UI — são contratos usados por várias features. Alternativa: colocar cada contrato na pasta da feature que o consome. Ex.: tdd-my-profile.md dentro de home/profile-dialog/. A decisão fica entre:

• Opção A: api/ na raiz — contratos centralizados
• Opção B: Contratos nas pastas das features — ex.: perfil em home/profile-dialog/tdd-api-perfil.md

Recomendação: Opção B quando o contrato é usado basicamente por uma feature; Opção A para contratos usados por várias (gateway, healthcheck).

Decisão aplicada: Híbrido

• api/ — gateway, healthcheck, igrejas públicas, register-pending (cross-cutting ou múltiplos consumidores)
• home/profile-dialog/ — tdd-api-perfil.md (contrato de perfil na pasta da feature principal)
• Demais contratos nas pastas das features que os consomem

---

4. Campos do documento TDD (não precisam ser iguais ao ADR)

O ADR responde "por que decidimos"; o TDD responde "como implementamos". Os campos podem ser diferentes.

ADR (referência)

• Status, Contexto, Decisão, Consequências

TDD proposto (campos adaptados ao design técnico)

# TDD — [Nome da feature]

## Status
Implementado | Proposto

## Contexto
- Onde aparece na app (caminho na árvore)
- ADRs relacionados
- Resumo da feature

## Contratos
- Endpoints (método, URL, headers)
- Payloads (request/response)
- DTOs e schemas
- Códigos de erro

## Fluxo
- Sequência: UI → use case → repositório → backend
- Regras de validação
- Tratamento de erros

## Código de referência
- Caminhos dos arquivos principais

Campos como "Consequências" do ADR podem ser trocados por "Fluxo" e "Código de referência" no TDD.

---

5. Lidando com a árvore em doc estático

Pastas são uma árvore. O Docusaurus já gera sidebar a partir delas. Com _category_.json em cada pasta:

{"label": "Debug", "position": 1}

a navegação na documentação replica a árvore de pastas:

TDD
├── Home
│   ├── Help
│   │   └── Debug
│   │       ├── Snapshot
│   │       ├── Apply Structure
│   │       └── Firestore Command
│   └── Profile Dialog
│       ├── Dados
│       ├── Perfil na EBD
│       └── ...
├── Auth
│   ├── Login
│   └── Register
│       └── Signup Email
└── API
    ├── myProfile
    └── ...

Isso atende ao objetivo: navegar pelas pastas equivale a navegar pela aplicação.

---

6. Regras de organização

1. Contenção: Se a feature B só existe dentro da feature A, B fica em A/B/.
2. Rotas vs. overlays: login e register são rotas; help e profile-dialog são overlays da Home. Ainda assim, auth/ agrupa os fluxos de autenticação por conveniência.
3. Nomenclatura: pastas em kebab-case; arquivos tdd-*.md ou README.md.
4. README em cada pasta: descreve o que aquela parte da árvore contém.

---

7. Resumo da proposta

Aspecto	Decisão
Estrutura	Árvore espelhando a app (home > help > debug, etc.)
Navegação	Pastas = árvore; sidebar Docusaurus segue as pastas
Campos TDD	Adaptados ao design técnico (Contratos, Fluxo, Código); não copiar ADR
Contratos API	Opção A (pasta api/) ou B (em cada feature); híbrido para gateway
Nomenclatura	Pastas kebab-case; arquivos tdd-*.md

---

8. Próximos passos (após aprovação)

1. Definir: Opção A ou B para contratos API.
2. Criar a árvore de pastas e _category_.json.
3. Incluir READMEs por pasta.
4. Preencher TDDs conforme implementação atual.
5. Validar no Docusaurus se a navegação corresponde à árvore desejada.