62 KiB
Formação Técnica, Competências e Investimento em Educação
O diagnóstico inicial abaixo foi complementado pelo relatório de execução, que identifica a implementação interna existente, as correcções verificadas e as lacunas por RF. A presença de código não resolve automaticamente B01–B08 nem aprova esta proposta.
Versão 0.1 — 26/09/2026 — Proposta. Nenhum artefacto deste pacote está aprovado para produção, homologação ou integração automática. Pedido de origem: anexo 1b36f6f0-93cf-49aa-9479-986a57bd18f4/Pasted text.txt. Os exemplos não activam funcionalidades nem alteram dados do portal.
1. Sumário executivo
O submódulo liga necessidades produtivas a respostas formativas e investimento educativo. Não é formação sobre o uso do portal. A unidade de análise é a procura de trabalhadores por ocupação, qualificação, território e período, apoiada por competências verificáveis e por oferta formativa cuja capacidade, calendário e situação institucional estejam documentados.
Percurso: projecto/cluster/corredor → procura de mão-de-obra → competências → lacunas → resposta formativa → oportunidade de investimento educativo → formação → inserção → monitoria.
O MVP proposto limita a activação a até três clusters e três corredores, projectos-piloto validados e dados institucionais autorizados. A arquitectura permite expansão. Os cadastros documentais existentes não constituem aprovação dos pilotos. Dados de procura, instituições, cursos, custos, acreditações, capacidade e resultados: Pendente de levantamento e validação pela entidade competente.
O pacote inclui esta especificação, catálogo de 44 entidades, matrizes RF/RNF e indicadores, contrato OpenAPI proposto, proposta de migração, exemplos de cálculo e testes de especificação. Estes últimos verificam regras ilustrativas, não a implementação do submódulo no portal.
2. Escopo, diagnóstico e decisões
2.1 Âmbito do MVP
Registar procura e oferta; versionar fontes; confrontar unidades comparáveis; rever lacunas; preparar oportunidades educativas; receber interesse com consentimento e encaminhamento assistido ao CRM; pesquisar e apresentar indicadores agregados e mapa autorizado; emitir sugestões assistivas sujeitas a revisão. Instituições seleccionadas e profissões críticas dependem do levantamento. Formação, financiamento executado, turmas, bolsas, estágios, inserção e retenção constituem a extensão F2, com desenho antecipado sem recolher já os respectivos dados pessoais.
Exclusões: acreditar, certificar, emitir diplomas, gerir integralmente a vida académica ou salários, seleccionar ou contratar automaticamente pessoas, conceder financiamento automaticamente, classificar publicamente instituições por algoritmo, produzir previsões vinculativas ou integrar instituições sem acordo.
2.2 Evidência do repositório e reutilização
| Componente | Evidência verificada | Decisão | Qualidade, dependência, risco e esforço |
|---|---|---|---|
| React/Inertia/Laravel | lockfiles: React 19.2.8, Inertia React 3.7.0, Laravel 13.30.1, Inertia Laravel 3.3.3, Fortify 1.39.0 | Conservar | Convenções confirmadas; criar funcionalidades no mesmo produto; esforço baixo de integração visual |
| PostgreSQL/PostGIS | Consulta local: PostgreSQL 17.11, PostGIS 3.6.2 | Conservar | Read-only nesta entrega; sem base paralela |
| Skills e Occupations | migration 2026_09_24_009000; zero registos em ambas |
Melhorar | Cadastros mínimos; faltam taxonomia, sinónimos, níveis e versões aprovadas; esforço médio |
| training_needs | project/occupation/skill/quantity/priority; zero registos | Melhorar por extensão compatível | Não equivale ainda a LabourDemand; não reinterpretar quantity como trabalhadores sem evidência; esforço alto |
| training_providers e courses | organization/provider; estados simples; zero registos | Conservar e estender | approved não significa acreditação; capacidades e decisões são lacunas funcionais |
| education_opportunities | course_id obrigatório, datas e capacity; zero registos | Conservar como oferta calendarizada | Não suporta centro novo sem curso. B02 impede substituir silenciosamente a semântica |
| Projectos, clusters e corredores | cadastros, ligações, carteira de 29 rascunhos e jornada implementados | Conservar | Reutilizar UUID; publicações e contexto não equivalem a pilotos institucionais aprovados |
| Autenticação e autorização | Fortify; gate manage-portal por emails verificados |
Melhorar | Não há mandato institucional por organização; não habilitar acreditação usando o gate actual |
| Documentos/consentimentos/auditoria | tabelas Shared, education_documents, PortalAudit | Conservar e completar | Existência de tabelas não demonstra cofre, antivírus, revogação granular ou retenção operacionais |
| CRM local e SuiteCRM | conversão assistida, cliente OAuth, outbox; CRM externo sem instalação acessível | Conservar transição | Sem escrita dupla; sincronização real bloqueada; esforço alto de homologação |
| API pública actual | routes/api.php: catálogo e interesse, throttling e contratos existentes |
Conservar | Sem OAuth/OIDC de acesso à API Education demonstrado; não trocar contratos públicos |
| GIS | geo_locations/geo_geometries, SRID 4326, validadores | Conservar e melhorar | Sem mapa institucional autorizado ou motor de rotas confirmado |
| Componentes a substituir/descontinuar | Nenhum demonstrado como dispensável | Nenhuma remoção | Evitar inventar dívida técnica ou destruir investimentos existentes |
Não foi encontrada pasta .git acessível na raiz durante o diagnóstico. Antes de código de integração: confirmar checkout/branch própria e revisão por pares. Esta entrega é documentação e exemplos isolados, sem migrations executáveis em database/migrations.
2.3 Bloqueios e pressupostos
| ID | Bloqueio / decisão necessária | Responsável proposto | Efeito |
|---|---|---|---|
| B01 | Pilotos, entidades competentes, fontes e mandatos não identificados | Patrocinador + Secretariado de Dados | Não activar nem publicar dados oficiais |
| B02 | Oferta calendarizada ≠ oportunidade de investimento educativo; decidir extensão do catálogo Opportunity e identidade UUID | Produto + Arquitectura | Apenas modelo/migration proposta; preservar course_id e contratos actuais |
| B03 | RBAC por organização, segregação e OAuth/OIDC Education não implementados | Arquitectura + Segurança | Endpoints e policies apenas propostos |
| B04 | SuiteCRM sem motor/instalação/OAuth operacional | Operações + responsável CRM | Captura local e desenho de outbox; sem sincronização declarada concluída |
| B05 | Base de tratamento, retenção, menores, partilha e supressão estatística não aprovadas | Responsável de dados + jurídico | Sem recolha de beneficiários; sem exportações pessoais |
| B06 | Taxonomias, conversões de níveis, cobertura e validade das fontes não aprovadas | Entidades competentes | Cálculos oficiais indisponíveis; casos sintéticos apenas |
| B07 | Fornecedor/modelo IA, fontes e métricas não aprovados | Comité de IA e Dados | IA desligada; não apresentar regras determinísticas como IA |
| B08 | Limiares operacionais, recursos, orçamento e pilotos de carga não aprovados | Produto + Operações | Metas RNF são propostas; não compromisso de disponibilidade |
Precedência: protecção de dados e limites institucionais; não destruição; compatibilidade; revisão humana; reversibilidade; MVP. Conflitos B01–B08 impedem código executável para os itens afectados. Nenhuma lei, autoridade, instituição ou classificação nacional é presumida neste documento.
3. Actores e responsabilidades
| Grupo | Actores | Responsabilidade |
|---|---|---|
| Procura | Promotor, empregador, coordenador de cluster/corredor | Declarar postos, competências, calendário, local, evidência e responsável |
| Oferta | Instituição, prestador, formador | Declarar programas, capacidade, recursos e limitações; formador não certifica por ser utilizador |
| Regulação | Tutela, acreditadora/certificadora competente | Confirmar decisões exclusivamente no mandato e escopo autorizados |
| Investimento | Investidor, financiador, fornecedor | Consultar fichas aprovadas; expressar interesse; assumir compromissos formalizados |
| Beneficiários | Formando, trabalhador, candidato | Controlar dados autorizados; consultar percurso próprio; contestar informação |
| Operação | Gestor, analista, administrador, auditor | Tramitar, calcular, operar e auditar com funções separadas |
| Governação | Patrocinador, Produto, comités, Secretariado | Aprovar escopo, fontes, arquitectura, critérios e passagem de fase |
| Público | Visitante | Ler apenas projecções publicadas e agregadas |
4. Arquitectura funcional
| Blocos | MVP e evolução | Reutilização |
|---|---|---|
| 1 Observatório; 2 Procura; 3 Ocupações; 4 Competências | F1: registo, taxonomias versionadas, consulta | skills, occupations, project/cluster/corridor |
| 5 Instituições; 6 Cursos; 7 Capacidade | F1: cadastro e evidências sem atribuir acreditação | training_providers, courses, organizations, documents |
| 8 Lacunas; 9 Respostas; 10 Investimento educativo | F1: cálculo assistido, parecer humano e ficha | serviço de cálculo proposto, catálogo Opportunity após B02 |
| 11 Financiamento/bolsas; 12 Equipamento; 13 Parcerias | F1: necessidades indicativas; F2: compromissos e execução | CRM e contrapartes canónicas |
| 14 Aprendizagem/estágios; 15 Formadores | F2: acordos e percursos; F1 só requisitos agregados | identidade e documentos Shared |
| 16 Beneficiários; 17 Inserção; 18 Resultados | F2; indicadores preparados em F1 sem inventar dados | consentimento, auditoria e estatística agregada |
| 19 IA; 20 Governação | F1 assistiva após B07; validação humana transversal | aprovações e observabilidade partilhadas |
React apresenta projecções autorizadas. Laravel concentra regras, autorização contextual, validação, transacções e contratos. PostgreSQL/PostGIS conserva dados canónicos e relações. Jobs só processam eventos confirmados; nenhum HTTP externo dentro da transacção de negócio. Não instalar nova base, framework ou serviço complementar nesta fase.
5. Jornada completa
| Passos | Operação e evidência | Resultado / excepção |
|---|---|---|
| 1–3 | Empregador declara procura com contexto, ocupação, competências, quantidade e prazo | Submetida; falta de fonte ou unidade devolve para correcção |
| 4 | Validador mandatado, diferente do submissor, analisa a versão | Validada, rejeitada ou devolvida; alteração posterior invalida decisão da versão anterior |
| 5–8 | Analista selecciona oferta comparável, origem, período e método | Lacuna com fontes, tipo, confiança qualitativa e limitações; desconhecidos não viram zero |
| 9–10 | Correspondência sugere instituições e recursos necessários | Lista justificada; incompatibilidade curricular/calendário explicitada; sem promessa |
| 11 | Promotor converte lacuna validada em ficha educativa | Rascunho; publicação exige revisão, promotor, riscos, plano e autorização |
| 12–13 | Interesse consentido, identidade, papel e contexto → CRM | Protocolo idempotente, responsável e próxima acção; falha externa preserva pedido e tarefa manual |
| 14 | Autoridade recebe pedido curricular quando aplicável | Apenas decisão externa recebida, nunca aprovação emitida pelo portal |
| 15–16 | Instituição executa; reporta inscrições/conclusão e certificação externa | F2; separar conclusão de certificação, manter evidências e acesso restrito |
| 17 | Empregador confirma absorção autorizada | Vínculo e data, sem inferir emprego por matrícula ou ausência de resposta |
| 18–20 | Recalcular lacuna, detectar expiração/divergência, auditar | Nova versão; reabrir se necessário; nunca reescrever retrospectivamente resultados |
6. Diagrama de componentes
flowchart LR
UI[React: Education] --> BFF[Laravel: autenticação e autorização]
BFF --> EDU[Serviços Education propostos]
EDU --> SH[Shared: identidade, documentos, consentimento, auditoria]
EDU --> DATA[(PostgreSQL / PostGIS)]
EDU --> OUT[Outbox existente]
OUT --> JOB[Worker proposto e reconciliação]
JOB --> CRM[SuiteCRM: futuro mestre comercial]
EDU --> REVIEW[Revisão humana mandatada]
AI[IA assistiva condicionada] --> REVIEW
SOURCES[Fontes autorizadas] --> EDU
7. Diagrama de sequência
sequenceDiagram
participant E as Empregador
participant P as Portal Laravel
participant D as PostgreSQL
participant V as Validador
participant A as Analista
participant C as CRM
E->>P: Submeter procura com versão e idempotência
P->>D: Procura + auditoria + outbox na mesma transacção
P-->>E: Protocolo e estado submetida
V->>P: Rever versão e evidência (mandato válido)
P->>D: Decisão segregada e evento
A->>P: Comparar fontes, período, unidade e nível
P-->>A: Lacuna explicada ou dados insuficientes
V->>P: Validar lacuna e proposta educativa
P->>D: Ficha em rascunho e revisão de publicação
E->>P: Manifestar interesse consentido
P->>D: Pedido, recibo, contexto e evento
Note over P,C: Integração real depende de B04
P->>C: Envio assíncrono mínimo após activação validada
C-->>P: Identificador e confirmação reconciliável
8. Catálogo de entidades
O catálogo completo está em entities.csv, incluindo finalidade/domínio, campos tipados, obrigatoriedade, relações, estados, regras, fonte/responsável, fase, classificação, validade, histórico, permissões e retenção. ! obrigatório, ? opcional. Campos novos são propostas, mesmo quando associados a tabela existente.
Envelope E0 proposto: UUID canónico; source_system/external_id; version_no positivo; classificação; correlation_id; data de referência e validade; responsável pelos dados; fonte/evidência; autor da submissão; estado de revisão; datas de criação/alteração. Usar o envelope existente quando presente; novos atributos exigem análise de compatibilidade. FK para users é bigint no repositório, não UUID inventado. Os restantes IDs devem respeitar o tipo real do domínio: catálogo público Opportunity usa bigint, carteira e domínio CRM usam UUID.
Retenção R0: cada classe terá finalidade, fundamento, prazo/evento de início, prazo de revisão, retenção legal, anonimização e destino aprovados. Até B05: não recolher dados pessoais do novo domínio e não activar expurgo. Não adoptar retenção infinita como política final. Dados demonstrativos sintéticos podem ser descartados apenas no ambiente isolado previsto para ensaios.
9. Modelo lógico de dados
Procura é um lote de postos de trabalho, não uma lista de pessoas. Competências são requisitos N:M desse lote. Uma ocupação pode requerer várias competências sem multiplicar a quantidade de trabalhadores. Uma oferta formativa liga instituição, curso/versão curricular, capacidade por período e território. A relação ocupação–competência e curso–competência terá proficiência, evidência, versão e validade.
SkillGap referencia snapshots de procura e oferta, método, pressupostos e decisões; não duplica as entidades originais. EducationInvestmentOpportunity é um projecto de resposta a uma lacuna validada; pode existir antes de um curso. A oferta calendarizada education_opportunities continua com o significado actual. B02 requer decidir o vínculo à oportunidade pública e ao negócio comercial, sem impor course_id a uma nova escola.
Para estimar recursos: custo monetário decimal, moeda obrigatória com valor, fonte/data e natureza estimada ou contratual. Null significa desconhecido. Nunca converter ausência de orçamento em zero. Quantidade usa inteiro não negativo, unidade e período explícitos; procura activa exige quantidade positiva. Dados legados ficam não avaliados, nunca automaticamente validados.
10. Matriz de relacionamentos
| Relação | Cardinalidade | Regra |
|---|---|---|
| Project/Cluster/Corridor ↔ LabourDemand | N:M contextual | Pelo menos um contexto produtivo; contexto autorizado; relações entre contextos verificadas |
| Territory → LabourDemand / Provider / Capacity | 1:N | Local canónico; localização pessoal não pública |
| Occupation ↔ Skill ↔ Course | N:M / N:M | Nível, versão, equivalência e evidência; sem duplicar a procura por competência |
| TrainingProvider → Course → TrainingCapacity | 1:N / 1:N | Capacidade por janela, local, modalidade e pool partilhado |
| LabourDemand / Capacity → SkillGap | N:M por snapshot | Snapshot imutável e método reproduzível |
| SkillGap → Programme / EducationInvestmentOpportunity | 1:N / 1:N | Lacuna validada; resposta parcial permitida com saldo conhecido |
| Programme ↔ Funder / Investor / EquipmentSupplier | N:M | Papel e compromisso; identidades Shared; manifestação não é financiamento |
| Provider ↔ Employer | N:M via Partnership | Mandatos, acordo, validade e confidencialidade |
| Programme → Cohort → Learner | 1:N / N:M | F2, inscrição autorizada e deduplicada |
| Learner → Internship / Apprenticeship / Completion / Outcome | 1:N | Consentimento e escopo por finalidade; um resultado pode ter várias observações |
| Outcome → Project/Cluster/Corridor | N:M contextual | Absorção confirmada distinta de atribuição causal |
| Documento/Fonte/Decisão → versão de qualquer entidade | N:M | Autor da submissão não confirma sozinho; evidência restrita não é pública |
Exclusões físicas seguem integridade referencial e retenção aprovada; eliminar um registo não pode apagar decisões ou alterar cálculos históricos.
11. Requisitos RF-EDU e RNF-EDU
requirements.csv preserva o significado dos RF-EDU-001–016 da auditoria v4 e acrescenta RF-EDU-017 em diante. Cada linha possui actor, pré-condições, fluxo, excepções, dados, regra, aceitação, prioridade, dependência, fase e teste, mais referências aos contratos, evento, interface, risco e gate. Novos IDs não renumeram os existentes.
nonfunctional.csv define métricas e limiares propostos, método de teste e responsável. Aprovação dos limiares é B08. Ter uma matriz preenchida não significa que segurança, desempenho ou disponibilidade foram testados.
12. Regras de negócio e cálculo de lacunas
| ID | Regra verificável |
|---|---|
| RB01 | Submissor e validador não coincidem; mandato/território/entidade devem estar válidos no instante da decisão |
| RB02 | approved de provider e published de curso são estados existentes; nunca convertê-los em acreditação/certificação |
| RB03 | Comparação usa mesma ocupação, nível ou equivalência aprovada, território/cobertura, período e unidade; incompatíveis são excluídos com motivo |
| RB04 | Procura D soma lotes distintos de postos, deduplicados por empregador/projecto/fase/ocupação/local/janela; não somar a mesma pessoa por cada competência |
| RB05 | Oferta S de trabalhadores exige disponibilidade e evidência autorizada, deduplicada e alocada; vagas de curso não são S. Lacuna observada G=max(0,D−S) só com D e S conhecidos |
| RB06 | Capacidade formativa F é min(vagas livres, capacidade de formadores, equipamentos e instalações), com unidades comparáveis. Falta de uma capacidade crítica torna F não determinada |
| RB07 | Pipeline P=F×taxa de conclusão×taxa de elegibilidade×taxa de disponibilidade só é estimativa, com taxas documentadas, janela de conclusão anterior à contratação e intervalo de incerteza; sem taxas não calcular P |
| RB08 | Lacuna projectada max(0,D−S−P_alocado) é separada da observada. Livro de alocação impede usar a mesma oferta em vários projectos ou cursos do mesmo pool |
| RB09 | Lacuna qualitativa lista competências/proficiências/requisitos em falta; não transformar texto em número de pessoas nem score sem metodologia aprovada |
| RB10 | Confiança usa evidência, actualidade, cobertura e validação; desconhecido é desconhecido. Não inventar percentagem probabilística de confiança |
| RB11 | Fonte expirada bloqueia nova publicação e correspondência oficial; invalida projecções dependentes, gera alerta e preserva versões históricas |
| RB12 | Lacuna validada pode gerar ficha educativa; criação idempotente por versão/lacuna/modelo de intervenção; custos e metas permanecem estimativas até decisão |
| RB13 | Idempotency-Key inclui escopo do actor/operação; mesma chave/conteúdo retorna protocolo; conteúdo diferente 409; reserva e evento atómicos |
| RB14 | If-Match corresponde à versão autorizada; ausente 428, desactualizado 412; não substituir versão mais recente |
| RB15 | Interesse não garante emprego, financiamento, autorização institucional ou retorno; encaminhamento humano com responsável e próxima acção |
| RB16 | Revogação ou alteração de mandato afecta imediatamente novos acessos, downloads, exportações e sincronizações; eventos já entregues seguem procedimento de remediação |
| RB17 | Fonte, método, decisão e regra de alocação acompanham cada resultado; correcção gera nova versão, não reescreve história |
Exemplo didáctico em examples/ usa apenas inteiros sintéticos. Não estima mercado real, acreditação, probabilidades ou taxas. Dados sem evidência recebem «Pendente de levantamento e validação pela entidade competente».
13. Perfis e permissões
| Perfil | Pode propor/submeter | Pode validar/publicar | Limite |
|---|---|---|---|
| Administrador | Configuração técnica aprovada | Não declara acreditação | Sem acesso pessoal por defeito |
| Gestor Education | Tramitar, devolver, suspender divulgação | Publicação editorial após parecer distinto | Não valida a própria submissão |
| Coordenador cluster | Procura/contexto do cluster mandatado | Parecer territorial mandatado | Não extrapola para outro cluster |
| Coordenador corredor | Contexto e necessidades do corredor | Parecer no seu mandato | Não aprova certificações |
| Promotor | Procura/projecto e resposta educativa própria | Não sozinho | Sem acesso a candidatos |
| Empregador | Procura, capacidade de estágio, resultados autorizados | Confirma absorção com evidência | Não certifica cursos |
| Instituição | Oferta, capacidade, programas e resultados próprios | Confirma reportes próprios; revisão por terceiro | Não atribui acreditação ao seu cadastro |
| Tutela | Parecer/decisão no mandato | Decisão institucional no escopo formal | Não é acesso global implícito |
| Acreditadora | Decisões e evidências sob competência comprovada | Confirma acreditação externa própria | Verificação e importação segregadas |
| Financiador | Interesse/compromisso/bolsa | Aprova financiamento no seu processo | Não certifica; sem dados individuais de alunos |
| Investidor | Favoritos/interesse em fichas públicas | Não | Apenas resultados agregados autorizados |
| Fornecedor | Interesse/proposta técnica | Não | Sem acesso a dossiers privados sem autorização |
| Formador | Perfil/ disponibilidade próprios | Não | Sem inferência automática de competências |
| Formando | Dados e consentimentos próprios | Contesta/corrige por processo | Não vê outros formandos |
| Analista | Cálculo/correspondência/recomendação | Não aprova a própria recomendação | Agregados ou pseudónimos autorizados |
| Auditor | Não altera dados de negócio | Consulta trilha no escopo | Acesso auditado, minimizado e temporário |
| Público | Não escreve | Não | Só projecções publicadas e agregadas |
Negar por defeito. A decisão combina identidade, papel, organização representada, mandato, finalidade, classificação, território, validade e estado. Nenhum UUID, URL ou chave de idempotência concede acesso. Estas permissões são alvo, não capabilities já instaladas.
14. RACI
R executa; A responde pela decisão final; C consultado; I informado. Cada linha tem um A. Organizações/pessoas concretas permanecem por nomear.
| Acção | R | A | C | I |
|---|---|---|---|---|
| Aprovar âmbito/piloto/orçamento | Produto | Patrocinador | Comité Executivo, coordenadores | Equipa |
| Propor/submeter procura/oferta | Empregador/instituição | Responsável dos dados da entidade | Coordenadores | Gestor |
| Validar fonte/taxonomia | Secretariado | Entidade competente | Dados, coordenadores | Produto |
| Aprovar arquitectura/contratos | Equipa técnica | Comité de Arquitectura | Segurança, CRM | Executivo |
| Validar lacuna | Analista independente | Validador institucional mandatado | Empregador, instituição | Gestor |
| Aprovar/publicar ficha | Revisor editorial | Dono do Produto | Validador e promotor | Público autorizado |
| Confirmar decisão externa | Verificador mandatado | Entidade competente emissora | Jurídico, Secretariado | Gestor |
| Corrigir/suspender dados | Gestor + responsável de dados | Secretariado de Dados | Tutela, Segurança | Consumidores afectados |
| Aprovar modelo/regras IA | Equipa IA | Comité de IA e Dados | Arquitectura, entidades | Produto |
| Auditar acessos/resultados | Auditor independente | Comité Executivo | Segurança, Secretariado | Patrocinador |
| Autorizar produção/expansão | Produto + Operações | Comité Executivo | Todos os comités e responsáveis | Utilizadores afectados |
15. Integrações, propriedade e sincronização
| Dados | Mestre → consumidor | Campos partilhados | Cadência/conflicto/falha | Reconciliação |
|---|---|---|---|---|
| Procura, lacuna, capacidade, curso, mapa | Portal Education/Shared → CRM só contexto | UUID, título autorizado, estado editorial, URL | Eventos após commit; versão maior; sem sobrescrever decisão institucional | Secretariado |
| Contacto/organização comercial | CRM local na transição; SuiteCRM após corte → portal | ID externo, nome/contacto mínimo, estado comercial | Um escritor por fase; versão/owner; conflito vai a revisão, nunca last-write-wins indiscriminado | Responsável CRM |
| Interesse educativo | Portal → CRM | UUID, finalidade, papel, contexto, contacto consentido | Outbox; recepção idempotente; erros ambíguos exigem lookup/reconciliação antes de repetir POST | Operações CRM |
| Lead/tarefa/reunião/proposta/compromisso | CRM → painel autorizado | Estado, responsável, prazo, próxima acção | Após evento ou consulta incremental proposta; deduplicar, revalidar consentimento | Gestor CRM |
| Acreditação/certificação/validação curricular | Entidade competente → portal | Referência, escopo, emissor, validade, evidência autorizada | F1 registo documental verificado; F3 API apenas com acordo; nenhuma escrita de volta que altere decisão | Entidade + Secretariado |
| Beneficiários e resultados pessoais | Instituição/empregador autorizado → Education | Só mínimo necessário, consentimento e finalidade | F2; nunca sincronizar notas, saúde ou localização individual para CRM | Responsável de dados |
O sincronizador real está pendente. Backoff, dead-letter e replay controlado são propostas; capturar outbox não equivale a entregar. Tombstones e correcções são mensagens auditadas; não apagar remotamente por uma falha local. Acordos documentam payload, fundamento, destinatário, retenção e revogação.
16. Eventos de domínio
Envelope proposto: event_id UUID, event_type, schema_version, aggregate_id UUID, aggregate_version, occurred_at UTC, correlation_id, source_system, classification, payload mínimo referencial. Sem documentos, nomes de formandos ou tokens. Outbox/inbox existentes a reutilizar após confirmar índices e ledger de consumidores; unique(consumer,event_id), processamento transaccional, rejeição de versão incompatível.
| Fase | Eventos | Produtor → consumidor |
|---|---|---|
| F1 | LabourDemandSubmitted, LabourDemandValidated | Education → revisão/cálculo |
| F1 | TrainingCapacityUpdated, SkillGapDetected, SkillGapValidated | Education → analista/painel |
| F1 | EducationInvestmentOpportunityCreated, TrainingProviderMatched | Education → revisão/editorial; matching não aprova |
| F1 | FunderInterestRegistered, InvestorInterestRegistered | Portal → adaptador CRM; mapear ao evento de interesse existente sem dupla emissão comercial |
| F1 | DataValidationExpired | Validade → dependências/painel, sem alterar decisão oficial externa |
| F2 | EmployerPartnershipCreated, CurriculumReviewRequested | Education → tramitação e partes autorizadas |
| F2/F3 | AccreditationStatusReceived, CertificationReported | Adaptador externo verificado → registo de evidência |
| F2 | TrainingCohortStarted, TrainingCompleted, InternshipStarted | Instituição → acompanhamento autorizado |
| F2 | EmploymentOutcomeReported, SkillGapReduced, SkillGapReopened | Empregador/analista → monitoria e revisão |
Não há tópicos, filas novas ou listeners activados. Propostas de artefactos em §23; contract tests devem detectar duplicação, reorder, revogação e mensagens venenosas.
17. Endpoints e contratos
openapi.proposed.json é OpenAPI 3.1 Proposta, não rotas instaladas. Prefixo novo /api/v1/education; não modificar routes/api.php nesta entrega. O documento define o núcleo LabourDemand; os endpoints restantes constam da matriz RF com contratos detalhados pendentes, não são apresentados como completos.
| Família proposta | Operações | Requisitos |
|---|---|---|
| skills / occupations | GET, POST, PATCH com versão | 001, 017 |
| labour-demands | GET cursor, POST idempotente, GET/PATCH por UUID | 002, 009, 018 |
| labour-demands/{id}/decisions | POST decisão segregada e If-Match | 009, 032 |
| providers / courses / capacities | Cadastro, declaração de capacidade e evidências | 003, 007, 019 |
| gaps / matches | Criar análise, consultar explicação, decisão humana | 004, 011, 020 |
| investment-opportunities | Rascunho, revisão e publicação | 005, 006 |
| investment-opportunities/{id}/interests | POST consentido e idempotente | 008, 021 |
| responses / equipment-needs / funding-needs | Resposta e inventário indicativo MVP | 010, 022–024 |
| indicators / map | GET agregados filtrados, sem pontos pessoais | 015, 031 |
| ai-recommendations / audit | GET autorizado, decisão humana; auditoria só leitura | 014, 032 |
Autenticação alvo: OAuth2 para autorização, OIDC para identidade, issuer/JWKS/audience confiáveis, scopes e mandato contextual, expiração e revogação. Não reutilizar credenciais OAuth do SuiteCRM para autenticar utilizadores do portal. Issuer, fluxos e scopes ainda não configurados (B03); contrato usa esquema bearer indicativo e extensões que identificam esta pendência, sem inventar URLs de token/discovery.
JSON; UUID de recursos Education; ISO 8601; ISO 4217; ISO 3166-1 alpha-2 para país; cursor opaco ligado aos filtros/escopo, ordem estável (updated_at,id); máximo proposto 100 itens; X-Correlation-Id validado ou gerado no servidor. Erros application/problem+json com type/title/status/detail/instance/correlation_id e erros de campo sanitizados. 401 token, 403 escopo, 404 recurso inacessível, 409 conflito/idempotência, 412 versão, 422 regra, 428 precondição, 429 limite, 503 dependência. ETag opaco forte para a versão; If-Match obrigatório em alterações e decisões. Rotação/retensão do ledger de idempotência deve ser aprovada antes de activação. Mudança incompatível requer nova versão principal e transição.
18. Modelo CRM
Accounts para organizações, Contacts para interlocutores autorizados, Leads para interesse qualificado, Opportunities para negociação, Tasks/Meetings para acções, Campaigns para promoção; nomes de campos, ligações e módulos customizados dependem de descoberta da instalação. Não criar módulos SuiteCRM por suposição. Chave canónica da oportunidade educativa e origem projecto/cluster/corredor/território acompanham contexto. Separar montante indicado, proposta, compromisso e investimento realizado. Nenhum destes implica certificação ou emprego.
Papéis investidor/financiador/instituição/empregador/fornecedor pertencem a relações, não cinco contactos duplicados. Responsável, próxima acção e SLA aprovado obrigatórios antes de avançar a fase comercial. Quando B04 persistir, gerir localmente sob o modelo já existente, sem declarar sincronização nem activar escrita dupla.
19. Modelo GIS
Reutilizar geo_locations e geo_geometries; atribuir locais institucionais e áreas de cobertura autorizadas. ST_IsValid, SRID 4326 e envelope mundial já têm constraints. Distância métrica deve usar geography ou projecção apropriada, não graus. Distância em linha recta não é duração de viagem; rede rodoviária, transporte, acessibilidade e metodologia são fontes ainda não seleccionadas. Mapas mostram agregados por território, procura e oferta com unidade/período, validade e limitações; esconder ou agregar células abaixo do limiar de divulgação aprovado. Sem fonte/limiar aprovado: manter camada interna/desactivada. Não publicar residências ou trajectos de pessoas.
20. Arquitectura de IA
Inicialmente o motor de cálculo é determinístico e explicável. IA é capacidade separada, condicionada a B07: ingestão de fontes autorizadas → validação/limpeza → recuperação contextual → geração de proposta → filtros de dados pessoais e autoridade → revisão humana → publicação autorizada → monitoria. Não seleccionar fornecedor, instalar modelo ou enviar dados neste pacote.
Cada saída guarda referências/versionamento das entradas, fonte, data, modelo/versão, prompt/método versionado sem segredos, explicação, confiança calibrada ou indisponível, limitações, estado de recomendação, revisor, decisão e data. Texto de fontes é dado não confiável: instruções contidas em currículos/documentos não podem executar ferramentas nem modificar permissões.
Avaliação antes de activar: conjunto de referência aprovado, exactidão de citações, taxa de recomendações úteis, omissões perigosas, disparidades de erro por território/sector, contaminação de dados, fuga de informação, robustez a instruções maliciosas e revisão humana. Thresholds de qualidade/modelo dependem do Comité; zero atribuições de estados oficiais é condição absoluta.
21. Matriz de limites da IA
| Permitido como proposta | Controlo | Proibido |
|---|---|---|
| Extrair competências/ocupações de fontes autorizadas | Citações, validação taxonómica e revisão | Inferir competências individuais sem evidência |
| Sugerir correspondências/currículo a rever | Explicação e condições eliminatórias visíveis | Acreditar, certificar ou aprovar currículo |
| Estimar procura/risco e cenários | Horizonte, pressupostos e intervalo | Previsão vinculativa ou emprego garantido |
| Resumir dados de conclusão/inserção | Agregação, autorização, reconciliação | Decidir admissão, exclusão ou contratação |
| Assinalar divergência/expiração | Tarefa ao responsável e confirmação humana | Transformar estimativa em decisão oficial |
| Sugerir localização de programas | Fonte GIS, incerteza e avaliação humana | Publicar recomendação sem revisão |
22. Indicadores
indicators.csv contém os 25 indicadores solicitados: definição/fórmula, unidade, fonte, frequência, responsável, linha de base, meta, validação e divulgação. Todos se segmentam por projecto, cluster, corredor e território quando a relação é comprovada, além de período e ocupação/competência pertinentes.
Denominador zero ou população incompleta produz «não disponível», não 0%. Pessoas em vários cursos são contadas uma vez em indicadores de pessoas; episódios são contados separadamente. Metas, baselines, custos e efeitos causais não são inventados. Inserção confirmada não prova que o programa causou o emprego. Reconciliar contagens com fontes antes de divulgar.
23. Backlog e artefactos para programação
| Pacote | RF | Localizações propostas, não criadas nesta entrega | Dependência / teste |
|---|---|---|---|
| EDU-A Taxonomias e procura | 001/002/009/017/018 | app/Domain/Education/{Models,Requests,Policies,Services}; app/Http/Controllers/Api/V1/Education; migration aditiva após B02/B03 |
T-001/T-002; schemas e autorizações |
| EDU-B Oferta e capacidade | 003/007/019 | mesmos domínios, adaptadores dos modelos existentes; FormRequests; decisão/evidência separadas | T-003/T-007; não interpretar approved como acreditado |
| EDU-C Lacunas/correspondência | 004/011/020 | Services/GapCalculator, MatchExplainer; Jobs/Listeners apenas após contratos |
T-004/T-011; cálculo puro e alocação concorrente |
| EDU-D Oportunidade/interesse | 005/006/008/021 | adaptador para Opportunity/InterestSubmission; Policy contextual; eventos após commit | T-005/T-008; idempotência e CRM |
| EDU-E Pesquisa/mapa/painel | 015/031 | resources/js/pages/education, components/education, hooks/useEducation, serviço API e ficheiros PT/EN propostos |
T-015/T-031; acessibilidade e dados agregados |
| EDU-F Revisão/IA/auditoria | 014/032/033 | Services de decisão; Policies; Jobs de expiração; listeners de invalidação; interface de revisão | T-014/T-032; RBAC/anti-autovalidação |
| EDU-G Qualidade e migração | 016/033 | tests/Unit/Education, tests/Feature/Education, contratos e E2E; scripts separados sem SQL de remoção |
ensaio/restauro e gates G0–G3 |
Interfaces propostas: I01 catálogo; I02 formulário de procura; I03 oferta/capacidade; I04 lacuna e explicação; I05 ficha educativa/interesse; I06 fila de revisão; I07 mapa/painel; I08 acompanhamento F2. Mensagens e estados PT/EN devem partilhar chaves; não traduzir códigos de dados. Componentes existentes de formulário, conta, navegação e mensagens são reutilizados. Repositório/convenções podem motivar adaptar os caminhos antes da aprovação, sem criar uma segunda aplicação.
24. Plano MVP e selecção
| Critério | Evidência necessária | Regra proposta |
|---|---|---|
| Dados | Fonte, actualidade, completude, validade, direitos | Critério eliminatório se faltam campos críticos |
| Relevância/emprego | Evidência económica e procura documentada | Pontuação ordinal 0–3 proposta; sem dados = não avaliado |
| Projecto-piloto | Confirmação formal e responsável | Eliminatório para entrada |
| Equilíbrio territorial | Cobertura e diversidade justificadas | Comité documenta trade-off; não inventar quota |
| Criticidade de competências | Impacto e prazo comprovados | Não confundir volume declarado com validado |
| Capacidade institucional | Mandatos, equipa, calendário, compromisso | Eliminatório se não há validador |
| Oferta e parceiros | Instituições/empregadores participantes | Evidência de disponibilidade, não lista presumida |
| Integração | Contratos, dados e ambiente viáveis | Sem externalidade não formalizada |
| Custo/prazo/risco | Estimativa validada e mitigação | Orçamento pendente; não calcular retorno fictício |
| Replicabilidade | Lições e condições de expansão | Critério comparativo após elegibilidade |
Pesos e limiar agregados pendentes de aprovação; não reaproveitar pontuações comerciais dos clusters como pontuação de prontidão educativa. Após validar elegibilidade, comparar candidatos com critérios/versão uniformes, justificar selecção de até três de cada tipo e guardar decisão. Arquitectura não codifica limite permanente de três.
Entrega F1 em pequenos lotes: A/B → C → D → E/F → ensaios G. Dependências B01–B08 impedem prometer datas absolutas ou activar funcionalidades sem evidência. Feature flag e allowlist de pilotos são propostas de mecanismo; nomes/configuração ainda não criados.
25. Roteiro por fases e expansão
| Fase/vaga | Responsável | Entrada / saída | Dependências | Calendário e orçamento | Risco / mitigação |
|---|---|---|---|---|---|
| F0 Diagnóstico/governação | Produto + Secretariado | Mandatos/fontes → G0 | B01/B05/B06 | Pendente de plano aprovado; esforço de levantamento a estimar | Fonte sem autorização → quarentena |
| F1 Piloto até 3+3 | Equipa técnica + coordenadores | G0 → G1/G2 | B02/B03/B04/B07/B08 | Estimar por pacotes A–G após inventário | Complexidade → escopo pequeno e flag desligada |
| F2 Programas/financiamento | Instituições + Produto | Piloto aceite → G3 por programa | Consentimento, parceiros, recursos | Orçamento por programas sem montantes presumidos | Exposição pessoal → minimização e controle granular |
| F3 Interoperabilidade | Arquitectura + entidades | Acordos e contratos → homologação externa | Sistemas/fontes oficiais | Sequência por disponibilidade institucional | Divergência → reconciliação/manual |
| F4 Inteligência avançada | Comité IA e Dados | Métricas validadas → revisão periódica | Dados representativos e observação longitudinal | Calendarização após evidência de F1/F2 | Viés/deriva → suspensão e revisão |
| Expansão vaga n | Coordenadores + Operações | G2/G3 do piloto → Go da vaga | Qualidade/capacidade/suporte de novos territórios | Estimativa específica, aprovada antes da vaga | Regressão → canário, monitoria e reversão por flag |
Processo repetível: inventariar candidatos → pontuar e deliberar → preparar pequeno grupo → reconciliar e testar → activar gradualmente → medir e corrigir. Não colocar todos os corredores da carteira em produção educativa só porque já têm cadastro. Cada vaga tem responsável nominal, orçamento, calendário, entrada/saída, riscos e decisão registados antes de activação.
26. Riscos
| ID | Risco | Controlo / responsável |
|---|---|---|
| R01 | Estado editorial confundido com acreditação | RB02, separação de registos; entidade competente |
| R02 | Vagas/competências duplicadas como trabalhadores | RB03–RB08, pools e testes; analista |
| R03 | Exposição de alunos/localização | Policies, minimização e agregação; responsável de dados |
| R04 | Identidades ou campos comerciais divergentes | Um mestre, UUID e reconciliação; CRM |
| R05 | Fonte vencida/modelo sem base | Validade, versionamento e suspensão; Secretariado/IA |
| R06 | Quebra de contratos/tabelas existentes | Extensão aditiva e testes de regressão; Arquitectura |
| R07 | Sem recursos/mandatos para operar | Piloto e Go/No-Go; Patrocinador |
| R08 | Importação errada ou perda de histórico | Quarentena, reconciliação, restauro; Operações |
27. Testes e evidência
Cada T-n corresponde ao RF de mesmo número na matriz. Casos obrigatórios: autor tenta aprovar; gestor tenta atribuir acreditação; token sem scope/mandato expirado; aluno de outro tenant; documento em quarentena; fonte expirada; procura duplicada por competência; capacidade partilhada entre cursos; período/nível/unidade incompatíveis; dados em falta; negativas/overflow; conflito If-Match; mesma chave com payload diferente; falha após commit; CRM indisponível; eventos duplicados/fora de ordem; revogação antes de replay; instrução maliciosa na fonte IA; exportação com células pequenas; rollback e restauro.
Exemplos e testes em examples/gap-calculator.*.mjs exercitam apenas o contrato matemático proposto com dados sintéticos. Testes de consistência do pacote verificam IDs, referências e OpenAPI; não substituem validação semântica OpenAPI completa nem testes funcionais do domínio. A suite anterior do portal não demonstra RF-EDU cumpridos.
Homologação exige testes unitários, integração PostgreSQL/PostGIS isolada, contrato, E2E PT/EN, concorrência, autorização, privacidade, acessibilidade manual, carga, falhas, recuperação e regressão do portal. Sem ambiente/fontes aprovados: registar «não executado», nunca «aprovado».
28. Critérios Go/No-Go
| Gate | Critérios cumulativos | Aprovador | Estado actual |
|---|---|---|---|
| G0 Desenvolvimento integrado | Escopo, pilotos, modelo canónico B02, responsáveis, fontes, taxonomias e arquitectura aprovados; branch própria | Produto + Arquitectura | Pendente |
| G1 Homologação | Código revisto, análise estática, testes de regras e isolamento, contratos, flags e migração/restauro em cópia aprovados | Arquitectura + Segurança | Pendente |
| G2 Produção piloto | B01–B08 resolvidos no âmbito activado; permissões, limites oficiais, indicadores, privacidade, acessibilidade, desempenho, suporte e rollback aceites; zero defeitos críticos | Comité Executivo | NO-GO actual |
| G3 Expansão | Piloto medido, novos dados/mandatos/recursos validados, regressão/reconciliação e capacidade operacional aprovadas | Comité Executivo | Pendente |
O MVP inclui IA assistiva e integração CRM como alvo. Enquanto os respectivos bloqueios persistirem, não declarar o MVP integral concluído; redução formal de escopo deve ser uma decisão explícita, não uma exclusão silenciosa.
29. Governação, migração e operação
Secretariado mantém fontes, dicionários, decisões e prazos; gestores fazem triagem; coordenadores confirmam contexto; comités deliberam alterações materiais. Proposta de cadência: triagem semanal, qualidade mensal, estratégia trimestral e revisão imediata em incidente, sujeita a capacidade aprovada.
migration-proposal.md define inventário, extensão, mapeamento, quarentena, ensaio, reconciliação, backup/restauro e reversão. Não contém comandos de remoção nem migrations activas. Como as seis tabelas estão vazias, não há dados de formação a migrar agora; isso não autoriza eliminar a estrutura ou dispensar levantamento de fontes externas.
Logs minimizam dados pessoais; métricas de fila/erros/idade da fonte; alertas têm responsável e procedimento; modo degradado conserva protocolo e identifica dados não sincronizados. Incidentes podem suspender camada, fonte, modelo ou conector sem eliminar registos. Mudanças de versão têm análise de impacto, contrato e aprovação técnica.
30. Checklist institucional e conformidade
- Entidades e responsáveis nomeados; mandatos, jurisdição/escopo e segregação comprovados.
- Pilotos escolhidos com critérios comuns; projectos formalmente validados.
- Taxonomias, níveis, fontes, periodicidade, validade, licença e regras de divulgação aprovados.
- Situações declarada, em análise, validada, acreditada, certificada, expirada, suspensa e rejeitada distintas; recomendação IA nunca decisão.
- Tratamento, consentimento, representação, menores, retenção e partilha validados.
- Contratos, ownership, idempotência, versão, falhas, reconciliação e rollback aprovados.
- Métricas, orçamento, apoio operacional, testes e Go/No-Go assinados.
- Nenhum dado, custo, emprego, curso ou acreditação foi inventado para preencher o MVP.
conformity.csv relaciona princípios, 20 blocos, tecnologias, integrações, segurança, governação, MVP e exclusões com esta especificação. «Conforme» significa alinhamento documental, nunca certificação de implementação. «Parcialmente conforme» identifica cobertura sem operação; «Pendente de validação» exige decisão/evidência; «Não conforme» identifica lacuna actual face ao alvo. A auditoria geral v4 mantém-se; este pacote não marca RF-EDU como implementados.