Documentação interna

Console Health Audit — visão geral

Mapa da arquitetura de informação, referência da API, busca global, provenance, visualizador de PDF, tiers de acesso e diretrizes mobile.

Referência da API

Endpoints do cartridge health-audit, agrupados por área e sem duplicatas. Base no navegador: /api/mycelia/v2/health-audit (proxy same-origin via BFF — nunca há host de API exposto no cliente).

41 endpoints.

Auditoria

POST
/pipeline/run
Dispara o pipeline de auditoria (ingestão + regras + glosa) a partir do XML TISS.
usado em /
POST
/audit/xml-glosa
Roda apenas a glosa do XML contra o contrato (sem reingerir regras).
usado em /
GET
/audit/runs
Lista execuções de auditoria (filtra por status de revisão e limite).
read-onlyusado em /review
GET
/audit/runs/{run_id}
Detalhe de uma execução: itens, glosas, snapshot e trilha de revisão (inspeção read-only).
read-onlyusado em /review
POST
/audit/runs/{run_id}/review
Submete decisões profissionais (disposição + justificativa) para uma execução.
rules-managementusado em /audit-trail
GET
/internal/review/queue
Fila interna de revisão pendente.
rules-managementinterno

Contratos

GET
/contracts
Catálogo público de contratos vigentes (visível conforme tenant).
read-onlyusado em /contractsalias: /internal/contracts
GET
/contracts/{ref}
Detalhe do contrato: limites de preço, regras estruturadas e documentos. Aceita CNPJ, ANS, contract_id ou relationship_key.
read-onlyusado em /contracts, /relationship/[ref]alias: /internal/contracts/{ref}
GET
/contracts/{ref}/documents
Lista documentos-fonte (PDF/XLSX/DOCX) do contrato.
read-onlyusado em /contracts, /relationship/[ref]
GET
/contracts/{ref}/documents/{filename}
Stream do binário do documento (PDF inline com Range; demais como download).
read-onlyusado em /contracts
GET
/contracts/{ref}/status
Estado de processamento/ingestão de um contrato.
read-only
POST
/internal/contracts
Cria ou atualiza um contrato (upsert de regras e limites de preço).
rules-managementinternousado em /contracts (ingestão)
PUT
/internal/contracts/{ref}
Atualiza um contrato existente.
rules-managementinterno
DELETE
/internal/contracts/{ref}
Remove um contrato.
admininterno
POST
/internal/contracts/ingest-bundle
Ingere um pacote (bundle) de documentos de contrato de uma vez.
rules-managementinterno

Regras

GET
/registry/rules
Registry canônico de regras (KB e glosa) com origem, família, escopo e modo.
read-onlyusado em /rules, /relationship/[ref]alias: /rules
GET
/registry/rules/{rule_id}
Detalhe de uma regra do registry.
read-onlyusado em /rules
GET
/registry/overrides
Lista overrides aplicados sobre regras do registry.
rules-managementinterno
POST
/registry/overrides
Cria um override de regra.
rules-managementinterno
DELETE
/registry/overrides/{override_id}
Remove um override de regra.
rules-managementinterno
POST
/rules/simulate
Simula o efeito de regras contra um conjunto de itens (sem persistir).
rules-managementinterno

TISS

GET
/tiss/protocolos
Lista protocolos TISS (status, guias, valores informado e glosado).
read-onlyusado em /relationship/[ref]
GET
/tiss/recursos
Lista recursos de glosa TISS (status, motivo, resposta).
read-onlyusado em /relationship/[ref]
GET
/tiss/stats
Métricas agregadas de protocolos e recursos.
read-onlyusado em /relationship/[ref]
GET
/tiss/demonstrativo/{protocolo}
Demonstrativo de análise de um protocolo.
read-only

TUSS

GET
/tuss/validate/{code}
Valida um código TUSS (existência, tabela, termo, vigência).
read-onlyusado em /relationship/[ref], /glosa
GET
/tuss/procedures
Busca procedimentos TUSS por termo.
read-onlyusado em /relationship/[ref], /glosa
GET
/tuss/opme
Busca OPME (órteses, próteses e materiais especiais).
read-onlyusado em busca ⌘K
GET
/tuss/medications
Busca medicamentos por termo.
read-onlyusado em busca ⌘K
GET
/tuss/stats
Contagens de procedimentos, OPME, medicamentos e CBO.
read-only

Conhecimento

POST
/sparql
Executa consulta SPARQL sobre o grafo de conhecimento (uso avançado).
read-onlyusado em /knowledge
GET
/knowledge/graph/{iri}
Vizinhança de um IRI no grafo (nós e arestas) para exploração guiada.
read-onlyusado em /knowledge
GET
/glosa/patterns
Padrões de glosa derivados por FCA (motivo, contagem, valor negado).
read-only
GET
/glosa/denial-rates
Taxas de negação por procedimento.
read-only

Ingestão

GET
/sentinel/raw-data/status
Estado da base de dados brutos (pronta/pendente, contagem de arquivos).
read-onlyusado em /ingest
POST
/sentinel/raw-data/sync
Sincroniza dados brutos a partir de um source_path.
rules-managementusado em /ingest
POST
/kb/ingest
Ingere documentos na base de conhecimento (job assíncrono).
rules-managementusado em /ingest
GET
/kb/ingest/{job_id}
Acompanha o status de um job de ingestão.
read-only
POST
/kb/rebuild-fca
Reconstrói a treliça FCA a partir dos dados de glosa (job assíncrono).
rules-managementinterno

Sistema

GET
/status
Status do cartridge e prontidão das dependências (ontologia, regras, contratos).
read-onlyusado em /ingest
GET
/evolution/stats
Métricas de evolução do cartridge.
admininterno

Arquitetura de informação

A navegação segue “spine + satélites”: o relacionamento Operadora ↔ Hospital é a espinha polimórfica do produto.

FluxoAuditoriaDisparar pipeline (manual ou lote) e ver resultado.FluxoIngestãoXML TISS, PDF de contrato e documentos hospitalares.FluxoRevisãoInspeção read-only das execuções: lista de runs, itens, glosas e provas.FluxoTrilha de auditoriaHistórico cronológico do relacionamento: auditorias, glosas e decisões com proveniência.RelacionamentoOperadora ↔ HospitalCatálogo de contratos vigentes e versões.RelacionamentoRelacionamento 360Visão única — aceita CNPJ, ANS, contract_id ou relationship_key.ReferênciaRegrasRegistry de regras (KB e glosa) com origem, família e modo.ReferênciaConhecimentoGrafo de conceitos induzidos (ontologia, FCA).ContaUsuários e acessosGestão de usuários, papéis e tiers.

Busca global (⌘K)

Atalho ⌘K (macOS) ou Ctrl+K (Windows/Linux). Resolve, em ordem:

CNPJ (com ou sem máscara) → relacionamento do prestador/operadora.
Registro ANS → relacionamento da operadora.
contract_id (UUID) → relacionamento do contrato.
relationship_key (OPER:<ans>::HOSP:<cnpj>) → relacionamento direto.
Nome (fuzzy) → matches em catálogo de contratos e regras.

Provenance e trilha de auditoria

Toda regra, preço extraído e finding preserva o caminho até o documento de origem.

Preços extraídos

source_filename
source_page
source_line
source_module
extracted_at

Chips inline em /contracts e no modal de detalhe. O visualizador navega até a página citada.

Regras

rule_iri
source_module
rule_family
certainty
application_mode
processing_pipeline

Escopo: contract_id, relationship_key, provider_cnpj, operator_cnpj, operator_ans_registration.

Findings de auditoria

glosa_code
rule_iri
source
evidence_chunk

Referenciam a regra que disparou a glosa e o trecho de evidência.

Visualizador de PDF

ContractDocumentViewer usa <iframe> nativo (sem pdf.js nem react-pdf). A rota /contracts/[ref]/documents expõe o binário com Content-Type correto e suporta Range requests.

Tipo	Comportamento
.pdf	Renderiza no <iframe> com toolbar nativa. ?page=N navega direto.
.xlsx, .xls, .csv	Download direto + link 'abrir' no app local.
.docx, .doc	Download direto.
.xml (TISS)	Viewer monospaced; truncado para arquivos >1MB.
.png, .jpg, .jpeg	<img> inline.

RBAC: tiers do console

Verificação canônica é server-side no mycelia-api — a UI esconde affordances que o backend recusaria. Em client, use useAuth() + hasPermission(role, resource, action).

Tier (UI)	Papel backend	Permissões
admin	admin	Tudo: ingestão, regras, usuários, configurações.
rules-management	analyst ou auditor_medico	Leitura + escrita em rules; leitura no resto.
read-only	viewer	Apenas leitura.

Mobile

Sidebar colapsa em viewport <lg (botão hamburger no AppHeader).
Paleta ⌘K acessível via botão dedicado no header (não depende de atalho de teclado).
Chips de filtro sticky e horizontalmente roláveis em larguras estreitas.
Tap targets de ação primária ≥44×44px; secundários ≥32px.
Layouts em CSS grid com minmax(); sem scroll horizontal exceto em .custom-scrollbar.
Tabelas viram cards empilhados em <md e voltam a tabela em ≥md.
framer-motion usado com parcimônia para preservar fluidez.

Conteúdo completo (deploy, scripts, diagnóstico): README.md do projeto.