Investidor-V2/docs/investmoz/existing-business/wizard-implementation.md

Formulário por etapas — entrega local, 29/09/2026

Disponível em /investidor/negocios: criar rascunho e abrir a ficha. O prompt A–C completo ainda não está entregue. Este incremento implementa a preparação privada por etapas, autosave, retoma, sector e confirmação. Não implementa ainda publicação, uploads seguros, manifestações MNE ou operação integral.

1. Diagnóstico tecnológico: Laravel 13.30.1, PHP de validação 8.5.11, React 19.2.8, TypeScript 5.9.3, Inertia, Vite Plus, Leaflet e PostgreSQL 17.11/PostGIS. Mantidos componentes e autenticação por sessão/email verificado. Filas database/Redis e disco S3 são configuráveis; conectividade Redis/S3/ClamAV e CRM não ensaiada neste incremento. Sem novas dependências.
2. Pressupostos: formulário autenticado, classificação reservada e public.existing_businesses como autoridade. Identidade e titularidade são declarações pendentes. Referências documentais não são uploads, mandatos validados ou autorizações de transmissão. O preenchimento permite rascunhos incompletos; a submissão aplica validações adicionais. Clientes anteriores sem wizard_version conservam o contrato legado; converter todos os clientes exige uma migração de contrato posterior.
3. Mapa A–C: ver matriz abaixo. Não há equivalência entre oito etapas visíveis e implementação de todos os requisitos dessas etapas.
4. Plano por fase: responsável técnico da implementação: Codex. Incremento A1 executado: schema/validação, FK sectorial, wizard e testes. A2 pendente: localização normalizada/cartografia, contexto económico, anexos/scanner, consentimentos separados e acessibilidade integral. B pendente: manifestação MNE ligada a anúncio publicado, perfil e CRM idempotente. C pendente: aprovações, tarefas, SLA, alertas e dashboard. Dependências e gates mantidos em implementation-status.md; autorizações de desenvolvimento existentes preservadas.
5. Modelo PostgreSQL: coluna nullable bigint existing_businesses.sector_id, FK RESTRICT para a taxonomia existente e índice B-tree completo. Dados declarativos privados ficam no payload cifrado já existente; activos/direitos continuam nas entidades tipadas existentes. Não foram criadas pessoas, sectores ou negócios no schema mne. Localização deste formulário é ainda descritiva, não georreferenciada.
6. Migration/modelos: 2026_09_29_200000_existing_business_form_sector.php aplicada localmente. DOWN remove a coluna somente se não houver associações sectoriais. Modelo ExistingBusiness existente preservado; BusinessFormSchema centraliza campos, rótulos PT/EN e validação. Snapshot/auditoria cifrados existentes conservados.
7. API: mesmos nove endpoints privados /api/v1/existing-business. sector_id é adicional no draft; confirmation_code exigido na submissão de wizard_version=1. GET da ficha fornece formSchema e sectores activos. Erros 403/409/422 e ausência de publicação preservados. OpenAPI actualizado para 1.2.0; schema exportável por tools/export-business-form-schema.php.
8. Permissões: proprietário verificado cria/edita rascunho ou pedido de informação; revisor designado, independente e com MFA consulta submissões. Terceiros recusados. Revisores recebem os novos campos apenas após a policy de consulta. Autosave usa as mesmas autorizações e versões da gravação manual.
9. Estados: rascunho → submetido; revisão/pedido de informação/retirada existentes. Confirmação explícita por código e consentimento de análise interna no servidor. Repetir submissão com versão anterior dá 409 sem duplicar histórico; ainda não há comprovativo idempotente por chave de pedido. As duas aprovações e os demais estados de A–C continuam pendentes.
10. Serviços/eventos/Jobs: reutilizados ExistingBusinessDrafts, ExistingBusinessIntake, objectos, snapshots e ponte legada. Nenhum Job externo, tarefa de triagem, notificação ou envio CRM novo. O consentimento actual é de revisão interna; não é o catálogo completo de consentimentos versionados do anexo.
11. React: business-wizard.tsx oferece oito etapas, progresso, PT/EN nos controlos principais, autosave após três segundos, retoma no servidor, resumo e confirmação. Navegação/fecho avisam sobre alterações não gravadas; conflitos não substituem silenciosamente dados. Representante revela campos de mandato. Activos/direitos reutilizam BusinessObjects; estes componentes existentes ainda não estão integralmente traduzidos. Criação/consulta administrativa por representação de terceiros permanece pendente.
12. Código por ficheiro: novos app/Services/BusinessFormSchema.php, migration sectorial, resources/js/pages/investment/business-wizard.tsx, tests/Feature/ExistingBusinessWizardTest.php, exportador de schema e ferramentas de navegador. Alterados controlador, Drafts, Intake, business.tsx, businesses.tsx, business-types.ts e gerador OpenAPI. Código completo nesses ficheiros; sem ficheiros removidos nem commit Git.
13. Testes: suite completa executada: 180 testes / 1845 verificações. Depois do controlo adicional por modalidade e do teste de rollback, suite específica do wizard: 2 testes / 30 verificações aprovados. Cobertura inclui cifragem, terceiro recusado, retoma, sector, dados inválidos, conflito de versão, mandato, activo obrigatório, confirmação, submissão duplicada e rollback. Navegador: autosave/recarga, resumo em 390/1440 px e submissão, sem excepções JS. Isto não é uma auditoria WCAG completa.
14. Comandos: abaixo. Não foi necessário instalar pacotes Composer/npm. Backend requer PHP com pgsql. Migration local aplicada após backup/restauro, usando --path específico. Os scripts de navegador e fixtures só usam QA em 55441/18027, nunca a base local operacional.
15. Resultados: PHPStan, Pint, TypeScript, lint do wizard e build aprovados. Backup com restauro de 210 tabelas: storage/app/private/mne-integrity-backup-20260929-200103/. Evidência do navegador: wizard-browser-validation.json. Auditoria de dependências e ensaios de serviços externos não executados neste incremento.
16. Riscos residuais: restantes campos e relações A; identidade normalizada; coordenadas/geometria; CRM MNE; scanner/upload; redis em operação; consentimentos separados; comprovativo/notificações; SLA; aprovações/publicação; tradução integral; testes de acessibilidade, carga e serviços externos. A conta de BD local ainda é superuser. Nenhuma alegação de prontidão para produção.
17. Go/No-Go: Go para testar preparação privada local; No-Go para entrega integral A–C ou Go-Live. Os fluxos incompletos não foram expostos como funcionais.

Requisito	Implementação actual	Estado
A: proponente/representação	Campos cifrados, mandato condicional, declaração e validação	Parcial; sem verificação de identidade/documentos
A: modalidade/sector/valor	Taxonomia existente, FK, limites, moeda e natureza na submissão	Parcial; faltam intervalos e estruturas completas
A: localização/contexto	Descrição privada	Geografia estruturada e ligações pendentes
A: activos/direitos	Editor tipado existente; objecto aplicável exigido por modalidade	Parcial
A: fontes/documentos	Referências declaradas	Upload/scanner pendentes
A: rascunho/retoma/resumo	Autosave, versão, oito etapas, confirmação no servidor	Testado
B: interesse/CRM	Serviço geral existente preservado	Integração MNE pendente
C: revisão	Revisão privada e histórico existentes	Tarefas/SLA/dupla aprovação pendentes

php artisan migrate --path=database/migrations/2026_09_29_200000_existing_business_form_sector.php
php tools/export-business-form-schema.php
node tools/existing-business-openapi.mjs
php vendor/bin/phpunit --filter ExistingBusinessWizard --do-not-cache-result
npm.cmd run types:check
npm.cmd run build

Em ambiente QA isolado (APP_ENV=testing, base portal_services_test, porta 55441): php tools/business-wizard-browser-seed.php, seguido de node tools/business-wizard-browser.mjs, com servidor QA 18027 e navegador CDP 9224. As fixtures sintéticas ficam apenas nessa base de teste.