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

# Education — pacote de concepção para revisão

> **Decisões técnicas executadas:** ver [decisões adoptadas e limites externos](decisions.md). A preparação de investimento educativo já usa a oportunidade canónica em rascunho, com pesquisa e indicadores internos. A publicação oficial e as integrações externas continuam condicionadas à evidência institucional.

> **Actualização de execução, 26/09/2026:** existe agora um diagnóstico do código interno já presente, correcções e testes de regressão. Consultar [execução, cobertura dos 33 RF e decisões pendentes](implementation-status.md). A descrição abaixo corresponde à entrega inicial de concepção; não é o estado actual completo do repositório.

**Estado global: Proposta.** Produzido em 26/09/2026 a partir do pedido anexado e do diagnóstico do repositório. Não activou rotas, jobs, migrations, integrações ou recolha de dados pessoais. Nenhuma instituição, curso, acreditação, capacidade, custo ou resultado foi preenchido artificialmente.

Começar pela [especificação em 30 secções](specification.md). A sequência principal é procura → competências → lacuna → resposta formativa → investimento educativo → formação → inserção → monitoria. O MVP cobre registo/análise assistida; programas e resultados pessoais avançam na Fase 2.

| Artefacto                                                  | Objectivo e âmbito                                                                                            | Pressupostos e dependências                                         | Decisões pendentes                                 | Critério de validação                                                | Estado             |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | -------------------------------------------------- | -------------------------------------------------------------------- | ------------------ |
| [Especificação](specification.md)                          | 30 entregáveis na ordem solicitada: escopo, arquitectura, jornada, dados, controlo, integração e operação     | Diagnóstico real §2; fontes do pedido                               | B01–B08                                            | Revisão por Produto, Arquitectura, Segurança e entidades competentes | Proposta           |
| [RF-EDU](requirements.csv)                                 | 33 RF, preservando os 16 IDs v4; rastreabilidade a entidades/regras/endpoints/eventos/interfaces/testes/gates | Matriz v4 e modelo proposto                                         | Aprovação do MVP e backlog                         | Nenhum ID duplicado, referências resolvidas e critérios verificáveis | Proposta           |
| [RNF-EDU](nonfunctional.csv)                               | 18 RNF com métricas, limiares propostos, testes e responsáveis                                                | Capacidade operacional a medir                                      | B08 e políticas institucionais                     | Aprovar limiares e demonstrar cada teste em homologação              | Proposta           |
| [Entidades](entities.csv)                                  | 44 entidades/papéis, campos tipados, regras, estados e reutilização                                           | Envelope E0, retenção R0, Shared confirmado parcialmente            | B02/B03/B05/B06                                    | Não duplicar núcleo; confirmar campos propostos e propriedade        | Proposta           |
| [Indicadores](indicators.csv)                              | 25 fórmulas, fontes, cadências, divulgação e responsáveis                                                     | População, unidade e período comparáveis                            | Baselines/metas e supressão                        | Reconciliar com fontes antes de publicação                           | Proposta           |
| [OpenAPI inicial](openapi.proposed.json)                   | Núcleo de procura: lista, criação, consulta, revisão e decisão                                                | OpenAPI 3.1; paths ainda não instalados                             | B03; restante API ainda exige contratos detalhados | Validação semântica completa e contract tests antes de integração    | Proposta parcial   |
| [Migração](migration-proposal.md)                          | Inventário, mapeamento, vagas aditivas, pseudocódigo, reconciliação e reversão                                | Schema existente e zero registos nas seis tabelas Education         | B02; backup/ambiente aprovados                     | Ensaio isolado, restauro e totais reconciliados                      | Proposta           |
| [Conformidade](conformity.csv)                             | 53 linhas incluindo 20 blocos, princípios, tecnologia, integração, segurança e exclusões                      | Pedido e auditoria v4                                               | Acções correctivas por linha                       | Conferência documental e evidência funcional por requisito           | Proposta           |
| [Exemplo de cálculo](examples/gap-calculator.mjs) e testes | Distinguir pessoas/vagas, incompatibilidade, expiração e desconhecidos                                        | Dados exclusivamente sintéticos; não modela alocação multi-projecto | Aprovação metodológica B06                         | Casos previstos passam; não é cálculo oficial nem IA                 | Proposta didáctica |

## Evidência desta entrega

- Leitura de migrations, APIs, autorização, contratos de interesse/outbox e versões efectivas dos lockfiles.
- Consulta local read-only: `skills`, `occupations`, `training_needs`, `training_providers`, `courses` e `education_opportunities`, todas com zero registos. PostgreSQL 17.11/PostGIS 3.6.2.
- `node --test docs/investmoz/education/examples/*.test.mjs`: **11 testes aprovados**. São testes de exemplo e consistência do pacote; não comprovam os RF-EDU no portal.
- Nenhuma migration, instalação, alteração de configuração, seed ou envio ao CRM realizado nesta entrega.
- A suite funcional PHP anterior não foi repetida: não houve alteração de código da aplicação. A aprovação anterior do portal não foi transferida para este domínio.

## Decisões concretas para permitir integração

1. Confirmar até três clusters/corredores, projectos-piloto, fontes, responsáveis e entidades competentes — sem os presumir a partir da carteira de rascunhos.
2. Aprovar a diferença entre procura laboral, necessidade formativa, oferta calendarizada e oportunidade de investimento educativo; decidir o vínculo ao catálogo canónico.
3. Aprovar mandatos/RBAC, identidade OAuth/OIDC, tratamento/retensão e contratos de dados antes de disponibilizar escrita ou dados pessoais.
4. Validar a metodologia de alocação/cálculo, limiares RNF, ambiente de homologação e migração reversível.

Estas dependências decorrem do próprio pedido: «Produz inicialmente arquitectura, modelos, contratos, migrations propostas, testes e exemplos de código para revisão». O pacote não trata exemplos como autorização para execução automática ou produção.

## Referências técnicas

- [OpenAPI 3.1.0](https://spec.openapis.org/oas/v3.1.0.html): formato do contrato proposto. O esquema bearer é indicativo enquanto issuer/fluxos OAuth/OIDC não estiverem confirmados.
- [WCAG 2.2](https://www.w3.org/TR/WCAG22/): referência da meta de acessibilidade proposta; conformidade do produto ainda não auditada.
- [Auditoria v4](../requirements-audit.csv) e [progresso do portal](../upgrade-progress.md): diagnóstico existente, sem promover RF-EDU para cumprido.