Investidor-V2/docs/investmoz/education/specification.md

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.