vrsao 2
tests / ci (push) Canceled after 0s

This commit is contained in:
2026-10-08 14:02:01 +02:00
parent bdd766c68a
commit 1106509116
354 changed files with 48275 additions and 24635 deletions
+4
View File
@@ -34,6 +34,10 @@ final class EvidenceRepository
if (! empty($filters['nature'])) {
$builder->where('s.nature', $filters['nature']);
}
if ($filters['public_only'] ?? false) {
$builder->where('d.data_classification', 'public')->where('d.rights_status', '!=', 'restricted')
->whereExists(fn ($q) => $q->selectRaw('1')->from('portal_resources as r')->whereColumn('r.document_id', 'd.id')->where('r.published', true)->where('r.rights_status', '!=', 'restricted'));
}
return array_values($builder->orderByDesc('rank')->orderBy('c.id')->limit((int) config('investmoz_ai.retrieval_limit', 5))
->get()->map(fn ($row) => (array) $row)->all());
+255
View File
@@ -0,0 +1,255 @@
<?php
namespace App\Services\Ai;
use App\Models\CrmTask;
use App\Models\InvestmentSubmission;
use App\Models\SimulationFormDraft;
use App\Models\User;
use App\Services\InvestmentGeography;
use App\Services\VirtualDesk;
use Illuminate\Support\Arr;
use Illuminate\Support\Carbon;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Schema;
use Illuminate\Support\Facades\Validator;
use Illuminate\Validation\Rule;
class InvestorGuidance
{
public function __construct(private VirtualDesk $desk, private InvestorGuidanceRules $rules) {}
public function installed(): bool
{
return Schema::hasColumn('tasks', 'desk_case_id');
}
/** Reads each linked module with its own owner rule; case membership does not grant access to a private simulator. */
/** @return array<string,mixed> */
public function context(User $actor, \stdClass $case): array
{
$base = $this->desk->decode($case->payload);
$facts = Arr::only($base['guidance']['assumptions'] ?? [], InvestorGuidanceRules::FIELDS);
$consulted = [];
$unavailable = [];
$financialDraft = null;
$checks = [];
$revision = ['case' => (int) $case->version];
$submission = $case->submission_id ? InvestmentSubmission::where('id', $case->submission_id)->where('user_id', $actor->id)->first() : null;
if ($submission) {
$input = $submission->payload;
$mapped = ['project_title' => $input['title'] ?? $case->title, 'project_summary' => $input['objective'] ?? '',
'activity' => $input['activity_description'] ?? '', 'schedule' => $input['schedule'] ?? ''];
$facts = [...$mapped, ...$facts];
$consulted[] = ['module' => 'investment_submission', 'id' => $submission->id, 'version' => $submission->version, 'date' => $submission->updated_at?->toIso8601String(), 'status' => 'investor_declaration'];
$revision['submission'] = $submission->version;
} elseif ($case->submission_id) {
$unavailable[] = 'investment_submission_permission_or_availability';
}
if ($case->simulation_id) {
$draft = SimulationFormDraft::where('id', $case->simulation_id)->where('owner_user_id', $actor->id)->whereNull('deleted_at')
->where(fn ($q) => $q->whereNull('expires_at')->orWhere('expires_at', '>', now()))->first();
if ($draft) {
$economic = SimulationFormDraft::decryptSnapshot($draft->economic_snapshot);
$mapped = Arr::only($economic, InvestorGuidanceRules::FIELDS);
$mapped['activity'] = $economic['selection_labels']['activity_id'] ?? $economic['products_services'] ?? '';
// A market assumption is not evidence of demand.
if (! empty($economic['market_source'])) {
$mapped['market_evidence'] = $economic['market_source'];
}
$mapped['location'] = $economic['selection_labels']['province_id'] ?? '';
$mapped['location_evidence'] = $economic['location_rationale'] ?? '';
if (! empty($economic['skills_needed'])) {
$mapped['resource_plan'] = $economic['skills_needed'];
}
$checks = $this->catalogueChecks($economic);
$facts = [...$mapped, ...$facts];
// Only economic fields needed by existing deterministic calculators, never personal_snapshot.
$financialDraft = Arr::only($economic, ['business_plan_snapshot', 'financial_tools_snapshot', 'currency']);
$consulted[] = ['module' => 'simulation_form_draft', 'id' => $draft->id, 'version' => $draft->version_no, 'hash' => $draft->snapshot_sha256,
'date' => $draft->updated_at?->toIso8601String(), 'status' => 'declared_assumptions_and_versioned_snapshots'];
$revision['simulation'] = [$draft->version_no, $draft->snapshot_sha256];
} else {
$unavailable[] = 'simulation_draft_permission_or_availability';
}
}
$facts['project_title'] = $facts['project_title'] ?? $case->title;
$evidence = app(InvestorGuidanceEvidence::class)->forCase($actor, $case, $this->desk);
$fingerprint = hash('sha256', json_encode([InvestorGuidanceRules::VERSION, $revision, Arr::sortRecursive($facts), $checks, $evidence], JSON_THROW_ON_ERROR));
return ['facts' => $facts, 'consulted' => $consulted, 'unavailable' => $unavailable, 'financial_draft' => $financialDraft, 'fingerprint' => $fingerprint, 'catalogue_checks' => $checks, 'evidence' => $evidence];
}
/** @param array<string,mixed> $economic
* @return list<array<string,mixed>> */
private function catalogueChecks(array $economic): array
{
$checks = [];
if (! empty($economic['activity_id'])) {
$activity = DB::table('economic_activities as a')->join('reference_catalog_versions as v', 'v.id', '=', 'a.catalog_version_id')
->where('a.id', $economic['activity_id'])->where('a.status', 'published')->where('v.status', 'published')
->whereDate('a.valid_from', '<=', today())->where(fn ($q) => $q->whereNull('a.valid_to')->orWhereDate('a.valid_to', '>', today()))
->first(['a.id', 'a.sector_id', 'a.catalog_version_id']);
$classification = ! $activity || empty($economic['sector_id']) ? 'insufficient_information'
: ((int) $activity->sector_id === (int) $economic['sector_id'] ? 'catalogue_consistent' : 'documented_incompatibility');
$checks[] = ['code' => 'activity_sector', 'classification' => $classification, 'restriction' => false,
'explanation' => match ($classification) {
'documented_incompatibility' => 'A actividade e o sector seleccionados não correspondem no catálogo publicado consultado.',
'catalogue_consistent' => 'Actividade e sector correspondem no catálogo consultado; isto não prova mercado ou elegibilidade.',
default => 'Sem referência actual autorizada suficiente para verificar actividade e sector.',
}, 'source' => $activity ? ['module' => 'economic_activities', 'id' => $activity->id, 'version_id' => $activity->catalog_version_id] : null];
}
$parents = ['district_id' => 'province_id', 'admin_post_id' => 'district_id', 'locality_id' => 'admin_post_id'];
foreach ($parents as $child => $parent) {
if (empty($economic[$child])) {
continue;
}
$location = app(InvestmentGeography::class)->publicReferences()->where('id', $economic[$child])->first(['id', 'parent_id']);
$classification = ! $location || empty($economic[$parent]) ? 'insufficient_information'
: ($location->parent_id === $economic[$parent] ? 'catalogue_consistent' : 'documented_incompatibility');
$checks[] = ['code' => 'territory_'.$child, 'classification' => $classification, 'restriction' => false,
'explanation' => match ($classification) {
'documented_incompatibility' => 'A hierarquia territorial declarada contradiz a referência publicada consultada.',
'catalogue_consistent' => 'Hierarquia territorial coerente na referência consultada; disponibilidade e infraestrutura continuam por confirmar.',
default => 'Referência territorial insuficiente ou indisponível para esta verificação.',
}, 'source' => $location ? ['module' => 'geo_locations', 'id' => $location->id, 'parent_id' => $location->parent_id] : null];
}
return $checks;
}
/** @return array<string,mixed> */
public function view(User $actor, string $id): array
{
$case = $this->desk->case($actor, $id);
abort_unless($this->installed(), 503, 'A extensão do acompanhamento aguarda instalação autenticada.');
$context = $this->context($actor, $case);
$choices = [];
foreach (DB::table('desk_events')->where('case_id', $id)->where('action', 'recommendation_reviewed')->orderBy('event_order')->get() as $event) {
$data = $this->desk->decode($event->payload);
$choices[$data['code']] = [...$data, 'actor_id' => $event->actor_id, 'date' => $event->created_at, 'stale' => $data['context_hash'] !== $context['fingerprint']];
}
$actions = ['opportunities' => '/oportunidades', 'locations' => '/oportunidades?view=map', 'partners' => '/parcerias',
'documents' => '/documentos', 'plan' => $case->submission_id && (int) $case->user_id === $actor->id ? '/investidor/manifestacoes/'.$case->submission_id : '/balcao-virtual/dossiers/'.$id,
'simulator' => '/simulador-fiscal', 'support' => '/balcao-virtual/dossiers/'.$id];
// The simulator recovers its current owner-scoped draft; do not pass private payload in URLs.
if ($case->simulation_id && $context['financial_draft'] !== null) {
$actions['plan'] = '/simulador-fiscal';
}
$phases = $this->rules->evaluate($context['facts'], $context['evidence']);
foreach ($phases as &$phase) {
foreach ($phase['recommendations'] as &$recommendation) {
$recommendation['review'] = $choices[$recommendation['code']] ?? null;
$recommendation['href'] = $actions[$recommendation['action']];
}
unset($recommendation);
}
unset($phase);
$tasks = DB::table('tasks as t')->leftJoin('users as u', 'u.id', '=', 't.assignee_user_id')->where('t.desk_case_id', $id)->whereNull('t.deleted_at')
->when(! $this->desk->owns($actor, $case, false) && ! $actor->can('manage-portal'), fn ($q) => $q->where('t.assignee_user_id', $actor->id))
->get(['t.id', 't.title', 't.status', 't.due_at', 't.version_no', 't.desk_request_id', 't.accepted_by', 't.accepted_at', 't.assignee_user_id', 'u.name as assignee_name', 't.external_sync_status']);
return ['version' => $case->version, 'rules_version' => InvestorGuidanceRules::VERSION, 'computed_at' => now()->toIso8601String(),
...$context, 'phases' => $phases, 'tasks' => $tasks, 'actions' => $actions, 'can_write' => $this->desk->owns($actor, $case),
'external_ai' => ['status' => 'not_configured', 'model' => null, 'consulted' => []],
'calculator_versions' => ['business_financial_plan' => hash_file('sha256', resource_path('js/lib/business-financial-plan.ts')), 'financial_calculators' => hash_file('sha256', resource_path('js/lib/financial-calculators.ts')), 'project_dossier' => hash_file('sha256', resource_path('js/lib/project-dossier.ts'))],
'crm' => ['internal' => 'available', 'external' => 'out_of_scope', 'reason' => 'O acompanhamento usa o CRM interno existente. A sincronização externa está fora desta fase; nenhum contacto, mensagem ou documento é transmitido.']];
}
/** @param array<string,mixed> $input */
public function assumptions(User $actor, string $id, array $input): void
{
$rules = ['version' => 'required|integer|min:1', 'assumptions' => ['required', 'array:'.implode(',', InvestorGuidanceRules::FIELDS)]];
foreach (InvestorGuidanceRules::FIELDS as $field) {
$rules['assumptions.'.$field] = in_array($field, ['expected_start_date', 'ready_date', 'funding_ready_date', 'completion_date'], true) ? 'nullable|date_format:Y-m-d' : 'nullable|string|max:3000';
}
$data = Validator::make($input, $rules)->validate();
DB::transaction(function () use ($actor, $id, $data) {
$case = $this->desk->case($actor, $id, true, true);
abort_if($case->closed_at, 409);
abort_unless((int) $case->version === (int) $data['version'], 409, 'Dossier alterado; recarregue antes de corrigir.');
$base = $this->desk->decode($case->payload);
$base['guidance']['assumptions'] = $data['assumptions'];
DB::table('desk_cases')->where('id', $id)->update(['payload' => $this->desk->encode($base), 'version' => $case->version + 1, 'updated_at' => now()]);
$this->desk->event(DB::table('desk_cases')->where('id', $id)->first(), $actor, 'assumptions_corrected', ['assumptions' => $data['assumptions'], 'origin' => 'investor_correction_not_official_data']);
});
}
/** @param array<string,mixed> $input */
public function feedback(User $actor, string $id, array $input): void
{
$data = Validator::make($input, ['code' => 'required|string|max:100', 'context_hash' => 'required|string|size:64',
'decision' => ['required', Rule::in(['accepted', 'rejected', 'corrected'])], 'reason' => 'required|string|min:3|max:3000'])->validate();
DB::transaction(function () use ($actor, $id, $data) {
$case = $this->desk->case($actor, $id, true, true);
abort_if($case->closed_at, 409);
$view = $this->view($actor, $id);
abort_unless(hash_equals($view['fingerprint'], $data['context_hash']), 409, 'Pressupostos alterados; reveja a recomendação actual.');
$recommendations = array_merge(...array_column($view['phases'], 'recommendations'));
abort_unless(in_array($data['code'], array_column($recommendations, 'code'), true), 422);
$this->desk->event($case, $actor, 'recommendation_reviewed', [...$data, 'rules_version' => InvestorGuidanceRules::VERSION, 'creates_task' => false]);
});
}
/** @param array<string,mixed> $input */
public function acceptTask(User $actor, string $id, array $input): CrmTask
{
$data = Validator::make($input, ['code' => 'required|string|max:100', 'context_hash' => 'required|string|size:64', 'consent' => 'accepted',
'due_at' => 'required|date|after:now', 'request_id' => 'nullable|uuid'])->validate();
return DB::transaction(function () use ($actor, $id, $data) {
$case = $this->desk->case($actor, $id, true, true);
abort_if($case->closed_at, 409);
$view = $this->view($actor, $id);
abort_unless(hash_equals($view['fingerprint'], $data['context_hash']), 409);
$recommendations = array_merge(...array_column($view['phases'], 'recommendations'));
$suggestion = collect($recommendations)->firstWhere('code', $data['code']);
abort_unless($suggestion && ($suggestion['review']['decision'] ?? null) === 'accepted' && ! $suggestion['review']['stale'], 422, 'Aceite a recomendação actual antes de assumir a tarefa.');
if ($data['request_id'] ?? null) {
$request = $this->desk->request($actor, $data['request_id'], true);
abort_unless($request->case_id === $id, 422);
}
// One accepted action per suggestion, even after corrections or retries.
$existing = CrmTask::where('desk_case_id', $id)->where('guidance_key', $data['code'])->first();
if ($existing) {
abort_unless($existing->getAttribute('desk_request_id') === ($data['request_id'] ?? null)
&& (int) $existing->getAttribute('accepted_by') === $actor->id && $existing->due_at !== null && $existing->due_at->equalTo(Carbon::parse($data['due_at'])), 409, 'A tarefa já foi assumida com outros dados; reveja o registo existente.');
return $existing;
}
$task = CrmTask::create(['desk_case_id' => $id, 'desk_request_id' => $data['request_id'] ?? null, 'guidance_key' => $data['code'],
'title' => $suggestion['explanation'], 'status' => 'open', 'due_at' => $data['due_at'], 'assignee_user_id' => $actor->id,
'accepted_by' => $actor->id, 'accepted_at' => now(), 'external_sync_status' => 'pending_authorization',
'source_system' => 'investor-guidance', 'data_classification' => 'confidential']);
$this->desk->event($case, $actor, 'guidance_task_accepted', ['task_id' => $task->id, 'code' => $data['code'], 'context_hash' => $data['context_hash'], 'due_at' => $data['due_at'], 'scope' => 'internal_crm']);
return $task;
});
}
/** @param array<string,mixed> $input */
public function updateTask(User $actor, string $id, string $taskId, array $input): void
{
$data = Validator::make($input, ['version' => 'required|integer|min:1', 'status' => ['required', Rule::in(['open', 'in_progress', 'done', 'cancelled'])],
'reason' => 'required|string|min:3|max:3000', 'assignee_user_id' => 'nullable|integer|exists:users,id', 'due_at' => 'nullable|date|after:now'])->validate();
DB::transaction(function () use ($actor, $id, $taskId, $data) {
$case = $this->desk->case($actor, $id);
$task = CrmTask::where('desk_case_id', $id)->whereKey($taskId)->lockForUpdate()->firstOrFail();
abort_unless($actor->can('manage-portal') || (int) $task->getAttribute('assignee_user_id') === $actor->id, 403);
abort_unless((int) $task->getAttribute('version_no') === (int) $data['version'], 409);
$updates = ['status' => $data['status'], 'version_no' => $data['version'] + 1];
if ($data['assignee_user_id'] ?? null) {
abort_unless($actor->can('manage-portal'), 403);
$assignee = User::where('id', $data['assignee_user_id'])->firstOrFail();
abort_unless($assignee->hasVerifiedEmail(), 422, 'Responsável sem conta verificada.');
abort_unless($assignee->can('manage-portal') || DB::table('desk_requests')->where('case_id', $id)->where('analyst_id', $assignee->id)->exists() || $this->desk->owns($assignee, $case), 422, 'Responsável sem acesso ao dossier.');
$updates['assignee_user_id'] = $assignee->id;
}
if ($data['due_at'] ?? null) {
$updates['due_at'] = $data['due_at'];
}
$task->update($updates);
$this->desk->event($case, $actor, 'guidance_task_updated', ['task_id' => $task->id, ...$data, 'kind' => $actor->can('manage-portal') ? 'responsible_response' : 'investor_action']);
});
}
}
@@ -0,0 +1,84 @@
<?php
namespace App\Services\Ai;
use App\Models\User;
use App\Services\VirtualDesk;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Storage;
class InvestorGuidanceEvidence
{
public const FIELDS = ['market_evidence', 'location_evidence', 'resource_evidence', 'funding_evidence'];
/** @return array<string,array<string,mixed>> */
public function forCase(User $actor, \stdClass $case, VirtualDesk $desk): array
{
$privateScope = ! $desk->owns($actor, $case, false) && ! $actor->can('manage-portal');
$documents = DB::table('desk_documents as l')->join('documents as d', 'd.id', '=', 'l.document_id')->where('l.case_id', $case->id)->whereNull('d.deleted_at')
->when($privateScope, fn ($q) => $q->where(fn ($p) => $p->whereNull('l.request_id')->orWhereIn('l.request_id', DB::table('desk_requests')->where('analyst_id', $actor->id)->select('id'))))
->get(['l.id as link_id', 'l.document_id', 'l.category', 'l.valid_until', 'd.file_name', 'd.version_no', 'd.sha256', 'd.status', 'd.malware_scan_status', 'd.malware_scanned_sha256', 'd.storage_key']);
$reviews = DB::table('desk_events as e')->join('users as u', 'u.id', '=', 'e.actor_id')->where('e.case_id', $case->id)->where('e.action', 'document_reviewed')
->when($privateScope, fn ($q) => $q->where(fn ($p) => $p->whereNull('e.request_id')->orWhereIn('e.request_id', DB::table('desk_requests')->where('analyst_id', $actor->id)->select('id'))))
->orderByDesc('e.event_order')->get(['e.id', 'e.payload', 'e.created_at', 'e.actor_id', 'u.name']);
$result = [];
foreach (self::FIELDS as $field) {
$records = [];
foreach ($documents as $doc) {
$latest = null;
foreach ($reviews as $review) {
$payload = $desk->decode($review->payload);
if (($payload['link_id'] ?? null) === $doc->link_id) {
$latest = ['id' => $review->id, 'author_id' => $review->actor_id, 'author' => $review->name, 'date' => $review->created_at, 'payload' => $payload];
break;
}
}
if ($doc->category !== $field && ! ($latest && in_array($field, $latest['payload']['supports'] ?? [], true))) {
continue;
}
// A later review replaces the earlier scope. Merely choosing a
// document category does not verify a preparation assumption.
if ($latest && ! in_array($field, $latest['payload']['supports'] ?? [], true)) {
$latest = null;
}
$state = 'attached_unchecked';
if ($doc->valid_until && $doc->valid_until < now()->toDateString()) {
$state = 'expired';
} elseif ($latest && (($latest['payload']['sha256'] ?? null) !== trim($doc->sha256) || ($latest['payload']['document_version'] ?? null) !== (int) $doc->version_no)) {
$state = 'superseded';
} elseif ($latest) {
$path = realpath(Storage::disk('local')->path($doc->storage_key));
$root = realpath(Storage::disk('local')->path(''));
if (! $path || ! $root || ! str_starts_with($path, $root.DIRECTORY_SEPARATOR) || ! is_file($path) || ! is_string($hash = hash_file('sha256', $path)) || ! hash_equals(trim($doc->sha256), $hash)) {
$state = 'superseded';
} elseif ($doc->status !== 'active' || $doc->malware_scan_status !== 'clean' || trim($doc->sha256) !== $doc->malware_scanned_sha256) {
$state = 'technical_unavailable';
} else {
$state = match ($latest['payload']['outcome'] ?? '') {
'internal_verified' => 'internally_verified',
'contradiction_identified' => 'contradiction',
default => 'issue_identified',
};
}
}
$records[] = ['document_id' => $doc->document_id, 'link_id' => $doc->link_id, 'name' => $doc->file_name, 'state' => $state, 'version' => (int) $doc->version_no, 'hash' => trim($doc->sha256), 'valid_until' => $doc->valid_until,
'review' => $latest ? ['event_id' => $latest['id'], 'author_id' => $latest['author_id'], 'author' => $latest['author'], 'date' => $latest['date'], 'what_checked' => $latest['payload']['what_checked'], 'evidence' => $latest['payload']['evidence'], 'scope' => $latest['payload']['scope']] : null];
}
if ($records) {
// A specific current contradiction takes precedence; other valid evidence
// remains visible instead of erasing expired or replaced originals.
$states = array_column($records, 'state');
$state = 'attached_unchecked';
foreach (['contradiction', 'internally_verified', 'issue_identified', 'superseded', 'expired', 'technical_unavailable'] as $candidate) {
if (in_array($candidate, $states, true)) {
$state = $candidate;
break;
}
}
$result[$field] = ['state' => $state, 'documents' => $records];
}
}
return $result;
}
}
+121
View File
@@ -0,0 +1,121 @@
<?php
namespace App\Services\Ai;
/** Internal preparation rules; never calculate tax, returns or eligibility. */
class InvestorGuidanceRules
{
public const VERSION = 'investor-guidance-2026-10-08-v3';
public const FIELDS = ['project_title', 'project_summary', 'activity', 'target_customers', 'market_evidence', 'location',
'location_evidence', 'resource_plan', 'resource_evidence', 'funding_evidence', 'expected_start_date', 'ready_date', 'schedule',
'demand_quantity', 'capacity_quantity', 'quantity_unit', 'quantity_period', 'resources_required', 'resources_available', 'resource_unit',
'funding_required', 'funding_committed', 'funding_currency', 'funding_ready_date', 'completion_date'];
/** @param array<string,mixed> $facts
* @param array<string,array<string,mixed>> $evidence
* @return list<array<string,mixed>> */
public function evaluate(array $facts, array $evidence = []): array
{
$phases = [
'idea' => ['Definir a actividade e o objectivo', ['project_title', 'project_summary', 'activity'], 'Confirme o que pretende produzir ou prestar.', 'plan'],
'market' => ['Documentar clientes e hipóteses de mercado', ['target_customers', 'market_evidence'], 'Reúna evidência de clientes; uma hipótese não demonstra procura.', 'opportunities'],
'location' => ['Comparar locais e requisitos da actividade', ['location', 'location_evidence'], 'Confirme terreno, acesso, infraestrutura e licenciamento para cada alternativa.', 'locations'],
'resources' => ['Preparar recursos e equipa', ['resource_plan', 'resource_evidence'], 'Distinga recursos declarados de disponibilidade comprovada.', 'partners'],
'finance' => ['Explorar financiamento e cenários', ['funding_evidence'], 'Reveja os pressupostos e os cenários no simulador determinístico.', 'simulator'],
'execution' => ['Reconciliar calendário e dependências', ['expected_start_date', 'ready_date', 'schedule'], 'Confirme datas, dependências e responsáveis antes de assumir marcos.', 'plan'],
'support' => ['Preparar o pedido e acompanhar a resposta', [], 'Prepare um rascunho no Balcão; reveja e submeta pessoalmente.', 'support'],
];
$result = [];
foreach ($phases as $code => [$objective, $fields, $explanation, $action]) {
$known = [];
$unknown = [];
$phaseEvidence = [];
$risks = [];
foreach ($fields as $field) {
$value = trim((string) ($facts[$field] ?? ''));
$record = $evidence[$field] ?? null;
$state = $record['state'] ?? ($value !== '' ? 'investor_declared_not_verified' : 'absent');
if (in_array($field, InvestorGuidanceEvidence::FIELDS, true)) {
$phaseEvidence[] = ['field' => $field, 'state' => $state, 'documents' => $record['documents'] ?? []];
if ($state !== 'internally_verified') {
$message = match ($state) {
'absent' => 'Ainda não existe informação ou documento para este pressuposto.',
'investor_declared_not_verified' => 'A declaração do investidor ainda não foi conferida.',
'attached_unchecked' => 'Existe um documento associado, sem conferência interna deste pressuposto.',
'expired' => 'A validade documental registada terminou; actualize a evidência.',
'superseded' => 'O ficheiro ou a versão mudou depois da conferência; é necessária nova análise.',
'contradiction' => 'Uma conferência interna identificou contradição no âmbito descrito.',
'issue_identified' => 'Uma conferência interna identificou um problema no âmbito descrito.',
default => 'A evidência não está disponível para utilização; consulte o motivo documental.',
};
$risks[] = ['code' => $field.'_'.$state, 'classification' => $state === 'contradiction' ? 'documented_contradiction' : 'insufficient_information', 'explanation' => $message, 'field' => $field, 'restriction' => false];
}
}
if ($value !== '') {
$known[] = ['field' => $field, 'value' => $value, 'status' => 'investor_declared_not_verified'];
} elseif (! $record) {
$unknown[] = $field;
}
}
$result[] = ['id' => $code, 'objective' => $objective, 'known' => $known, 'questions' => $unknown,
'recommendations' => [[
'code' => $code.'_preparation', 'kind' => 'automatic_recommendation', 'classification' => $unknown ? 'insufficient_information' : 'verification_required',
'explanation' => $explanation, 'action' => $action, 'assumptions' => $known,
'source' => ['identifier' => self::VERSION, 'reference' => 'app/Services/Ai/InvestorGuidanceRules.php#'.$code, 'date' => '2026-10-08', 'nature' => 'internal_preparation_rule'],
'limitations' => ['Uma conferência interna só sustenta o âmbito descrito pelo verificador; não aprova procura, infraestrutura, financiamento, registo ou licença institucional.', 'Sem previsão de sucesso, taxa fiscal ou elegibilidade inferida.'],
]], 'evidence' => $phaseEvidence, 'risks' => $risks];
}
if (($facts['expected_start_date'] ?? '') && ($facts['ready_date'] ?? '') && $facts['expected_start_date'] < $facts['ready_date']) {
$result[5]['risks'][] = ['code' => 'schedule_contradiction', 'classification' => 'declared_contradiction',
'explanation' => 'O início indicado antecede a disponibilidade declarada dos recursos.', 'basis' => ['expected_start_date' => $facts['expected_start_date'], 'ready_date' => $facts['ready_date']],
'restriction' => false];
}
$result[4]['risks'][] = ['code' => 'tax_eligibility_not_inferred', 'classification' => 'insufficient_information', 'explanation' => 'A evidência do financiamento não determina taxas fiscais ou elegibilidade. Consulte os pressupostos, fontes e versões no simulador.', 'restriction' => false];
foreach ([
[1, 'demand_quantity', 'capacity_quantity', ['quantity_unit', 'quantity_period'], 'A procura declarada excede a capacidade declarada para a mesma unidade e período.'],
[3, 'resources_required', 'resources_available', ['resource_unit'], 'Os recursos disponíveis declarados são inferiores aos necessários declarados.'],
[4, 'funding_required', 'funding_committed', ['funding_currency'], 'O financiamento comprometido declarado é inferior ao necessário declarado na mesma moeda.'],
] as [$phase, $required, $available, $scope, $explanation]) {
$values = array_intersect_key($facts, array_flip([$required, $available, ...$scope]));
if (! array_filter($values, fn ($value) => $value !== null && $value !== '')) {
continue;
}
$complete = true;
foreach ([$required, $available, ...$scope] as $field) {
if (! isset($facts[$field]) || trim((string) $facts[$field]) === '') {
$complete = false;
}
}
// Compare declared magnitudes only: this is no forecast, valuation or financial calculation.
$left = $facts[$required] ?? null;
$right = $facts[$available] ?? null;
$valid = is_scalar($left) && is_scalar($right)
&& preg_match('/^\d{1,12}(\.\d{1,2})?$/', (string) $left)
&& preg_match('/^\d{1,12}(\.\d{1,2})?$/', (string) $right);
if (! $complete || ! $valid) {
$result[$phase]['risks'][] = ['code' => $required.'_comparison_incomplete', 'classification' => 'insufficient_information',
'explanation' => 'Faltam valores comparáveis, unidade, período ou moeda para esta comparação.', 'basis' => $values, 'restriction' => false];
} elseif ($this->declaredMagnitude((string) $left) > $this->declaredMagnitude((string) $right)) {
$result[$phase]['risks'][] = ['code' => $required.'_declared_gap', 'classification' => 'declared_contradiction',
'explanation' => $explanation.' Estes valores são declarações, não disponibilidade comprovada.', 'basis' => $values, 'restriction' => false];
}
}
foreach ([['completion_date', 'expected_start_date', 'A conclusão declarada antecede o início.'],
['expected_start_date', 'funding_ready_date', 'O início declarado antecede a disponibilidade declarada do financiamento.']] as [$first, $second, $explanation]) {
if (! empty($facts[$first]) && ! empty($facts[$second]) && $facts[$first] < $facts[$second]) {
$result[5]['risks'][] = ['code' => $first.'_'.$second.'_contradiction', 'classification' => 'declared_contradiction',
'explanation' => $explanation, 'basis' => [$first => $facts[$first], $second => $facts[$second]], 'restriction' => false];
}
}
return $result;
}
private function declaredMagnitude(string $value): int
{
$parts = explode('.', $value);
return (int) $parts[0] * 100 + (int) str_pad($parts[1] ?? '', 2, '0');
}
}