Handoff di Integrazione

Il Contributor Portal è la porta d'ingresso per l'identità del contributor e la compliance pre-recorder. I sistemi a valle devono consumare soltanto output espliciti del portale e non devono inferire la readiness da stati di UI vaghi.

Bridge di Identità con l'App Playroll

Il bridge canonico tra l'utente dell'app Playroll e il contributor del Contributor Portal è esplicito e soggetto al gate di attivazione:

playroll_supa_new.playroll_users.user_id
  <-> playroll_contributor_portal.contributors.id

Source of truth:

playroll_contributor_portal.public.contributor_app_links

App read model:

playroll_supa_new.public.contributor_status_projection

L'app Playroll avvia il flusso chiamando:

playroll_supa_new.functions.create-contributor-link-intent

Il portale completa il flusso chiamando:

playroll_contributor_portal.functions.activate-contributor-app-link

L'attivazione è consentita soltanto dopo che:

accepted_documents.incarico = true
accepted_documents.privacy = true
accepted_documents.compensation = true
accepted_documents.isee_notice = true
payout_receiving_methods.method_type = sepa_iban
payout_receiving_methods.status = confirmed
payout_receiving_methods.email_confirmation_status = confirmed

Regole di integrazione:

• non usare l'email come bridge app Playroll/portale
• non lasciare che l'app attivi un contributor direttamente
• non considerare manual_review come sufficiente per l'attivazione automatica
• non copiare PII legali o di pagamento in playroll_supa_new
• non calcolare rewards o denaro pagabile a partire dal solo link
• la UI dell'app può trattare l'esistenza di una riga di proiezione come verifica del contributor

Accesso al Recorder

L'accesso al recorder deve basarsi sull'email verificata e sull'evidenza di completamento, non su un nome o un handle di contatto in formato libero.

Dati source richiesti:

public.onboarding_submissions.auth_user_id
public.onboarding_submissions.email
public.onboarding_submissions.accepted_documents
public.onboarding_submissions.document_acceptance_evidence
public.onboarding_submissions.metadata.recorder_access.status

Gate minimo per il recorder:

accepted_documents.incarico = true
accepted_documents.privacy = true
accepted_documents.compensation = true
accepted_documents.isee_notice = true
verified email present

Lo stato di metadata attuale dopo un onboarding andato a buon fine è:

documents_completed

Pipeline di Validazione

La validazione delle sessioni deve scrivere in:

public.session_validation_results

Solo questo semaforo deve sbloccare il tempo validato:

status = validated

Payload di validazione atteso:

session_id
contributor_id
validation_version
gross_seconds
valid_seconds
invalid_seconds
valid_ratio
rewardable_seconds
result_sha256

Non creare denaro pagabile direttamente dall'output di validazione. payable_eur è deprecato.

PlayRoll Time

Le sessioni validate creano credito interno di PlayRoll time:

public.playroll_time_ledger

Il ledger è la source of truth della valuta tempo. Non è denaro.

Campi di collegamento richiesti:

contributor_id
session_id
validation_result_id
entry_type = validated_time
seconds_delta
status
source
external_reference
earned_at

Milestone e Rewards

I milestone convertono il tempo disponibile in sblocchi di reward:

public.reward_milestones
public.contributor_milestone_unlocks

Solo uno sblocco di milestone deve creare un value item:

public.compensation_items

I value item devono tracciare ogni classe di valore, non solo i bonifici bancari:

cash
steam_key or software_key
voucher
prepaid_card
referral_bonus
manual_adjustment

Ogni compensation item dovrebbe includere:

contributor_id
item_type
eur_value
source_session_id
earned_at
paid_at
included_in_cap
receipt_id
validation_result_id
milestone_unlock_id
status

Integrazione Payout

Il Contributor Portal attualmente esporta i receiving-method confermati o in manual-review attraverso:

public.confirmed_payout_receiving_methods

Il trasferimento automatico di denaro deve richiedere:

method_type = sepa_iban
status = confirmed
email_confirmation_status = confirmed

I casi di manual review richiedono un'alternativa approvata da un operatore al di fuori di questo repo.

Il sistema di pagamento, non il browser del portale, deve possedere:

• la creazione delle richieste di payout
• i controlli di cap al momento della richiesta e dell'approvazione
• la creazione o verifica del beneficiario presso il provider
• l'approvazione del founder
• l'invio del batch di pagamento
• la gestione dei fallimenti del provider
• ricevute e value sheet
• gli eventi di audit

Visualizzazione del Saldo Rewards

Il workspace delle rewards è attualmente una UI statica in zero-state. Una futura integrazione dovrebbe leggere da:

public.contributor_playroll_time_balances
public.contributor_milestone_progress
public.contributor_reward_balances

Campi di visualizzazione suggeriti:

pending_seconds
available_seconds
available_hours
milestone credited_seconds
milestone remaining_seconds
in_validation_eur
available_eur
queued_eur
paid_eur
rolling_12mo_cap_used_eur
cap_remaining_eur

Admin Surface

Una admin/review surface interna non è presente in questo repo. Se costruita, va tenuta separata dal flusso pubblico del contributor e ristretta alle identità del team EC.

Code admin attese:

• coda di compliance del contributor
• coda di validazione delle sessioni
• coda dei pagamenti
• coda dei pagamenti falliti
• cap monitor
• dashboard documenti/versioni
• coda di manual review
• audit log

Usa credenziali service-role solo in contesti backend o di Edge Function. Non collocare mai operazioni admin nel codice del browser.