# Formação Técnica, Competências e Investimento em Educação > O diagnóstico inicial abaixo foi complementado pelo [relatório de execução](implementation-status.md), 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 ```mermaid 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 ```mermaid 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](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](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](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.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](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](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](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.