PLANO-ESTRUTURA-TDD

1. Formato de registro (espelhando ADR)

1.1 Padrão ADR (referência)

• Localização: docs/architecture/adrs/
• Nomenclatura: adr-XXXX-nome-descritivo-kebab-case.md (ex.: adr-0014-gateway-unico-operacoes-usuario-handlers-por-acao.md)
• Estrutura do arquivo:

  ---
  sidebar_position: N
  ---
  # ADR-XXXX — Título Descritivo
  ## Status
  Aprovado | Proposto | Deprecado
  ## Contexto
  ...
  ## Decisão
  ...
  ## Consequências
  ...

1.2 Padrão TDD proposto

• Nomenclatura: tdd-XXXX-nome-descritivo-kebab-case.md
• Estrutura do arquivo (espelhando ADR):

  ---
  sidebar_position: N
  ---
  # TDD-XXXX — Título Descritivo (ex.: API Perfil de Usuário)
  ## Status
  Implementado | Proposto
  ## Contexto
  Feature/domínio; ADRs relacionados.
  ## Contratos
  Endpoints, payloads, DTOs, schemas.
  ## Fluxo de dados
  Request → validação → use case → response.
  ## Referências
  - ADR-XXXX
  - Código: backend/... ou frontend/...

---

2. Features implementadas (mapeamento)

2.1 Backend (Cloud Functions)

#	Feature	Endpoint/Handler	Responsável
1	Perfil do usuário	myProfileHttp GET	MyProfileHttpController → ProcessUserAction(USER_GET)
2	Gateway de usuário	userGatewayHttp POST	UserGatewayHttpController → ProcessUserAction (USER_GET, USER_PROFILE_UPDATE, USER_ROLES_AVAILABLE_LIST, USER_ROLE_REQUEST, USER_ROLE_REQUEST_APPROVE/REJECT/DELETE, USER_ROLE_REQUESTS_PENDING, USER_ACTIVE_ROLE_SET, USER_PREFERENCES_UPDATE, USER_SELF_REGISTER, USER_MESSAGES_LIST)
3	Registro de conta pendente	registerPendingAccount (callable)	RegisterPendingAccountController → CreatePendingAccountUseCase
4	Signup por email — início	emailSignupStartHttp	EmailSignupHttpController.handleStart
5	Signup por email — reenviar	emailSignupResendHttp	EmailSignupHttpController.handleResend
6	Signup por email — verificar	emailSignupVerifyHttp	EmailSignupHttpController.handleVerify
7	Igrejas públicas	publicChurchesHttp GET	PublicChurchesHttpController → listChurchOptionsByDomain
8	Healthcheck	healthcheck GET	HealthcheckController
9	Platform Debug	platformDebugHttp, platformDebugApplyHttp, platformDebugFirestoreHttp	Controllers de debug (dev)

2.2 Frontend (Flutter)

#	Feature	Módulo/Camada	Componentes principais
1	Login (email/senha)	application, presentation	SignInWithEmailPassword, LoginPage
2	Login (Google)	application, presentation	SignInWithGoogle, SignInWithGoogleAuthOnly, LoginPage
3	Registro (signup)	application, presentation	StartEmailSignup, VerifyEmailSignupCode, ResendEmailSignupCode, RegisterPage
4	Reset de senha	application, presentation	SendPasswordResetEmail
5	Perfil — leitura	application, domain, infrastructure	GetMyProfile, UserProfileService, BackendHttpProfileRepository
6	Perfil — diálogo	presentation	ProfileDialog, HomeProfileDialog, HomeProfileDialogTabs, HomeProfileDialogAvatar, HomeProfileDialogActions
7	Registro conta pendente	application, presentation	RegisterCurrentUserPendingAccount
8	Catálogo de papéis	application, domain	RoleCatalogService, RoleCatalogItem
9	Opções de igreja (signup)	application, domain, infrastructure	GetSignupChurchOptions, SignupChurchOption
10	Home	presentation	HomePage, _NavTabs (Início, Frequência, Aulas), ActionCards
11	Debug (plataforma)	application, presentation	GetPlatformDebugSnapshot, ApplyPlatformDebugStructure, ExecutePlatformDebugFirestoreCommand, DebugHelpPopup

---

3. Estrutura de pastas proposta

Opção A — Plana (espelhando ADRs)

Todos os TDDs na pasta tdd/, com numeração sequencial. Simples, consistente com adrs/.

docs/architecture/tdd/
├── README.md
├── _category_.json
├── tdd-0001-api-perfil-usuario.md
├── tdd-0002-gateway-usuario-acoes.md
├── tdd-0003-register-pending-account.md
├── tdd-0004-fluxo-signup-email.md
├── tdd-0005-api-igrejas-publicas.md
├── tdd-0006-catalogo-papeis.md
├── tdd-0007-healthcheck.md
├── tdd-0008-auth-frontend.md
├── tdd-0009-perfil-dialog-frontend.md
├── tdd-0010-home-page-frontend.md
└── tdd-0011-platform-debug.md

Opção B — Por camada (backend / frontend)

Subpastas separando backend e frontend. Facilita navegação por stack.

docs/architecture/tdd/
├── README.md
├── _category_.json
├── backend/
│   ├── _category_.json
│   ├── tdd-0001-api-perfil-usuario.md
│   ├── tdd-0002-gateway-usuario-acoes.md
│   ├── tdd-0003-register-pending-account.md
│   ├── tdd-0004-fluxo-signup-email.md
│   ├── tdd-0005-api-igrejas-publicas.md
│   ├── tdd-0006-catalogo-papeis-gateway.md
│   ├── tdd-0007-healthcheck.md
│   └── tdd-0008-platform-debug.md
└── frontend/
    ├── _category_.json
    ├── tdd-0001-auth.md
    ├── tdd-0002-perfil.md
    ├── tdd-0003-home.md
    └── tdd-0004-debug.md

Opção C — Por domínio funcional

Subpastas por área de negócio. Agrupa por feature, independente de stack.

docs/architecture/tdd/
├── README.md
├── _category_.json
├── perfil/
│   ├── _category_.json
│   ├── tdd-0001-api-perfil-usuario.md
│   └── tdd-0002-perfil-dialog-frontend.md
├── auth/
│   ├── _category_.json
│   ├── tdd-0001-signup-email.md
│   ├── tdd-0002-register-pending-account.md
│   └── tdd-0003-auth-frontend.md
├── roles/
│   └── tdd-0001-catalogo-papeis.md
├── organizacao/
│   └── tdd-0001-api-igrejas-publicas.md
├── home/
│   └── tdd-0001-home-page.md
└── infra/
    ├── _category_.json
    ├── tdd-0001-healthcheck.md
    └── tdd-0002-platform-debug.md

---

4. Recomendação

Opção A (plana) — pela consistência com adrs/, simplicidade e facilidade de manutenção. Numeração única permite ordenação clara e evita ambiguidade entre backend e frontend.

---

5. Conteúdo mínimo por TDD

Cada arquivo deve conter:

1. Frontmatter: sidebar_position, metadados se necessário
2. Título: # TDD-XXXX — Nome da feature
3. Status: Implementado
4. Contexto: Qual feature, qual ADR base
5. Contratos:
   • Backend: endpoint, método, headers, payload (request/response), códigos de erro
   • Frontend: use cases, repositórios, DTOs, fluxo de chamada
6. Referências: links para ADR e caminhos de código

---

6. Checklist antes de implementar

• Aprovar opção de estrutura (A, B ou C)
• Ajustar numeração/agrupamento conforme escolha
• Criar arquivos vazios ou com esqueleto
• Preencher cada TDD com conteúdo conforme features mapeadas
• Validar links e referências no Docusaurus

---

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

1. Criar pasta(s) e arquivos conforme estrutura aprovada
2. Preencher TDDs na ordem de dependência (ex.: perfil antes de roles)
3. Revisar e publicar na documentação