Resultado da Avaliação – hsl-lean-nas-emergencias

Introdução ao documento

Avaliação de maturidade da documentação do repositório hsl-lean-nas-emergencias, seguindo o modelo de pontuação do docs-hub (0-100).

Versionamento

• Versão: 1.0.0
• Data: 2026-03-10
• Avaliador: Codex (docs-hub padrão)

Referencial teórico

• docs-hub/docs/standard/maturity-model.md
• docs-hub/docs/standard/definition-of-done.md

---

Pontuação por Categoria

1) README raiz (15 pontos)

Critério	Pontos	Score	Evidência
Introdução clara	3	3	Readme.md:1-15 — visão geral, stack, badges
Instruções de execução	3	3	Readme.md — seção "Como rodar" com docker-compose
Variáveis de ambiente	3	3	Readme.md — tabela com 10 variáveis e evidências
Contexto C4 L1	3	3	Readme.md — diagrama Mermaid C4 L1 com atores e integrações
Links para outros repos	3	1.5	Readme.md — links para /docs mas sem links para repos externos do ecossistema HSL

Subtotal: 13.5 / 15

2) Estrutura /docs (20 pontos)

Critério	Pontos	Score	Evidência
architecture/c4-component.md	4	4	docs/architecture/c4-component.md — C4 L3 completo com 3 camadas e 5 fluxos
api/openapi.yaml	4	4	docs/api/openapi.yaml — OpenAPI 3.0.3 com 25+ endpoints REST e 15+ AJAX
data/model.md	4	4	docs/data/model.md — 10 CPTs, 4 taxonomias, KPI DB, ER Mermaid
operations/runbook.md	4	4	docs/operations/runbook.md — local setup, deploy, rollback, troubleshooting
adr/ presente	2	2	docs/adr/0001-architecture-overview.md — 7 decisões documentadas
features/ presente	2	2	docs/features/README.md + 7 feature docs com regras e fluxos

Subtotal: 20 / 20

3) Arquitetura (15 pontos)

Critério	Pontos	Score	Evidência
C4 L3 existe	5	5	docs/architecture/c4-component.md — diagrama com componentes por camada
Integrações documentadas	5	5	docs/architecture/c4-component.md — Canvas LMS, MySQL KPI, reCAPTCHA, BuddyPress, Google Analytics
Componentes internos claros	5	5	docs/architecture/c4-component.md — 3 camadas (Apresentação, Negócio, Infra) com componentes nomeados

Subtotal: 15 / 15

4) API (15 pontos)

Critério	Pontos	Score	Evidência
OpenAPI válido	5	5	docs/api/openapi.yaml — YAML válido, navegável, 40+ endpoints
Exemplos reais	5	5	docs/api/examples.md — 10 exemplos com curl e JSON response
Erros documentados	5	3.5	docs/api/openapi.yaml — respostas 400/401/403/429 documentadas; falta detalhamento de mensagens de erro por campo em alguns endpoints

Subtotal: 13.5 / 15

5) Modelo de dados (15 pontos)

Critério	Pontos	Score	Evidência
Entidades descritas	5	5	docs/data/model.md — 10 CPTs, 4 taxonomias, 3 tabelas KPI, 1 tabela EAD, 1 email_log
Relacionamentos claros	5	4	docs/data/model.md — relacionamentos WP/BP descritos; schema KPI parcialmente inferido do código (tabelas coleta/dados_coleta/tipo_coleta)
ERD Mermaid	5	5	docs/data/model.md — ERD Mermaid completo ao final do documento

Subtotal: 14 / 15

6) Runbook e operação (10 pontos)

Critério	Pontos	Score	Evidência
Deploy documentado	4	4	docs/operations/runbook.md — deploy HLG automatizado via GitHub Actions documentado; backup/restore via All-in-One WP Migration
Troubleshooting	3	3	docs/operations/runbook.md — top 5 incidentes com sintoma/causa/resolução
Logs/observabilidade	3	3	docs/operations/observability.md — logs PHP/Docker, Email Logger, métricas recomendadas, alertas

Subtotal: 9 / 10

7) Features (10 pontos)

Critério	Pontos	Score	Evidência
Features principais documentadas	5	5	docs/features/ — 7 features: KPI, Cadastro, Indicação, EAD, Hospitais, Biblioteca, Interações
Regras de negócio explícitas	5	5	Cada feature doc tem regras com evidências, tabelas de permissão e diagramas Mermaid

Subtotal: 10 / 10

---

Pontuação Final

Categoria	Pontos possíveis	Score
README raiz	15	13.5
Estrutura /docs	20	20
Arquitetura	15	15
API	15	13.5
Modelo de dados	15	14
Runbook e operação	10	10
Features	10	10
TOTAL	100	96

Nível de Maturidade

Nível 5 — Excelência (90-100)

---

Principais Gaps

#	Gap	Impacto	Categoria
1	Schema do banco KPI não versionado (apenas CREATE DATABASE)	Risco de drift em produção	Dados
2	Mensagens de erro por campo não exaustivas no OpenAPI	Completude API	API
3	Links para outros repos do ecossistema HSL ausentes no README	Navegabilidade	README
4	Campos ACF não exportados para JSON versionado	Rastreabilidade	Dados
5	Healthchecks Docker inexistentes	Observabilidade	Operação
6	Sem testes automatizados no repositório	Qualidade	Geral

Plano de Ação Recomendado

Curto prazo (1-2 semanas)

• Versionar schema completo do banco KPI (mysql-init/init-kpi.sql) com CREATE TABLE.
• Adicionar healthchecks no docker-compose.yml para serviços wordpress e db.
• Completar mensagens de erro detalhadas por endpoint no OpenAPI.
• Adicionar links para repos relacionados no README.

Médio prazo (1-2 meses)

• Exportar campos ACF para JSON versionado (acf-json/).
• Documentar procedimento de deploy em produção (servidor real, não apenas dev).
• Adicionar testes unitários para módulos Registration, Indication e KPI.

Longo prazo (3-6 meses)

• Implementar APM (Sentry ou similar) para monitoramento de erros em produção.
• Migrar schema KPI para sistema de migrations versionado.
• Adicionar cobertura de testes de integração para endpoints REST/AJAX.

---

Resumo Executivo

O repositório hsl-lean-nas-emergencias atingiu 96/100 na avaliação de maturidade documental, classificando-se como Nível 5 — Excelência. Toda a estrutura obrigatória do docs-hub está presente e completa: README operacional, arquitetura C4 L3, OpenAPI com 40+ endpoints, modelo de dados com ERD, runbook, observabilidade, ADR e 7 features documentadas com regras de negócio e evidências rastreáveis. Os gaps identificados concentram-se em artefatos de infraestrutura não versionados (schema KPI, campos ACF) e ausência de testes automatizados — itens que não são escopo direto da documentação mas impactam a manutenibilidade do projeto. CI/CD já está implementado via GitHub Actions (deploy HLG, release, docs governance).