Files
Investidor-V2/docs/investmoz/business-marketplace-schema-integration.md
T
nala 1106509116
tests / ci (push) Canceled after 0s
vrsao 2
2026-10-08 14:02:01 +02:00

49 lines
7.4 KiB
Markdown

# Integração do modelo de negócios
O SQL recebido foi convertido numa migração incremental para PostgreSQL/PostGIS. `existing_businesses` continua a ser a entidade canónica dos anúncios de negócios; não é criado outro catálogo de oportunidades. `interest_requests` continua a guardar manifestações de interesse já recebidas.
## Correspondências
| SQL recebido | Modelo actual |
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `business.parties` | Contas autenticadas em `users`; proponentes institucionais em `organizations`; perfis de investimento em `investors` e `investor_accounts`. Não é criada uma segunda tabela de identidade. |
| `business.opportunities` | `existing_businesses`: `tracking_code` usa `code`; proponente/criador usa `owner_user_id`; proprietário institucional usa `organization_id`; sector usa `sector_id`; versão usa `version_no`. |
| `business.opportunity_locations` | Nova tabela de relações `existing_business_locations`, ligada a `geo_locations` por UUID e com validação da hierarquia e geometria PostGIS. |
| `business.assets` | Campos tipados adicionais em `existing_business_objects`; o `payload` cifrado actual continua a guardar pormenores privados. |
| `business.rights` | Nova tabela `existing_business_rights`, ligada ao negócio e, quando aplicável, ao objecto. O detalhe reservado fica em `confidential_payload`, que os serviços devem cifrar. |
| `business.documents` | `documents` actual (`file_name`, `media_type`, `storage_key`, `sha256`, `status` e `data_classification`), com metadados adicionais; nova tabela de ligação ao negócio ou ao pedido de interesse. |
| `business.investor_profiles` | Campos de perfil em `investors`, cuja ligação à conta autenticada já existe em `investor_accounts`. |
| `business.interests` | `interest_requests`; acrescenta alvo `existing_business_id`, perfil do investidor, modalidade, montantes e atribuição. `opportunity_id` continua a referir-se ao catálogo público de investimentos, e uma submissão só pode indicar um desses dois alvos. |
| `business.consents` | `consents` actual, com alvo opcional e versão da política; os estados existentes `granted`/`withdrawn` mantêm-se como fonte canónica. |
| `business.workflow_transitions` | Histórico actual de revisões/reviews de negócios mais `business_workflow_transitions` para transições de negócios e pedidos de interesse. |
| `business.tasks` / `business.outbox_messages` | `tasks` e `outbox_events` existentes recebem campos adicionais; não são criadas filas paralelas. |
| `business.crm_links` | Nova tabela `external_record_links` para mapear identificadores remotos sem duplicar os registos de CRM. |
Campos confidenciais já protegidos no `payload` cifrado não são copiados para colunas em texto aberto. O campo `public_title` fica separado para publicação futura; esta migração não publica negócios nem muda a máquina de estados da aplicação.
## Migração e reversão
Aplicar em produção depois do backup normal da base:
```sh
php artisan migrate --force
```
A reversão remove apenas colunas e tabelas novas, e recusa prosseguir quando já houver dados nelas. Não executa `DROP SCHEMA ... CASCADE` e não remove dados existentes.
Esta entrega altera o esquema e a serialização do modelo. Os endpoints/formulários para gerir todas as novas relações, estados de aprovação, documentos e tarefas requerem implementação incremental própria; o SQL por si só não os activa.
## Arquitetura da aplicação (opção 1)
A implementação da proposta reutiliza os serviços e modelos que já existem, sem introduzir `Opportunity`, `Interest`, `Party` ou `OutboxMessage` paralelos:
| Responsabilidade proposta | Implementação no portal |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Criar e actualizar rascunhos | `ExistingBusinessDrafts`, usado pela API autenticada `api/v1/existing-business/listings`. |
| Submeter e rever anúncios | `ExistingBusinessIntake`, com autorização via `ExistingBusinessPolicy`, controlo de versão e histórico cifrado. |
| Pedidos de interesse idempotentes | `InterestRequestController` e `InterestSubmission`; eventos são gravados na outbox existente. |
| Integração CRM | Cliente seguro `SuiteCrmClient`; a outbox existente usa `aggregate_type`, `aggregate_id`, `event_type`, `payload` e estados `pending/published/failed`. |
| Estados tipados | Enums `OpportunityStatus` e `InterestStatus` em `app/Domain`, mantendo os valores de estado já persistidos. |
Os estados adicionais do enum `OpportunityStatus` alimentam agora as etapas de triagem, revisão, duas aprovações e publicação de `ExistingBusinessIntake`. A publicação usa uma projecção pública separada e allowlist de campos. As manifestações de interesse têm uma máquina de estados própria em `InterestWorkflow`; transições, notas cifradas e prazos são guardados no histórico comum. Isto ainda não constitui uma integração CRM em background, SLA automatizado, upload/scanner de documentos ou autorização institucional para publicar dados reais.