248 lines
20 KiB
PHP
248 lines
20 KiB
PHP
<?php
|
|
namespace App\Modules\Services;
|
|
|
|
use App\Modules\Identity\Services\Audit;
|
|
use App\Modules\Identity\Services\Permissions;
|
|
use App\Shared\Context\CompanyContext;
|
|
use App\Shared\Testing\TestingDatabaseGuard;
|
|
use Brick\Math\BigDecimal;
|
|
use Brick\Math\RoundingMode;
|
|
use Illuminate\Support\Facades\DB;
|
|
use Illuminate\Support\Facades\Validator;
|
|
|
|
/** Isolated operational subledger. Never invokes fiscal, banking or accounting consumers. */
|
|
final class ServiceReceivables
|
|
{
|
|
public const POLICY='SGF-RECEIVABLES-SIM-v1';
|
|
public const NOTICE='TESTE — SEM VALIDADE FISCAL';
|
|
public const SIMULATION='SIMULAÇÃO — SEM MOVIMENTAÇÃO DE DINHEIRO';
|
|
public function __construct(private CompanyContext $context, private Permissions $permissions) {}
|
|
public static function guard(): void
|
|
{
|
|
abort_unless(ServiceCalculation::isolated(),403,'Recebimentos e reconciliação disponíveis exclusivamente em testes isolados.');
|
|
TestingDatabaseGuard::assertSafe();
|
|
}
|
|
private function scope(int $actor,string $right): array
|
|
{
|
|
$s=$this->context->identifiers()+['unit_id'=>$this->context->unitId()];
|
|
abort_unless($actor===$this->context->userId() && $s['unit_id']!==null,403);
|
|
$this->context->selectFor($actor,$s['tenant_id'],$s['company_id'],$s['unit_id']);
|
|
foreach (['view',$right] as $r) $this->permissions->require($actor,$s['tenant_id'],$s['company_id'],'service_receivables.'.$r,$s['unit_id']);
|
|
return $s;
|
|
}
|
|
public static function money(mixed $value,bool $positive=true): string
|
|
{
|
|
$v=DraftValues::decimal($value,'amount');
|
|
abort_unless($v!==null,422,'Montante explícito necessário.');
|
|
$n=BigDecimal::of($v);
|
|
abort_if(($positive && $n->isLessThanOrEqualTo(0)) || $n->getScale()>2,422,'Use um montante positivo exactamente representável a duas casas; sem truncagem.');
|
|
return (string)$n->toScale(2,RoundingMode::UNNECESSARY);
|
|
}
|
|
private function validate(array $d,array $rules): array
|
|
{
|
|
abort_if(array_diff(array_keys($d),array_keys($rules)),422,'Campo protegido ou não suportado.');
|
|
return Validator::make($d,$rules)->validate();
|
|
}
|
|
private function json(mixed $d): string { return json_encode($d,JSON_THROW_ON_ERROR|JSON_UNESCAPED_UNICODE); }
|
|
private function data(object $r): array { return json_decode($r->data,true,32,JSON_THROW_ON_ERROR); }
|
|
private function row(int $id,array $s,?string $kind=null): object
|
|
{
|
|
$q=DB::table('sr_records')->where($s)->where('id',$id);
|
|
if($kind) $q->where('kind',$kind);
|
|
return $q->first() ?? abort(403,'Identidade fora do âmbito ou tipo incorrecto.');
|
|
}
|
|
private function revision(int $ob): int { return DB::table('sr_effects')->where('obligation_id',$ob)->count(); }
|
|
private function command(int $actor,string $right,string $key,array $input,callable $write): array
|
|
{
|
|
self::guard(); $s=$this->scope($actor,$right);
|
|
abort_unless(preg_match('/^[A-Za-z0-9_-]{8,100}$/D',$key),422,'Chave de idempotência obrigatória.');
|
|
ksort($input); $hash=hash('sha256',$this->json($input));
|
|
return DB::transaction(function() use($actor,$right,$key,$input,$hash,$s,$write) {
|
|
// Same global order as the database guards: company, then immutable records/effects.
|
|
DB::table('companies')->where('id',$s['company_id'])->lockForUpdate()->firstOrFail();
|
|
$this->scope($actor,$right);
|
|
$old=DB::table('sr_commands')->where($s)->where(['actor_id'=>$actor,'action'=>$right,'command_key'=>$key])->first();
|
|
if($old) {
|
|
abort_unless(hash_equals($old->request_hash,$hash),409,'Chave já usada com conteúdo diferente.');
|
|
return json_decode($old->result,true,32,JSON_THROW_ON_ERROR)+['replayed'=>true];
|
|
}
|
|
$result=$write($s);
|
|
$cmd=DB::table('sr_commands')->insertGetId($s+['actor_id'=>$actor,'action'=>$right,'command_key'=>$key,'request_hash'=>$hash,'result'=>$this->json($result),'created_at'=>now()]);
|
|
Audit::record('service_receivables.'.$right,$actor,$s['tenant_id'],$s['company_id'],$s['unit_id'],details:['command_id'=>$cmd,'record_id'=>$result['id'],'simulation_only'=>true]);
|
|
$event=DB::table('sr_events')->insertGetId(['command_id'=>$cmd,'type'=>$result['event'],'schema_version'=>1,'payload'=>$this->json($s+['policy'=>self::POLICY,'command_id'=>$cmd,'actor_id'=>$actor,'result'=>$result]),'created_at'=>now()]);
|
|
DB::table('sr_outbox')->insert(['event_id'=>$event,'state'=>'captured_simulation_only']);
|
|
return $result+['replayed'=>false];
|
|
},3);
|
|
}
|
|
private function record(array $s,int $actor,string $kind,object $inv,int $client,?int $ob,?int $receipt,string $amount,string $source,string $external,array $data): array
|
|
{
|
|
abort_if(DB::table('sr_records')->where($s)->where(['kind'=>$kind,'source'=>$source,'external_id'=>$external])->exists(),409,'Acontecimento já registado; consulte a identidade original.');
|
|
if($kind==='obligation') abort_if(DB::table('sr_records')->where('invoice_id',$inv->id)->where('kind','obligation')->exists(),409,'Documento já tem obrigação.');
|
|
$origin=['invoice_id'=>$inv->id,'snapshot_sha256'=>hash('sha256',$inv->snapshot),'series'=>$inv->series_code,'number'=>$inv->number,'issued_at'=>$inv->issued_at];
|
|
$id=DB::table('sr_records')->insertGetId($s+['invoice_id'=>$inv->id,'client_id'=>$client,'obligation_id'=>$ob,'receipt_id'=>$receipt,'kind'=>$kind,'currency'=>'MZN','amount'=>$amount,'source'=>$source,'external_id'=>$external,'data'=>$this->json(array_replace($data,['policy'=>self::POLICY,'origin'=>$origin])),'version'=>1,'actor_id'=>$actor,'created_at'=>now()]);
|
|
return ['id'=>$id,'version'=>1,'event'=>$kind.'.proposed'];
|
|
}
|
|
public function propose(int $actor,array $input,string $key): array
|
|
{
|
|
self::guard();
|
|
$d=$this->validate($input,['kind'=>'required|in:obligation,receipt,observation,correction','invoice_id'=>'required|integer|min:1','obligation_id'=>'nullable|integer|min:1','receipt_id'=>'nullable|integer|min:1','currency'=>'required|in:MZN','amount'=>'nullable|string','source'=>'required|string|min:3|max:80','external_id'=>'required|string|min:3|max:100','date'=>'nullable|date_format:Y-m-d','evidence'=>'nullable|string|min:3|max:1000','due_date'=>'nullable|date_format:Y-m-d','reason'=>'nullable|string|min:3|max:1000','action'=>'nullable|in:reverse_allocation,reverse_reconcile,reverse_receipt,reduction,due','target_effect_id'=>'nullable|integer|min:1','document_ref'=>'nullable|string|max:100','line'=>'nullable|in:1','revision'=>'required|integer|min:0']);
|
|
$kind=$d['kind'];
|
|
$right=$kind==='correction'?'correction_request':'prepare';
|
|
if(isset($d['amount'])) $d['amount']=self::money($d['amount'],$kind!=='observation');
|
|
return $this->command($actor,$right,$key,$d,function($s)use($actor,$d,$kind) {
|
|
$inv=\App\Shared\Context\ModuleRecords::query('si_invoices')->where($s)->where('id',$d['invoice_id'])->first();
|
|
abort_unless($inv,403,'Documento de origem não autorizado.');
|
|
$snapshot=json_decode($inv->snapshot,true,32,JSON_THROW_ON_ERROR);
|
|
abort_unless(($snapshot['simulation_only']??false)===true && ($snapshot['notice']??'')===self::NOTICE && ($snapshot['document']['data']['currency']??'')==='MZN',422,'Origem sintética compatível necessária.');
|
|
$history=DB::table('a_history')->where($s)->where(['area'=>'billing_drafts','record_id'=>$inv->draft_id,'version'=>$snapshot['document']['draft_version']])->value('snapshot');
|
|
abort_unless($history,409,'Versão histórica da origem necessária.');
|
|
$client=(int)json_decode($history,true,32,JSON_THROW_ON_ERROR)['client_id'];
|
|
$ob=null; $receipt=null; $amount='0.00';
|
|
if($kind==='obligation') {
|
|
abort_if(!empty($d['obligation_id']) || !empty($d['receipt_id']) || $d['revision']!==0,422);
|
|
$amount=self::money($snapshot['calculation']['total_document_proposed']);
|
|
abort_unless(!isset($d['amount']) || $d['amount']===$amount,422,'Montante deve coincidir com a fotografia.');
|
|
} else {
|
|
$ob=$this->row((int)($d['obligation_id']??0),$s,'obligation');
|
|
abort_unless($ob->invoice_id===$inv->id,403);
|
|
abort_unless($d['revision']===$this->revision($ob->id),409,'Revisão desactualizada.');
|
|
abort_unless(DB::table('sr_effects')->where(['record_id'=>$ob->id,'kind'=>'open'])->exists(),409,'Obrigação ainda não aberta.');
|
|
if(!empty($d['receipt_id'])) { $receipt=$this->row($d['receipt_id'],$s,'receipt'); abort_unless($receipt->obligation_id===$ob->id,403); }
|
|
}
|
|
if(in_array($kind,['receipt','observation'])) {
|
|
abort_unless(isset($d['amount'],$d['date'],$d['evidence']),422,'Montante, data e evidência sintética são obrigatórios.');
|
|
abort_if($d['date']>now(ServiceInvoicing::ZONE)->format('Y-m-d'),422,'Data futura não comprova recebimento ou observação.');
|
|
$amount=$d['amount'];
|
|
abort_if(($kind==='receipt' && $receipt) || ($kind==='observation' && !$receipt),422);
|
|
}
|
|
if($kind==='correction') {
|
|
abort_unless(isset($d['action'],$d['reason']),422,'Acção e motivo necessários.');
|
|
if($d['action']==='reduction') {
|
|
abort_unless(isset($d['amount'],$d['document_ref'],$d['line']) && str_starts_with($d['document_ref'],'TEST-REDUCTION-'),422,'Documento redutor sintético e linha necessários.');
|
|
$amount=$d['amount'];
|
|
}
|
|
if(in_array($d['action'],['reverse_allocation','reverse_reconcile'])) {
|
|
$effect=DB::table('sr_effects')->where('obligation_id',$ob->id)->where('id',$d['target_effect_id']??0)->first();
|
|
abort_unless($effect && $effect->kind===($d['action']==='reverse_allocation'?'allocate':'reconcile'),422,'Alvo de reversão incompatível.');
|
|
$receipt=$this->row($effect->receipt_id,$s,'receipt'); $amount=$effect->amount;
|
|
}
|
|
if($d['action']==='reverse_receipt') { abort_unless($receipt,422); $amount=$receipt->amount; }
|
|
}
|
|
return $this->record($s,$actor,$kind,$inv,$client,$ob?->id,$receipt?->id,$amount,$d['source'],$d['external_id'],$d);
|
|
});
|
|
}
|
|
public function decide(int $id,int $actor,array $input,string $key): array
|
|
{
|
|
self::guard(); $s=$this->scope($actor,'view'); $r=$this->row($id,$s);
|
|
$right=$r->kind==='correction'?'correction_approve':($r->kind==='observation'?'reconcile':'confirm');
|
|
$d=$this->validate($input,['version'=>'required|integer|in:1','revision'=>'required|integer|min:0','decision'=>'required|in:approved,refused','reason'=>'required|string|min:3|max:1000']);
|
|
return $this->command($actor,$right,$key,['record_id'=>$id]+$d,function($s)use($id,$actor,$d) {
|
|
$r=$this->row($id,$s); $rd=$this->data($r); $ob=$r->kind==='obligation'?$r->id:$r->obligation_id;
|
|
abort_if($r->actor_id===$actor,403,'Confirmação/aprovação exige identidade distinta.');
|
|
abort_unless($d['revision']===$this->revision($ob),409,'Estado alterado; reveja a decisão.');
|
|
abort_if(DB::table('sr_effects')->where('record_id',$id)->where('kind','<>','allocate')->exists(),409,'Versão já tem decisão.');
|
|
$kind='refused'; $amount='0.00'; $receipt=null; $target=null;
|
|
if($d['decision']==='approved') {
|
|
if($r->kind==='obligation') { $kind='open'; $amount=$r->amount; }
|
|
if($r->kind==='receipt') { $kind='receipt_confirm'; $amount=$r->amount; }
|
|
if($r->kind==='observation') {
|
|
$receipt=$r->receipt_id; $rc=$this->row($receipt,$s,'receipt');
|
|
$diff=BigDecimal::of($rc->amount)->minus($r->amount)->abs();
|
|
$kind=$diff->isZero()?'reconcile':'divergence'; $amount=$diff->isZero()?$rc->amount:(string)$diff->toScale(2);
|
|
}
|
|
if($r->kind==='correction') {
|
|
abort_unless(($rd['revision']??-1)===$d['revision'],409,'Proposta ligada a revisão anterior; prepare nova proposta.');
|
|
$kind=$rd['action']; $amount=$r->amount; $receipt=$r->receipt_id; $target=$rd['target_effect_id']??null;
|
|
if($kind==='reduction' || $kind==='due') $receipt=null;
|
|
}
|
|
} elseif($r->kind==='observation') abort(422,'A conferência regista correspondência ou divergência; não é aprovação de recibo.');
|
|
return $this->effect($id,$ob,$receipt,$kind,$amount,$target,$d['revision'],$actor,$d+['due_date'=>$rd['due_date']??null]);
|
|
});
|
|
}
|
|
private function effect(int $record,int $ob,?int $receipt,string $kind,string $amount,?int $target,int $revision,int $actor,array $data): array
|
|
{
|
|
$state=$this->state($ob);
|
|
if($kind==='allocate') {
|
|
$r=$state['receipts'][$receipt]??abort(409,'Recebimento indisponível.');
|
|
abort_unless($r['state']==='confirmed' && BigDecimal::of($amount)->isLessThanOrEqualTo($r['available']) && BigDecimal::of($amount)->isLessThanOrEqualTo($state['balance']),409,'Sobreafectação recusada integralmente.');
|
|
}
|
|
if($kind==='reduction') abort_if(BigDecimal::of($amount)->isGreaterThan($state['balance']),409,'Liberte afectação antes da redução.');
|
|
if($kind==='reverse_receipt') {
|
|
$r=$state['receipts'][$receipt]??abort(409);
|
|
abort_unless($r['state']==='confirmed' && $r['allocated']==='0.00' && !$r['reconciled'],409,'Reverta afectações e reconciliação primeiro.');
|
|
}
|
|
if(in_array($kind,['reconcile','divergence'])) {
|
|
$r=$state['receipts'][$receipt]??abort(409);
|
|
abort_unless($r['state']==='confirmed' && !$r['reconciled'],409,'Recebimento indisponível ou já conferido.');
|
|
}
|
|
if($target) abort_if(DB::table('sr_effects')->where('target_effect_id',$target)->exists(),409,'Efeito já revertido.');
|
|
$id=DB::table('sr_effects')->insertGetId(['record_id'=>$record,'obligation_id'=>$ob,'receipt_id'=>$receipt,'kind'=>$kind,'amount'=>$amount,'target_effect_id'=>$target,'revision'=>$revision,'data'=>$this->json($data),'actor_id'=>$actor,'created_at'=>now()]);
|
|
return ['id'=>$id,'record_id'=>$record,'obligation_id'=>$ob,'event'=>$kind.'.simulation','revision'=>$revision+1];
|
|
}
|
|
public function allocate(int $id,int $actor,array $input,string $key): array
|
|
{
|
|
self::guard(); $d=$this->validate($input,['amount'=>'required|string','revision'=>'required|integer|min:0','version'=>'required|integer|in:1']);
|
|
$d['amount']=self::money($d['amount']);
|
|
return $this->command($actor,'allocate',$key,['receipt_id'=>$id]+$d,function($s)use($id,$actor,$d) {
|
|
$r=$this->row($id,$s,'receipt'); abort_unless($d['revision']===$this->revision($r->obligation_id),409,'Revisão desactualizada.');
|
|
return $this->effect($id,$r->obligation_id,$id,'allocate',$d['amount'],null,$d['revision'],$actor,[]);
|
|
});
|
|
}
|
|
private function state(int $ob,?string $cut=null): array
|
|
{
|
|
$r=DB::table('sr_records')->find($ob); $rd=$this->data($r);
|
|
$effects=DB::table('sr_effects')->where('obligation_id',$ob)->orderBy('id')->get();
|
|
$receipts=[]; $balance=BigDecimal::of($r->amount); $reduced=BigDecimal::zero(); $allocated=BigDecimal::zero(); $due=$rd['due_date']??null; $opened=false; $refused=false;
|
|
foreach(DB::table('sr_records')->where('obligation_id',$ob)->where('kind','receipt')->get() as $rc) $receipts[$rc->id]=['id'=>$rc->id,'amount'=>$rc->amount,'state'=>'proposed','allocated'=>'0.00','available'=>'0.00','reconciled'=>false];
|
|
foreach($effects as $e) {
|
|
if($e->kind==='open') $opened=true;
|
|
if($e->kind==='refused' && $e->record_id===$ob) $refused=true;
|
|
if($e->kind==='due') $due=$this->data($e)['due_date'];
|
|
if($e->kind==='receipt_confirm') { $receipts[$e->record_id]['state']='confirmed'; $receipts[$e->record_id]['available']=$e->amount; }
|
|
if($e->kind==='refused' && isset($receipts[$e->record_id])) $receipts[$e->record_id]['state']='refused';
|
|
if(in_array($e->kind,['allocate','reverse_allocation'])) {
|
|
$x=BigDecimal::of($e->amount)->multipliedBy($e->kind==='allocate'?1:-1); $allocated=$allocated->plus($x);
|
|
$rc=&$receipts[$e->receipt_id]; $rc['allocated']=(string)BigDecimal::of($rc['allocated'])->plus($x)->toScale(2); $rc['available']=(string)BigDecimal::of($rc['available'])->minus($x)->toScale(2); unset($rc);
|
|
}
|
|
if($e->kind==='reduction') $reduced=$reduced->plus($e->amount);
|
|
if($e->kind==='reconcile') $receipts[$e->receipt_id]['reconciled']=true;
|
|
if($e->kind==='reverse_reconcile') $receipts[$e->receipt_id]['reconciled']=false;
|
|
if($e->kind==='reverse_receipt') { $receipts[$e->receipt_id]['state']='reversed'; $receipts[$e->receipt_id]['available']='0.00'; }
|
|
}
|
|
$balance=$balance->minus($reduced)->minus($allocated); $received=BigDecimal::zero(); $available=BigDecimal::zero();
|
|
foreach($receipts as $rc) if($rc['state']==='confirmed') { $received=$received->plus($rc['amount']); $available=$available->plus($rc['available']); }
|
|
$cut??=now(ServiceInvoicing::ZONE)->format('Y-m-d');
|
|
return ['id'=>$ob,'original'=>$r->amount,'reduced'=>(string)$reduced->toScale(2),'received'=>(string)$received->toScale(2),'allocated'=>(string)$allocated->toScale(2),'available'=>(string)$available->toScale(2),'balance'=>(string)$balance->toScale(2),'opened'=>$opened,'state'=>!$opened?($refused?'refused':'proposed'):($balance->isZero()?'settled':($allocated->isPositive()?'partial':'open')),'due_date'=>$due,'due_state'=>!$opened?'not_open':($balance->isZero()?'settled':($due===null?'unknown':($cut>$due?'overdue':'not_due'))),'cut_date'=>$cut,'revision'=>$effects->count(),'receipts'=>$receipts,'effects'=>$effects->all()];
|
|
}
|
|
public function listing(int $actor): array
|
|
{
|
|
$s=$this->scope($actor,'view');
|
|
if(!ServiceCalculation::isolated()) return ['blocked'=>true,'notice'=>self::NOTICE,'simulation'=>self::SIMULATION,'obligations'=>[],'records'=>[],'documents'=>[]];
|
|
self::guard();
|
|
return DB::transaction(function()use($s) {
|
|
DB::table('companies')->where('id',$s['company_id'])->lockForUpdate()->firstOrFail();
|
|
$records=DB::table('sr_records')->where($s)->orderBy('id')->get();
|
|
return ['blocked'=>false,'notice'=>self::NOTICE,'simulation'=>self::SIMULATION,'records'=>$records->map(function($r){$r->data=$this->data($r);return $r;})->all(),'obligations'=>$records->where('kind','obligation')->map(fn($r)=>$this->state($r->id))->values()->all(),'documents'=>\App\Shared\Context\ModuleRecords::query('si_invoices')->where($s)->get(['id','series_code','number'])->all()];
|
|
});
|
|
}
|
|
/** Scoped single-position read reuses the authoritative state calculation without writer locks. */
|
|
public function position(int $obligation,int $actor):array
|
|
{
|
|
self::guard();$scope=$this->scope($actor,'view');$this->row($obligation,$scope,'obligation');return $this->state($obligation);
|
|
}
|
|
/** Idempotent internal delivery only: validates ledger, never posts accounts or calls banks. */
|
|
public function deliver(int $event): bool
|
|
{
|
|
self::guard();
|
|
return DB::transaction(function()use($event) {
|
|
$e=DB::table('sr_events')->where('id',$event)->lockForUpdate()->firstOrFail();
|
|
if(DB::table('sr_deliveries')->where('event_id',$event)->exists()) return false;
|
|
$cmd=DB::table('sr_commands')->find($e->command_id); $result=json_decode($cmd->result,true,32,JSON_THROW_ON_ERROR);
|
|
$ob=$result['obligation_id']??null;
|
|
if($ob) { $state=$this->state($ob); abort_if(BigDecimal::of($state['balance'])->isNegative(),409,'Integridade do saldo falhou.'); }
|
|
DB::table('sr_deliveries')->insert(['event_id'=>$event,'consumer'=>'simulation_integrity_v1','created_at'=>now()]);
|
|
return true;
|
|
});
|
|
}
|
|
}
|