Documento de Requisitos Funcionais - Horus HAB
Projeto: Horus Solicitação Municipal (SHAB Horus) Contratante: Secretaria de Desenvolvimento Urbano e Habitação (SDUH) — Governo do Estado de São Paulo Código: HORUS-REQ-FUN-001 Data: 2026-10-05 Versão: 1.4
1. Sumário Executivo
O Horus Solicitação Municipal (SHAB Horus) é uma plataforma integrada voltada para o gerenciamento e análise do desenvolvimento habitacional e urbano. O objetivo do sistema é permitir que municípios solicitem suporte ou submetam projetos habitacionais à SDUH, acompanhando todo o ciclo de aprovação — da inserção de informações preliminares até a análise final de documentação —, amparado por dados territoriais e informações georreferenciadas unificadas a nível estadual.
2. Escopo do Projeto
O escopo do projeto engloba uma plataforma web estruturada em módulos fundamentais:
- Autenticação e Segurança Híbrida
- Módulo de Solicitações Municipais
- Módulo de Informações Georreferenciadas
- Módulo de Gestão Documental
- APIs e Ingestão Analítica (BigQuery)
A plataforma abrange todos os municípios do estado e conecta equipes locais com as áreas técnicas da SDUH.
3. Perfis de Usuários
| Perfil | Funções e Permissões |
|---|---|
| Usuários Externos | Visualizam informações públicas e georreferenciadas através de rotas desprotegidas. |
Usuário do Município (municipio_user) | Preenchem formulários de solicitação, inserem dados técnicos, enviam documentos. Acesso e visibilidade estritamente limitados ao seu próprio município (Tenant Isolation). Autenticação via Gov.br (IDP.SP). |
Equipe SDUH (sduh_user / sduh_mgr / adm) | Visão global sobre todos os municípios. Revisam projetos, analisam dados, gerenciam a situação das solicitações e avançam o fluxo de aprovação. Autenticação via CyberArk (Minha Área). |
| Maintainer (API/ETL) | Perfil de máquina ou administrador de dados com privilégios para forçar refresh de cache no middleware e ingerir novos dados no pipeline de ETL. |
4. Requisitos Funcionais (Por Módulo)
Módulo 1 — Autenticação e Segurança
| ID | Requisito |
|---|---|
| 1.1 | Login Híbrido OIDC via Gov.br para municípios |
| 1.2 | Login Híbrido OIDC via CyberArk para SDUH |
| 1.3 | Login alternativo via Passkey (Biometria) para cenários de bypass de contingência |
| 1.4 | Geração de Custom Token (Firebase) e gerenciamento de sessão frontend |
Módulo 2 — Solicitações Municipais
| ID | Requisito |
|---|---|
| 2.1 | Preenchimento de informações preliminares pelo município |
| 2.2 | Painel de controle de solicitações enviadas / rascunhos |
| 2.3 | Análise técnica SDUH: aprovação (HOMOLOGADO), devolução com pendências (AGUARDANDO_DOCUMENTO) ou indeferimento (INDEFERIDO) |
| 2.4 | Análise de projetos SDUH |
| 2.5 | Histórico de tramitação e mudança de situação (aderente aos estados canônicos de máquina: RASCUNHO, EM_ANALISE, AGUARDANDO_DOCUMENTO, HOMOLOGADO, INDEFERIDO, SUSPENSO, CONCLUIDO, CANCELADO) |
Módulo 3 — Informações Georreferenciadas
| ID | Requisito |
|---|---|
| 3.1 | Visualização do mapa base e renderização de camadas de Empreendimentos (via Looker Studio Pro iframe ou render nativo) |
| 3.2 | Ferramentas de desenho em mapa (polígonos, marcações) |
| 3.3 | Consulta à base analítica de dados (BigQuery) via API otimizada (Middleware) |
Módulo 4 — Gestão Documental
| ID | Requisito |
|---|---|
| 4.1 | Upload de documentos técnicos e projetos (Upload Direto no Cloud Storage) |
| 4.2 | Validação de extensões e tamanhos de arquivos |
| 4.3 | Vinculação de documento a uma solicitação municipal específica |
| 4.4 | Análise de documentação SDUH (Validação) |
Módulo 5 — APIs e Middleware Analítico
| ID | Requisito |
|---|---|
| 5.1 | Acesso público / public docs (/public/docs) para leitura de métricas e empreendimentos |
| 5.2 | Atualização e Ingestão forçada do cache (/empreendimentos/refresh-cache) para perfis administrativos e esteiras de ETL |
| 5.3 | Autenticação M2M utilizando chaves estáticas (MACHINE_API_KEY) para rotinas batch, restritas aos endpoints /admin/ |
5. Requisitos Não Funcionais
| ID | Requisito |
|---|---|
| RNF-01 | Usabilidade: aplicação Single Page Application (SPA) responsiva, com navegação rápida provida por React + Vite e Tailwind CSS. |
| RNF-02 | Segurança (Shift-Left): código formatado pelo Biome, checado pelo Husky e verificado quanto a vulnerabilidades estáticas (Semgrep) e de containers (Trivy) nos pipelines. |
| RNF-03 | Desempenho (cache): o Middleware (FastAPI) inicia o cache em memória na primeira requisição, com latência para consultas analíticas cacheadas, TTL padrão de 15 minutos, expiração automática e endpoint de renovação forçada. |
| RNF-04 | Conformidade (Passkey / bypass): sessões por Passkey (partial_auth: true) são bloqueadas no Backend para qualquer mutação de dados, alteração de situação ou acesso a informações pessoais (LGPD), além da restrição na UI e do registro compulsório na trilha de auditoria (auditoria.log_operacao). |
| RNF-05 | Disponibilidade e recuperação: banco em instância regional de alta disponibilidade, com RTO < 1 minuto em falha de zona, backup diário e PITR de 7 dias (Doc 04, Seção 4). |
| RNF-06 | Proteção de dados (LGPD): colunas com dado pessoal classificadas e mascaradas fora de PROD; HOM não contém PII real (Doc 05, Seções 3.4 e 5.3). |
| RNF-07 | Auditoria: toda escrita em tabela crítica e todo evento de segurança são registrados em auditoria.log_operacao (Doc 04, Seção 7). |
| RNF-08 | Soberania: dados e serviços hospedados exclusivamente em southamerica-east1 (São Paulo). |
| RNF-09 | Dependência do cadastro mestre: a indisponibilidade da API de Cadastro Mestre não pode corromper dado nem impedir a leitura de dados já gravados; a gravação de vínculo com o mestre falha de forma explícita e pode ser repetida sem duplicar (Doc 01, Seção 6). |
6. Rastreabilidade
| Módulo | Componente | Schema / dataset (Doc 03) |
|---|---|---|
| 1 — Autenticação e Segurança | Express.js, Firebase Auth, Gov.br / CyberArk | seguranca, auditoria |
| 2 — Solicitações Municipais | SHAB-HorusHab (Core Backend) | solicitacao |
| 3 — Informações Georreferenciadas | Looker Studio Pro, Middleware FastAPI | *_gold (BigQuery) |
| 4 — Gestão Documental | Cloud Storage, Core Backend | mdm.arquivos |
| 5 — APIs e Ingestão Analítica | Middleware FastAPI, BigQuery | *_gold (BigQuery) |