Versão v1.0

Objetivo

Detalhar os requisitos funcionais estritamente alinhados ao recorte da v1.0 do SSDOi.

Neste recorte, a v1.0 é tratada como um núcleo de avaliação automática, sem interface gráfica e com parametrização única definida diretamente no código.

O enquadramento desta versão no planejamento do produto está descrito em v1.0 prevista para dezembro/2026.

Premissas de leitura

• Os requisitos abaixo descrevem capacidades de serviço e cálculo.
• Eles não devem ser interpretados como requisitos de tela, cadastro operacional ou administração funcional do sistema.
• Tudo o que depender de interface gráfica, manutenção dinâmica de parâmetros ou fluxo amplo de gestão de processos fica fora desta versão.

Diagramas de sequência

Os diagramas abaixo descrevem, em alto nível, as principais interações esperadas para execução dos requisitos funcionais da v1.0. Eles devem ser lidos como referência de comportamento entre componentes, sem impor nomes finais de serviços, classes ou endpoints.

Recepção e validação da solicitação

Requisitos relacionados: RF-V1-001, RF-V1-002, RF-V1-003, RF-V1-004, RF-V1-014.

sequenceDiagram
    autonumber
    actor Consumidor as Sistema consumidor
    participant API as API SSDOi/ANA
    participant Validador as Serviço de validação
    participant Geo as Serviço geoespacial
    participant Parametros as Parâmetros fixos da v1.0
    participant Auditoria as Trilha de execução

    Consumidor->>API: Envia solicitação de avaliação
    API->>Auditoria: Registra recebimento da solicitação
    API->>Validador: Valida contrato e dados mínimos
    alt Dados mínimos inválidos
        Validador-->>API: Retorna inconsistências
        API->>Auditoria: Registra rejeição
        API-->>Consumidor: Retorna rejeição estruturada
    else Dados mínimos válidos
        Validador-->>API: Confirma solicitação válida
        API->>Geo: Localiza interferência por coordenadas
        Geo-->>API: Retorna trecho hidrográfico ou zona
        API->>Parametros: Recupera parâmetros embarcados
        Parametros-->>API: Retorna identificação da parametrização
        API->>Auditoria: Registra execução aceita
        API-->>Consumidor: Retorna identificador da execução
    end

Figura 1. Sequência de recepção e validação da solicitação.

Avaliação superficial automática

Requisitos relacionados: RF-V1-005, RF-V1-006, RF-V1-007, RF-V1-008, RF-V1-012, RF-V1-014.

sequenceDiagram
    autonumber
    participant API as API SSDOi/ANA
    participant Motor as Motor de avaliação superficial
    participant BHO as Base BHO v6
    participant SNISB as Serviço SNISB
    participant Auditoria as Trilha de execução
    participant Resultado as Resultado técnico

    API->>Motor: Solicita avaliação superficial
    Motor->>BHO: Consulta trecho e topologia hidrográfica
    BHO-->>Motor: Retorna trecho, montante, jusante e atributos
    Motor->>Motor: Calcula demanda incidente
    Motor->>Motor: Propaga impacto à jusante
    opt Trecho influenciado por reservatório
        Motor->>SNISB: Consulta dados de reservatórios aplicáveis
        SNISB-->>Motor: Retorna dados disponíveis ou falha estruturada
        Motor->>Motor: Ajusta cálculo quando houver dado aplicável
    end
    Motor->>Resultado: Consolida disponibilidade e indicadores
    Motor->>Auditoria: Registra bases, parâmetros e eventos relevantes
    Resultado-->>API: Retorna resultado superficial estruturado

Figura 2. Sequência de avaliação superficial automática.

Integrações com CNARH e SNISB

Requisitos relacionados: RF-V1-009, RF-V1-010, RF-V1-012, RF-V1-014.

sequenceDiagram
    autonumber
    participant Motor as Motor de avaliação
    participant Integracao as Serviço de integração
    participant CNARH as CNARH
    participant SNISB as SNISB
    participant Auditoria as Trilha de execução

    Motor->>Integracao: Solicita dados externos necessários
    par Dados de usuários e usos
        Integracao->>CNARH: Consulta dados do cadastro
        CNARH-->>Integracao: Retorna dados ou erro de comunicação
    and Dados de reservatórios
        Integracao->>SNISB: Consulta dados de barragens e reservatórios
        SNISB-->>Integracao: Retorna dados ou erro de comunicação
    end
    alt Integração concluída
        Integracao->>Auditoria: Registra origem e dados utilizados
        Integracao-->>Motor: Retorna dados externos estruturados
    else Falha de integração
        Integracao->>Auditoria: Registra falha, origem e motivo
        Integracao-->>Motor: Retorna erro estruturado de integração
    end

Figura 3. Sequência de integração com CNARH e SNISB.

Avaliação subterrânea simplificada por zona

Requisitos relacionados: RF-V1-003, RF-V1-004, RF-V1-005, RF-V1-011, RF-V1-012, RF-V1-014.

sequenceDiagram
    autonumber
    participant API as API SSDOi/ANA
    participant Geo as Serviço geoespacial
    participant Motor as Motor de avaliação subterrânea
    participant Zonas as Base de zonas de balanço
    participant Parametros as Parâmetros fixos da v1.0
    participant Auditoria as Trilha de execução

    API->>Geo: Solicita localização da interferência subterrânea
    Geo->>Zonas: Identifica zona correspondente às coordenadas
    alt Zona não encontrada
        Zonas-->>Geo: Informa ausência de zona aplicável
        Geo-->>API: Retorna solicitação não avaliável
        API->>Auditoria: Registra rejeição espacial
    else Zona encontrada
        Zonas-->>Geo: Retorna zona de balanço
        Geo-->>API: Retorna zona associada
        API->>Parametros: Recupera disponibilidade e parâmetros da zona
        Parametros-->>API: Retorna parâmetros aplicáveis
        API->>Motor: Solicita balanço subterrâneo simplificado
        Motor->>Motor: Calcula demanda, disponibilidade e saldo
        Motor->>Auditoria: Registra parâmetros e resultado
        Motor-->>API: Retorna resultado subterrâneo estruturado
    end

Figura 4. Sequência de avaliação subterrânea simplificada por zona.

Consulta de resultado e rastreabilidade

Requisitos relacionados: RF-V1-012, RF-V1-013, RF-V1-014.

sequenceDiagram
    autonumber
    actor Consumidor as Sistema consumidor
    participant API as API SSDOi/ANA
    participant Resultado as Repositório de resultados
    participant Auditoria as Trilha de execução

    Consumidor->>API: Consulta resultado por identificador
    API->>Resultado: Recupera resultado técnico da execução
    API->>Auditoria: Recupera parâmetros, bases e eventos registrados
    alt Execução encontrada
        Resultado-->>API: Retorna resultado técnico
        Auditoria-->>API: Retorna rastreabilidade mínima
        API-->>Consumidor: Retorna resposta estruturada de consulta
    else Execução inexistente
        Resultado-->>API: Informa ausência de resultado
        API-->>Consumidor: Retorna erro estruturado de consulta
    end

Figura 5. Sequência de consulta de resultado e rastreabilidade.

Requisitos funcionais da v1.0

RF-V1-001 Receber solicitação para avaliação automática

• Prioridade: Obrigatório
• Descrição: o sistema deve receber uma solicitação de análise hídrica por interface de serviço, contrato de integração ou mecanismo equivalente sem interface gráfica.
• Regras de negócio aplicáveis: — (requisito operacional de recepção).
• Entradas mínimas:
  • identificador do processo;
  • tipo de análise;
  • interferência de uso;
  • coordenadas geográficas;
  • regime temporal;
  • dados complementares exigidos pelo cálculo.
• Regras:
  • a entrada deve obedecer a contrato estruturado e validável;
  • a recepção da solicitação não pressupõe tela de cadastro;
  • a execução deve gerar identificador interno da avaliação.
• Saídas:
  • solicitação aceita para processamento;
  • identificador da execução;
  • registro do recebimento.

RF-V1-002 Validar dados mínimos da solicitação

• Prioridade: Obrigatório
• Descrição: o sistema deve validar a presença e a consistência dos dados mínimos exigidos para a avaliação automática.
• Regras de negócio aplicáveis: — (requisito operacional de validação de entrada).
• Entradas mínimas:
  • payload da solicitação;
  • regras mínimas da versão.
• Regras:
  • o identificador do processo deve ser obrigatório;
  • a classificação da interferência deve ser obrigatória;
  • a solicitação deve ser rejeitada quando faltar dado essencial ao cálculo;
  • a rejeição deve devolver motivo explícito.
• Saídas:
  • solicitação validada; ou
  • rejeição estruturada com justificativa.

RF-V1-003 Validar georreferenciamento e localizar a interferência

• Prioridade: Obrigatório
• Descrição: o sistema deve validar as coordenadas da solicitação e localizar a interferência na unidade espacial aplicável ao cálculo.
• Regras de negócio aplicáveis: RN-SUP-001 (a vazão de referência por trecho depende da localização correta na BHO), RN-SUB-001 (o balanço subterrâneo depende da identificação da zona).
• Entradas mínimas:
  • latitude;
  • longitude;
  • base espacial carregada.
• Regras:
  • coordenadas inválidas devem ser rejeitadas;
  • para análise superficial, o sistema deve localizar a interferência na BHO v6;
  • para análise subterrânea, o sistema deve localizar a zona correspondente;
  • a unidade espacial derivada deve constar do resultado.
• Saídas:
  • localização espacial validada;
  • trecho hidrográfico ou zona associado à solicitação.

RF-V1-004 Aplicar parametrização fixa da versão

• Prioridade: Obrigatório
• Descrição: o sistema deve aplicar o conjunto de parâmetros matemáticos e operacionais embarcado no código da versão, sem parametrização dinâmica ou administrativa. Os parâmetros podem variar conforme a unidade territorial aplicável (bacia, estado, zona, contexto regulatório), mas o conjunto completo de tabelas é fixo na v1.0.
• Regras de negócio aplicáveis: RN-PAR-001 (parâmetros vinculados a unidade territorial), RN-PAR-002 (parametrização fixa em código na v1.0).
• Entradas mínimas:
  • solicitação validada;
  • unidade territorial derivada da localização da interferência;
  • parâmetros embarcados na v1.0.
• Regras:
  • não deve haver seleção manual de conjunto de parâmetros por usuário final;
  • o cálculo deve usar apenas os parâmetros homologados para a v1.0;
  • quando houver parâmetro específico para a unidade territorial, ele prevalece sobre o parâmetro padrão da versão;
  • os parâmetros efetivamente aplicados devem ser identificáveis no resultado ou na trilha de execução, inclusive a unidade territorial considerada.
• Saídas:
  • conjunto de parâmetros efetivamente aplicado na avaliação, qualificado pela unidade territorial.

RF-V1-005 Calcular demanda bruta e consumptiva da solicitação

• Prioridade: Obrigatório
• Descrição: o sistema deve calcular, a partir dos dados de uso informados, a demanda bruta (volume captado do corpo d'água) e a demanda consumptiva (volume bruto descontado o retorno) da solicitação. A demanda consumptiva é a vazão utilizada na propagação à jusante e no balanço acumulado.
• Regras de negócio aplicáveis: RN-SUP-004 (distinção entre demanda bruta e consumptiva), RN-SUP-005 (composição temporal da demanda).
• Entradas mínimas:
  • tipo de interferência e finalidade de uso;
  • regime temporal declarado (anual ou mensal);
  • vazão, volume ou parâmetros equivalentes exigidos pela finalidade;
  • coeficiente de retorno declarado, quando informado.
• Regras:
  • o cálculo deve considerar a semântica do tipo de uso e da finalidade informados;
  • a demanda deve ser compatível com o regime declarado, mensal ou anual;
  • quando o coeficiente de retorno não for declarado, deve ser adotado o coeficiente padrão definido por parâmetro para a finalidade de uso;
  • pleitos com declaração apenas anual adotam distribuição uniforme ao longo dos meses;
  • inconsistências de entrada devem impedir cálculo silencioso.
• Saídas:
  • demanda bruta calculada, em escala mensal e/ou anual;
  • demanda consumptiva calculada, em escala mensal e/ou anual;
  • coeficiente de retorno efetivamente aplicado.

RF-V1-006 Executar avaliação superficial automática com BHO v6

• Prioridade: Obrigatório
• Descrição: o sistema deve executar a avaliação automática da disponibilidade hídrica superficial usando a BHO v6 como base hidrográfica de referência. A avaliação calcula, para o trecho da interferência e para a cadeia de trechos à jusante, o índice de comprometimento hídrico e a classificação disponível / indisponível para o novo uso.
• Regras de negócio aplicáveis: RN-SUP-001 (vazão de referência por trecho), RN-SUP-002 (limite outorgável por trecho), RN-SUP-003 (balanço de demanda no trecho), RN-IND-001 (indisponibilidade por comprometimento).
• Entradas mínimas:
  • solicitação superficial validada;
  • trecho hidrográfico identificado;
  • bases de referência carregadas;
  • parâmetros aplicáveis à unidade territorial.
• Regras:
  • a análise deve identificar o trecho afetado e a cadeia topológica à jusante aplicável;
  • para cada trecho avaliado, o sistema deve determinar a vazão de referência a partir da BHO v6 e o limite outorgável correspondente, definido como uma fração da vazão de referência parametrizada para a unidade territorial;
  • o cálculo deve produzir o índice de comprometimento do trecho como relação entre a soma das demandas (existentes mais a pleiteada) e o limite outorgável;
  • o trecho é considerado indisponível para o novo uso quando o índice de comprometimento resultante ultrapassa o limite outorgável; do contrário, é considerado disponível;
  • a análise deve usar a base oficial adotada para a v1.0.
• Saídas:
  • resultado técnico estruturado da avaliação superficial, incluindo:
    • vazão de referência considerada por trecho;
    • limite outorgável considerado por trecho;
    • soma de demandas existentes e demanda pleiteada por trecho;
    • índice de comprometimento por trecho;
    • classificação disponível / indisponível por trecho;
    • classificação consolidada do pleito.

RF-V1-007 Propagar impacto superficial à jusante

• Prioridade: Obrigatório
• Descrição: o sistema deve refletir o impacto consumptivo da nova solicitação ao longo da rede hidrográfica à jusante, segundo a topologia da BHO, até alcançar trecho terminal ou um ponto de interrupção definido pela topologia.
• Regras de negócio aplicáveis: RN-PROP-001 (propagação à jusante), RN-PROP-002 (encerramento da propagação), RN-PROP-003 (acumulação de impactos no trecho).
• Entradas mínimas:
  • trecho inicial da interferência;
  • demanda consumptiva da solicitação;
  • topologia hidrográfica;
  • vazão consumptiva já considerada em cada trecho à jusante.
• Regras:
  • a propagação deve seguir a conectividade da rede hidrográfica;
  • o cálculo deve usar a demanda consumptiva, e não a demanda bruta, no encadeamento à jusante;
  • o impacto da nova solicitação no balanço de cada trecho deve somar-se aos impactos das captações já consideradas no mesmo trecho;
  • a propagação termina ao alcançar trecho terminal ou ponto de interrupção definido pela topologia da BHO;
  • o resultado deve ser compatível com a unidade territorial e hidrológica de cálculo adotada.
• Saídas:
  • conjunto finito de trechos impactados;
  • efeitos propagados da solicitação, expressos como redução de vazão disponível por trecho.

RF-V1-008 Considerar reservatórios regularizadores no cálculo superficial

• Prioridade: Obrigatório
• Descrição: o sistema deve considerar, quando aplicável, o efeito de reservatórios regularizadores na avaliação superficial. A análise considera apenas reservatórios catalogados em sistemas institucionais oficiais, em particular o SNISB na v1.0.
• Regras de negócio aplicáveis: RN-BAR-001 (interceptação por reservatório), RN-BAR-002 (cadastro institucional de reservatórios).
• Entradas mínimas:
  • rede hidrográfica afetada;
  • dados de reservatórios acessíveis;
  • dados necessários do SNISB.
• Regras:
  • o uso de reservatórios deve seguir os dados externos disponíveis para a execução;
  • a consideração de reservatórios deve ser rastreável;
  • ausência de dado necessário deve produzir tratamento explícito.
• Saídas:
  • resultado superficial ajustado pela presença de reservatórios, quando aplicável.

RF-V1-009 Integrar com serviços do CNARH

• Prioridade: Obrigatório
• Descrição: o sistema deve interoperar com serviços do CNARH para obtenção e/ou envio dos dados necessários ao fluxo de análise da v1.0.
• Regras de negócio aplicáveis: — (requisito operacional de integração; apoia o conjunto de demandas existentes consumido pelas regras de balanço superficial e subterrâneo).
• Entradas mínimas:
  • identificadores e dados de integração definidos para a operação;
  • parâmetros de autenticação e comunicação.
• Regras:
  • a integração deve ocorrer sem dependência de interface gráfica;
  • falhas de comunicação devem ser tratadas de forma explícita;
  • a origem dos dados externos deve ser identificável.
• Saídas:
  • dados obtidos do CNARH; e/ou
  • resultado de interoperabilidade executada.

RF-V1-010 Integrar com serviços do SNISB

• Prioridade: Obrigatório
• Descrição: o sistema deve interoperar com serviços do SNISB para acesso aos dados de reservatórios necessários ao cálculo da v1.0.
• Regras de negócio aplicáveis: RN-BAR-002 (cadastro institucional de reservatórios).
• Entradas mínimas:
  • identificadores e parâmetros de acesso ao serviço;
  • contexto da análise superficial.
• Regras:
  • a integração deve fornecer dados utilizáveis no cálculo;
  • falhas ou indisponibilidade do serviço devem ser sinalizadas;
  • o uso de informação externa deve ser auditável.
• Saídas:
  • dados de reservatório recuperados e associados à execução; ou
  • erro estruturado de integração.

RF-V1-011 Executar balanço subterrâneo simplificado por zona

• Prioridade: Obrigatório
• Descrição: o sistema deve executar avaliação subterrânea simplificada por zona, conforme o recorte previsto para a v1.0. A avaliação calcula, para a zona em que está localizada a interferência subterrânea, o índice de comprometimento e a classificação disponível / indisponível para o novo uso.
• Regras de negócio aplicáveis: RN-SUB-001 (balanço por zona subterrânea), RN-SUB-002 (volume outorgável por zona), RN-IND-001 (indisponibilidade por comprometimento).
• Entradas mínimas:
  • solicitação subterrânea localizada;
  • zona correspondente;
  • volume explotável configurado para a zona;
  • fração outorgável da zona, definida em parâmetro;
  • demandas subterrâneas existentes consideradas na zona.
• Regras:
  • a v1.0 deve usar abordagem agregada por zona, sem análise de interferência entre poços;
  • o volume outorgável da zona é uma fração do volume explotável, definida em parâmetro associado à zona;
  • o índice de comprometimento da zona deve resultar da relação entre a soma das demandas subterrâneas (existentes mais a pleiteada) e o volume outorgável da zona;
  • a zona é considerada indisponível para o novo uso quando o índice de comprometimento resultante ultrapassa o volume outorgável; do contrário, é considerada disponível.
• Saídas:
  • resultado subterrâneo estruturado por zona, incluindo:
    • volume explotável e fração outorgável considerados;
    • soma de demandas existentes e demanda pleiteada;
    • índice de comprometimento da zona;
    • classificação disponível / indisponível da zona.

RF-V1-012 Produzir resultado técnico estruturado da avaliação

• Prioridade: Obrigatório
• Descrição: o sistema deve devolver um resultado técnico estruturado, independente de interface gráfica, para cada solicitação processada. O resultado deve declarar explicitamente a classificação disponível, indisponível ou indisponibilidade técnica por falta de informação do pleito.
• Regras de negócio aplicáveis: RN-IND-001 (indisponibilidade por comprometimento), RN-IND-002 (indisponibilidade por falta de informação).
• Entradas mínimas:
  • dados de entrada da solicitação;
  • resultados do cálculo;
  • parâmetros aplicados;
  • insumos consultados durante a análise.
• Regras:
  • o resultado deve conter dados suficientes para auditoria técnica;
  • o resultado deve informar se a análise executada foi superficial, subterrânea ou ambas;
  • o resultado deve incluir a classificação consolidada do pleito: disponível, indisponível ou indisponibilidade técnica por falta de informação;
  • quando o resultado for indisponibilidade técnica por falta de informação, o motivo deve ser registrado de forma explícita (insumo ausente, dado fora de padrão, zona sem balanço definido, trecho sem vazão de referência, ou equivalente);
  • o resultado deve poder ser serializado e consumido por outros sistemas.
• Saídas:
  • objeto estruturado de resultado da avaliação, contendo a classificação consolidada e, quando aplicável, o motivo da indisponibilidade técnica.

RF-V1-013 Expor resultado e rastreabilidade por serviço

• Prioridade: Obrigatório
• Descrição: o sistema deve disponibilizar, por serviço ou mecanismo equivalente sem interface gráfica, o resultado da avaliação e a rastreabilidade mínima da execução.
• Regras de negócio aplicáveis: — (requisito operacional de exposição do resultado).
• Entradas mínimas:
  • identificador da execução ou da solicitação.
• Regras:
  • o retorno deve incluir os dados de entrada relevantes, os parâmetros fixos aplicados e o resultado produzido;
  • o contrato de saída deve ser estável para integração;
  • a consulta não pressupõe tela de listagem operacional.
• Saídas:
  • resposta estruturada de consulta do resultado.

RF-V1-014 Registrar trilha mínima de execução

• Prioridade: Obrigatório
• Descrição: o sistema deve registrar trilha mínima de execução suficiente para auditoria técnica e reprocessamento analítico.
• Regras de negócio aplicáveis: RN-IND-002 (registro do motivo da indisponibilidade técnica por falta de informação).
• Entradas mínimas:
  • dados da solicitação;
  • parâmetros aplicados;
  • eventos relevantes da execução.
• Regras:
  • a trilha deve permitir identificar a base de referência utilizada;
  • deve ser possível associar resultado, parâmetros e entrada processada;
  • falhas relevantes também devem ser registradas.
• Saídas:
  • registro de execução associado ao resultado.

Requisitos explicitamente fora do recorte da v1.0

Os itens abaixo foram retirados do detalhamento da v1.0 porque extrapolam o recorte da primeira entrega:

• cadastro manual de pedidos por interface;
• alteração manual de pedidos;
• listagem operacional com filtros;
• importação manual em lote por tela;
• manutenção de catálogos por usuário;
• parametrização dinâmica por interface;
• motor qualitativo de efluentes;
• métodos Theis e Hunt;
• módulos completos de DRDH, OGP e obras hídricas.