Skip to main content

Plano — Estrutura de Pastas TDD para Features Implementadas

Objetivo: Definir a estrutura de pastas e documentos TDD para registrar todas as features já implementadas no frontend e backend, seguindo o formato dos ADRs.

Status: Aguardando aprovação antes de implementar.

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)​

#FeatureEndpoint/HandlerResponsável
1Perfil do usuáriomyProfileHttp GETMyProfileHttpController → ProcessUserAction(USER_GET)
2Gateway de usuáriouserGatewayHttp POSTUserGatewayHttpController → 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)
3Registro de conta pendenteregisterPendingAccount (callable)RegisterPendingAccountController → CreatePendingAccountUseCase
4Signup por email — inícioemailSignupStartHttpEmailSignupHttpController.handleStart
5Signup por email — reenviaremailSignupResendHttpEmailSignupHttpController.handleResend
6Signup por email — verificaremailSignupVerifyHttpEmailSignupHttpController.handleVerify
7Igrejas públicaspublicChurchesHttp GETPublicChurchesHttpController → listChurchOptionsByDomain
8Healthcheckhealthcheck GETHealthcheckController
9Platform DebugplatformDebugHttp, platformDebugApplyHttp, platformDebugFirestoreHttpControllers de debug (dev)

2.2 Frontend (Flutter)​

#FeatureMódulo/CamadaComponentes principais
1Login (email/senha)application, presentationSignInWithEmailPassword, LoginPage
2Login (Google)application, presentationSignInWithGoogle, SignInWithGoogleAuthOnly, LoginPage
3Registro (signup)application, presentationStartEmailSignup, VerifyEmailSignupCode, ResendEmailSignupCode, RegisterPage
4Reset de senhaapplication, presentationSendPasswordResetEmail
5Perfil — leituraapplication, domain, infrastructureGetMyProfile, UserProfileService, BackendHttpProfileRepository
6Perfil — diálogopresentationProfileDialog, HomeProfileDialog, HomeProfileDialogTabs, HomeProfileDialogAvatar, HomeProfileDialogActions
7Registro conta pendenteapplication, presentationRegisterCurrentUserPendingAccount
8Catálogo de papéisapplication, domainRoleCatalogService, RoleCatalogItem
9Opções de igreja (signup)application, domain, infrastructureGetSignupChurchOptions, SignupChurchOption
10HomepresentationHomePage, _NavTabs (Início, Frequência, Aulas), ActionCards
11Debug (plataforma)application, presentationGetPlatformDebugSnapshot, 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
Last updated on