[Nome da Feature] — [Papel(éis)]

Última atualização: YYYY-MM-DD

---

1. Visão Geral

Descrição funcional em 2-3 linhas: o que a feature faz, quem usa, qual problema resolve.

---

2. Arquitetura

Frontend                     Backend                      Banco
────────                     ───────                      ─────
Componente ─┐                edge-function-name           tabela_principal
Componente ─┤── useHook.ts ──── invokeAction ──────────► tabela_secundaria
Componente ─┘                                            tabela_readonly

---

3. Schema (Tabelas)

Tabela	Propósito	RLS	Constraints
nome_tabela	Descrição	Policy por papel (SELECT, INSERT, UPDATE)	UNIQUE, triggers

Colunas Relevantes

-- Apenas colunas não-óbvias ou com lógica especial
coluna_x  -- Explicação
coluna_y  -- Explicação

---

4. Edge Function

nome-da-edge-function

Action	Tipo	Descrição	Validação	Logging
action_name	Read	Descrição	—	—
action_name	Write	Descrição	Zod schema	modulo.operacao

Auth: requireRole([...]) + requireFeatureFlag("flag")CORS: getCorsHeaders(req) em todas as respostas incluindo catch.

---

5. Hook React Query

useHookName.ts

Query Keys

Key	Formato
all	['feature-name']
subKey	['feature-name', 'sub', param]

Exports

Export	Tipo	Cache Key	staleTime
useQueryName	Query	subKey	5min
useMutationName	Mutation	Invalida all	—

Invalidação

Descrever quais mutations invalidam quais caches, e se há cross-feature invalidation.

---

6. Componentes

src/components/feature-name/
├── index.tsx                  Container principal
├── sub-component.tsx          Descrição
├── helpers.ts                 Tipos + utilitários
└── __tests__/                 Testes unitários

Padrões Visuais

• Memoização: React.memo, useMemo, useCallback
• Loading: Anti-Flash Pattern (isLoading && !data)
• Toast: olpToast (nunca alert())
• Erros: getUserFriendlyError(error)

---

7. Padrões Aplicados

Padrão	Referência
Renderização Atômica	→ Ref: docs/development/ATOMIC_RENDERING.md
React Query Cache	→ Ref: docs/development/REACT_QUERY_CACHE.md
Import System	→ Ref: docs/development/IMPORT_SYSTEM_STANDARD.md

---

8. Testes

Arquivo	Tipo	Cobertura
edge-function/index.test.ts	Contract (Deno)	CORS, auth, anti-leak
useHook.integration.test.ts	Hook integration	Queries, mutations
helpers.test.ts	Unit	Utilitários

---

9. Navegação

• sections-registry.ts: id: 'feature', icon: IconName, permissionKey: 'permission'
• permissions.ts: permission no PAPEL_PERMISSIONS
• Feature flag: flag_name (deve estar ativa em feature_flags)

---

10. Referências

• Outros docs relacionados
• Links para docs de arquitetura, segurança, etc.