# Arquitetura da API — Congregação / Matriz

A Fase 02 mantém o aplicativo funcionando com cache local e define o contrato para a API central.

## Identidade obrigatória
Todo registro sincronizável deve conter:
- `uuid`: identificador global imutável.
- `congregacao_id`: identifica a origem/dona do registro.
- `updated_at`: controle de atualização.
- `sync_status`: `PENDENTE`, `SINCRONIZADO` ou `ERRO` no cliente.

## Perfis
- `ADMIN`: gestão total da própria congregação.
- `SECRETARIA`: gestão de membros/documentos conforme permissão.
- `LIDER`: acesso limitado ao departamento/ministério.
- `MEMBRO`: somente dados pessoais, carteirinha, agenda, avisos e escalas autorizadas.

## Endpoints previstos
- `POST /auth/login`
- `POST /auth/refresh`
- `GET|POST /members`
- `GET|PUT /members/{uuid}`
- `GET|POST /notices`
- `GET|POST /events`
- `GET /dashboard`
- `GET /me`
- `GET /me/card`
- `GET /me/schedules`
- `POST /schedules/{uuid}/confirm`
- `POST /schedules/{uuid}/decline`
- `POST /schedules/{uuid}/replacement-request`
- `POST /schedules/{uuid}/substitute`
- `POST /schedules/{uuid}/reminder`
- `POST /sync/push`
- `GET /sync/pull?since=...`

## Regra para a futura Matriz
A congregação nunca acessa o banco de outra congregação diretamente. A Matriz recebe dados consolidados por API e permissões de escopo. O backend valida `congregacao_id` pelo token autenticado; o aplicativo não decide sozinho qual congregação pode consultar.

## Fluxo de escalas — Fase 06
- Escala nova nasce como `PENDENTE`.
- O membro pode `CONFIRMAR`, `RECUSAR` com motivo ou solicitar `SUBSTITUICAO_SOLICITADA`.
- A administração escolhe o substituto e encerra como `SUBSTITUIDA`.
- Toda resposta altera `updated_at` e deverá entrar no próximo ciclo de sincronização com a Matriz.
- Lembretes são registrados como notificações e, quando o push estiver ativo, poderão disparar FCM para o usuário vinculado.


## Fase 10 — Configurações oficiais da congregação
- `GET /api/v1/congregacao/configuracoes` — retorna identidade oficial da congregação autenticada.
- `PUT /api/v1/congregacao/configuracoes` — ADMIN atualiza nome, contato, CNPJ, responsáveis e validade de carteirinha.
- `POST /api/v1/congregacao/logomarca` — upload da logomarca e atualização de `logo_url`.
- `POST /api/v1/congregacao/assinatura` — upload protegido da assinatura e atualização de `assinatura_url`.
- Toda atualização deve gravar auditoria e fila `sincronizacao_matriz`, sempre respeitando `congregacao_id`.


## Fase 11 — implementação inicial
A API PHP/MySQL executável está em `server-api/public/index.php`. O login usa `password_verify`, tokens aleatórios de 256 bits são armazenados somente como SHA-256 em `api_tokens`, e toda rota autenticada deriva `congregacao_id` do token. A sincronização inicial bidirecional cobre congregação, membros, avisos e eventos.