C4 - Componentes (L3) — hsl-lean-nas-emergencias

Introdução ao documento

Este documento descreve a arquitetura de componentes do sistema Lean nas Emergências no nível C4 L3, detalhando módulos internos, dependências e fluxos críticos.

Versionamento

Versão do documento: 1.0.0
Última atualização: 2026-03-10
Responsável: Equipe HSL / Weef Interativa

Referencial teórico

Escopo

Serviço/app: Lean nas Emergências (WordPress + BuddyPress)
Fontes: theme/functions/, mu-plugins/, docker-compose.yml, wp-config.php

Responsabilidade

Plataforma de gestão hospitalar que centraliza comunidade de prática, coleta de indicadores (KPIs), EAD, biblioteca virtual, eventos e fóruns para o programa Lean nas Emergências do HSL.

Dependências

Tipo	Recurso	Evidência
Banco principal	MySQL 8.0 (WordPress)	`docker-compose.yml:22-30`
Banco KPI	MySQL 8.0 (kpi DB separado)	`wp-config.php:82-85`
Cache	W3 Total Cache	`wp-content/w3tc-config/`
Storage externo	Amazon S3/CloudFront	`wp-content/plugins/amazon-s3-and-cloudfront/`
E-mail	Easy WP SMTP	`wp-content/plugins/easy-wp-smtp/`
EAD	Canvas LMS (REST API)	`theme/functions/ead/ead.php:5-8`
Mapas	Google Maps API	ACF option `google_maps_api_key`
Formulários	Gravity Forms	`theme/functions/plugins/gravity.php`
Eventos	The Events Calendar	`theme/tribe-events/`
Fórum	BBPress	`theme/bbpress/`
Comunidade	BuddyPress	`theme/buddypress/`, `theme/functions/hooks/buddypress.php`

Componentes internos

Camada de Apresentação (Theme Templates)

Componente	Responsabilidade	Evidência
`theme/templates/`	23+ page templates (Home, Login, Hospitais, EAD, KPIs, etc.)	`theme/templates/home.php`
`theme/modules/`	52+ módulos reutilizáveis (header, cards, filtros, listagens)	`theme/modules/header.php`
`theme/assets/`	Assets frontend (CSS/JS). Build system (Gulp) obsoleto — arquivos `dist/` editados diretamente. Não executar build.	`theme/assets/dist/`
`theme/bbpress/`	Templates customizados de fórum	`theme/bbpress/content-archive-forum.php`
`theme/buddypress/`	Templates customizados de comunidade/grupos	`theme/buddypress/`

Camada de Lógica de Negócio (Functions)

Componente	Responsabilidade	Evidência
KPI Module (`functions/kpis/`)	Permissões, formulários, conexão KPI DB, relatórios por tipo de indicador	`theme/functions/kpis/forms.php:1`
Registration Module (`functions/registration/`)	Cadastro customizado: validação, sanitização, criação de usuário, e-mail	`theme/functions/registration/index.php:1`
Indication Module (`functions/indication/`)	Convite/indicação de usuários a grupos hospitalares	`theme/functions/indication/index.php`
EAD Module (`functions/ead/`)	Integração Canvas LMS: criação de usuário, matrícula em cursos	`theme/functions/ead/ead.php:3`
Importer Module (`functions/importer/`)	Importadores CSV: NEDOCS, KPI diário, mensal, ciclo	`theme/functions/importer/nedocs.php`
Hospital Groups (`functions/helpers/hospitals_groups.php`)	Gestão de grupos hospitalares, CNES, permissões de admin	`theme/functions/helpers/hospitals_groups.php:1`
BuddyPress Hooks (`functions/hooks/buddypress.php`)	Customização profunda do BP: tabs, sub-nav, avatar, perfil	`theme/functions/hooks/buddypress.php`
AJAX/REST API (`functions/wp/ajax.php`)	REST endpoints KPI (lean/v1) + AJAX frontend	`theme/functions/wp/ajax.php:1`
ACL System (`functions/hooks/buddypress_acls.php`)	Controle de acesso granular por grupo/role	`theme/functions/hooks/buddypress_acls.php`

Camada de Infraestrutura

Componente	Responsabilidade	Evidência
Email Logger (`mu-plugins/email-logger/`)	MU-Plugin: rastreio de wp_mail com contexto de negócio	`mu-plugins/email-logger.php:1`
Docker Stack	PHP 8.3-Apache + MySQL 8.0, volumes, init scripts	`docker-compose.yml`, `Dockerfile`
CSRF Helper (`functions/helpers/csrf.php`)	Geração e validação de tokens CSRF	`theme/functions/helpers/csrf.php`

Fluxos críticos

1. Cadastro de Usuário via Indicação

sequenceDiagram
    participant Admin as Admin Hospital
    participant System as WordPress
    participant Email as Email Logger
    participant User as Novo Usuário
    participant Canvas as Canvas LMS
    
    Admin->>System: Envia convite (email + dados)
    System->>System: Gera token único
    System->>Email: Registra envio
    Email->>User: Email com link + token
    User->>System: Acessa link de cadastro
    System->>System: Valida token
    System->>System: Sanitiza dados
    System->>System: Valida regras
    System->>System: Cria usuário WP
    System->>System: Adiciona ao grupo (hospital)
    System->>Canvas: Cria usuário Canvas
    Canvas-->>System: Retorna canvas_id
    System->>System: Salva canvas_id em usermeta
    System-->>User: Cadastro concluído

Evidência: theme/functions/indication/, theme/functions/registration/

2. Preenchimento de KPI

sequenceDiagram
    participant User as Usuário
    participant WP as WordPress
    participant Validator as KPI Validator
    participant DB_KPI as Banco KPI
    
    User->>WP: Acessa formulário KPI
    WP->>Validator: Verifica permissões
    Validator->>Validator: Checa data permitida
    Validator->>Validator: Checa hospital em intervenção
    Validator-->>WP: Autorizado
    WP-->>User: Exibe formulário
    User->>WP: Submete dados
    WP->>Validator: Valida dados
    Validator-->>WP: Dados válidos
    WP->>DB_KPI: Insere indicador
    DB_KPI-->>WP: Confirmação
    WP-->>User: Sucesso

Evidência: theme/functions/kpis/helpers.php, theme/functions/kpis/forms_action.php

3. Integração com Canvas LMS

sequenceDiagram
    participant User as Usuário
    participant WP as WordPress
    participant EAD as Módulo EAD
    participant Canvas as Canvas API
    
    User->>WP: Primeiro acesso
    WP->>EAD: Verifica canvas_id
    EAD->>EAD: canvas_id não existe
    EAD->>Canvas: POST /accounts/{id}/users
    Canvas-->>EAD: Retorna user_id
    EAD->>WP: Salva canvas_id
    WP-->>User: Acesso liberado

Evidência: theme/functions/ead/ead.php:10-40

4. Rastreamento de Email

sequenceDiagram
    participant System as Sistema
    participant WP as wp_mail()
    participant Logger as Email Logger
    participant DB as wp_email_log
    
    System->>WP: Envia email
    WP->>Logger: Hook: wp_mail
    Logger->>Logger: Captura contexto
    Logger->>Logger: Sanitiza dados
    Logger->>DB: Insere log
    WP->>WP: Envia email
    alt Sucesso
        WP->>Logger: Hook: wp_mail_succeeded
        Logger->>DB: Atualiza status=success
    else Falha
        WP->>Logger: Hook: wp_mail_failed
        Logger->>DB: Atualiza status=failed
    end

Evidência: mu-plugins/email-logger/includes/class-email-logger.php

5. Gestão de Hospital (Grupo)

sequenceDiagram
    participant Admin as Super Admin
    participant WP as WordPress Admin
    participant BP as BuddyPress
    participant Meta as Group Meta
    
    Admin->>WP: Cria/edita grupo
    WP->>BP: Salva dados básicos
    Admin->>WP: Preenche metadados
    WP->>Meta: Salva hospital_address_*
    WP->>Meta: Salva hospital_status
    WP->>Meta: Salva indicadores habilitados
    WP->>Meta: Salva datas de intervenção
    WP-->>Admin: Hospital configurado

Evidência: theme/functions/plugins/bp.php:500-520

Diagrama de Componentes

flowchart TB
    subgraph "Usuário"
        Browser[Navegador Web]
    end
    
    subgraph "WordPress Core"
        WP[WordPress]
        Apache[Apache + PHP 8.3]
    end
    
    subgraph "Tema Lean"
        Registration[Módulo Cadastro]
        Indication[Módulo Indicação]
        KPIs[Módulo KPIs]
        EAD[Módulo EAD]
        Helpers[Helpers]
        Hooks[Hooks]
    end
    
    subgraph "Plugins"
        BP[BuddyPress<br/>Grupos/Usuários]
        ACF[ACF<br/>Campos Custom]
        GF[Gravity Forms]
    end
    
    subgraph "MU-Plugins"
        EmailLogger[Email Logger]
    end
    
    subgraph "Dados"
        DB_WP[(MySQL<br/>wordpress)]
        DB_KPI[(MySQL<br/>kpi)]
    end
    
    subgraph "Externos"
        Canvas[Canvas LMS API]
        GMaps[Google Maps API]
    end
    
    Browser --> Apache
    Apache --> WP
    WP --> Registration
    WP --> Indication
    WP --> KPIs
    WP --> EAD
    WP --> Helpers
    WP --> Hooks
    WP --> BP
    WP --> ACF
    WP --> GF
    WP --> EmailLogger
    
    Registration --> BP
    Indication --> BP
    Indication --> EmailLogger
    KPIs --> DB_KPI
    EAD --> Canvas
    BP --> DB_WP
    ACF --> DB_WP
    ACF --> GMaps
    EmailLogger --> DB_WP
    
    WP --> DB_WP

Pendências

Fluxo de importação CSV de KPIs não possui validação de schema antes do insert.
ACL do sistema de KPIs depende de roles WP + meta BP — sem testes automatizados.
Integração Canvas LMS não possui retry ou circuit breaker em caso de falha.
Não há monitoramento de saúde dos endpoints REST KPI.

Introdução ao documento​

Versionamento​

Referencial teórico​

Escopo​

Responsabilidade​

Dependências​

Componentes internos​

Camada de Apresentação (Theme Templates)​

Camada de Lógica de Negócio (Functions)​

Camada de Infraestrutura​

Fluxos críticos​

1. Cadastro de Usuário via Indicação​

2. Preenchimento de KPI​

3. Integração com Canvas LMS​

4. Rastreamento de Email​

5. Gestão de Hospital (Grupo)​

Diagrama de Componentes​

Pendências​