# Arquitectura — SUPER Comercial v1.0.0

## Fronteira do sistema
O SUPER Comercial é uma aplicação e base de dados próprias. O SUPER GCH não é CRM e não é acedido por SQL remoto.

## Camadas
- `public/`: único document root; router frontal e assets.
- `app/Core`: configuração, PDO, autenticação, RBAC, scope, CSRF, auditoria, migrações.
- `app/Sso`: cliente OIDC/SSO com Authorization Code + PKCE.
- `app/Security`: HMAC/replay protection e criptografia utilitária.
- `app/Repositories`: acesso a dados com scope.
- `app/Services`: identificadores, SLA e anexos privados.
- `app/Http/Controllers`: casos de uso HTTP.
- `templates/`: interface PT-AO.
- `database/`: schema, migrações e ledger.
- `storage/`: ficheiros privados, chaves, logs e anexos; nunca exposto pelo servidor web.
- `cli/`: instalação, administração técnica e validação.

## Fluxo funcional
`Lead → Qualificação → Contacto → Levantamento de necessidade → Cotação → Negociação → Ganho / Perdido`

As definições têm `semantic_key`/`immutable_semantic_key`. O rótulo e a ordem podem evoluir, mas a semântica histórica não deve ser reescrita.

## Governação
- SSO fornece identidade mínima.
- RBAC é local.
- Scope limita registos por utilizador/equipa/carteira e é reaplicado na Pesquisa Global.
- Eventos críticos entram em `audit_events`, com triggers contra UPDATE/DELETE.
- O hash de cada evento inclui `prev_hash`, formando uma cadeia detectável.

## PWA e identidade
O Service Worker guarda apenas shell público/assets. A identidade usa uma shell institucional configurável; o logótipo oficial deve ser instalado sem redesenho conforme `docs/BRANDING.md`.