Agency Flow · Documentație Services & Billing

Zece billing types, aceeași schemă lunară

Un serviciu are exact un billing type; tipul e un strategy pattern — schema stochează parametrii, codul calculează, DB-ul păzește derivatele. Documentația de aici arată schema completă plus câte un flux narativ pas-cu-pas pentru fiecare tip: cine acționează, ce se inserează, ce se calculează și când îngheață fiecare cifră.

Account manager — setup Engine — automat Specialist / Echipa Finance — fee & facturare
Setup UI decision · 2026-07-10. Din pagina Digital Asset, Add service deschide drawerul comun direct pe A1. Billing Type rămâne selectabil în drawer și încarcă formularul Symfony dedicat tipului ales; schimbarea resetează Supplier/pricing fără confirmare, dar păstrează detaliile comune. Currency este setată per serviciu și se blochează doar în Budget mode. Asset și Composed name sunt evidențiate ca valori read-only, iar Composed name ocupă un rând complet și rămâne pe o singură linie. Pentru Provider Stack, după salvare se reîmprospătează doar panoul Services, astfel încât editările nesalvate rămân intacte. Fără JavaScript, selectorul grupat și rutele concrete rămân fallback-ul complet funcțional.
Exact Service end · 2026-07-14. end_date este ultima zi activă inclusivă. Setarea, schimbarea sau anularea unei date viitoare folosește ServiceEndScheduler: verifică intervalul complet al identității sub lock-ul Digital Asset-ului, protejează istoricul financiar și reconciliază atomic doar lunile a căror acoperire exactă s-a schimbat. Data rămâne editabilă în ultima zi activă, apoi Service-ul Closed este imuabil; minimul ultimei luni facturate este impus server-side, iar o veche lună finală viitoare nereprezentată nu se materializează dincolo de orizontul de referință.
Exact calendar UI · 2026-07-14. Formularele folosesc Paused from, Last paused day, Resume on și ruta POST /services/{serviceId}/end-date pentru Last active day. Stările sunt derivate dintr-un ClockInterface injectat. Dashboard-ul afișează auditul exact al pauzelor, intervalul calendaristic și baza de zile a fiecărei perioade, ecuațiile A1/C/D din inputurile fixe persistate pe perioadă și ecuațiile A2/B din billed hours plus rate/cap înghețate. Dacă orele labour se actualizează după ready, ultimul total eligibil apare separat. UI-ul nu reconstruiește ecuații din default-uri curente mutabile; rândurile legacy facturate fără bază sau fără inputurile de calcul obligatorii afișează Historical calculation. Înghețarea este per ServiceBillingPeriod, nu per Service și nu per formular TimeEntry: după ready se pot adăuga pontaje întârziate, care mișcă labour-ul/profitabilitatea până la invoicing fără să modifice suma client sau ecuația facturabilă înghețată; includerea lor pe factură cere reopen/recompute explicit.
Post-migration calendar reconciliation · 2026-07-14. app:billing:reconcile-calendar [--tenant=<uuid>] repară numai lunile deja reprezentate de perioade sau billing pauses. Comanda precolectează perechea Service/Digital Asset, blochează asset-ul înainte să încarce Service-ul fresh și rulează fiecare Service într-o tranzacție izolată: rândurile nefacturate primesc baza de zile, snapshot-urile și liniile generate lipsă, starea ready își păstrează timestampul și ajustarea manuală, iar invoiced rămâne neatins. Coverage zero nu șterge override-uri manuale sau linii deliverable user-owned, iar coverage zero/parțial nu exclude pontaje datate; conflictele sunt detectate înainte de mutații UnitOfWork și raportate skipped fără să oprească celelalte Servicii. Ordinea de deploy: migrarea Doctrine, comanda de reconciliere, apoi generarea normală.

Fundația

De aici se începe — tabelele și regulile pe care le folosesc toate fluxurile.

DB

Schema tabelelor

service · service_pricing_* · service_pause · service_billing_pause · service_billing_period · service_cost_line

Harta celor 12 tabele, exemple de date per billing type și puntea spre cod (composition → strategie → snapshot).
A1

Fixed fee — referință istorică

invoice = fixed_amount × billable_days / calendar_days

Lifecycle-ul conceptual A1, păstrat pentru referință. Nu descrie ruta și creatorul folosite de UI-ul actual.
⚡

Ghid rapid — tot sistemul pe o pagină

decizie · tabel comparativ · stări · glosar · FAQ

Pentru prima zi: cum aleg billing type-ul, ce diferă între tipuri dintr-o privire și întrebările care apar garantat.
∑

Calculator de billing — interactiv

alegi tipul → miști cifrele → vezi breakdown-ul live

Strategy pattern-ul pe viu: factura, costul și bucket-urile de profit se rescriu în timp real. Ideal pentru prezentare.

LABOR Munca echipei e costul

Fără supplier. Factura vine din sumă fixă sau din ore; profitul = factură − cost intern (pontaje × cost/h angajat).

A2

Hourly — flat rate

invoice = billed_rate × Σ ore

O singură rată pe serviciu; se agregă doar pontajele din zile eligibile. Rata nu se proratează, iar freeze-ul ready este doar al perioadei lunare.
B

Hourly — tiered

≤cap @ base · peste @ over (marginal)

Două benzi marginale peste orele eligibile; ratele și cap-ul lunar nu se proratează, iar pontajele întârziate nu schimbă factura ready fără reopen.

SUPPLIER Furnizorul e costul

Fără muncă internă. Costul furnizorului trece prin (C/E) sau poartă un fee (D/F1/F2/F3); fiecare lună lasă o linie de cost — ancora facturilor de furnizor.

C

Fixed cost

invoice = supplier_cost · profit 0

Pass-through pur, sumă fixă prorată pe zilele eligibile; clientul și supplierul folosesc același factor, deci profitul rămâne zero.
D

Fixed cost + fee

invoice = cost + fee · profit = fee

Ca C, plus un fee fix; ambele componente se proratează cu același factor calendaristic.
E

Variable cost

invoice = cost introdus lunar · profit 0

Pass-through cu cost variabil: specialistul introduce costul în fiecare lună, factura îl oglindește.
F1

Per deliverable + fee

invoice = Σ qty × (cost/u + fee/u)

Vedeta: linii per livrabil, fiecare cu supplierul ei, flux pe două roluri (specialist → finance) și lifecycle per linie.
F2

Cost/h + fee/h

invoice = (cost/h + fee/h) × ore

Ratele fixate la setup, orele furnizorului introduse lunar. Profit = fee/h × ore, marjă curată.
F3

% of cost (markup)

invoice = cost × (1 + fee_pct)

Procent fixat la setup peste un cost introdus lunar. Tot fee-ul e marjă curată — spre deosebire de Platform.

HIBRID Supplier și labor deodată

Singura excepție de la regula labor-XOR-supplier: financiar de platformă plus orele echipei care o administrează.

PL

Platform — % of spend

invoice = spend × (1 + client_pct) · rebate = platform_pct × spend

Rebate-ul platformei e profit direct (spread, nu cash); fee-ul clientului e labour-recovery și se netează cu orele echipei.

OVERLAY Buget la nivel de client

Nu e billing type: un overlay pe client care schimbă doar factura. Serviciile lui rulează normal, ca actuals.

G

Budget overlay

client_invoice = Client.budget · variance = budget − Σ actual

Factură fixă = bugetul, indiferent de servicii. Diferența buget − actual e variația de scop (under/over-serviced), ținută intern ca sold curent.
Cum se citește orice flux: pasul 1 e mereu setup-ul (2 rânduri: service + tabelul de pricing al tipului), pasul 2 e deschiderea lunii (rândul de perioadă), la mijloc stă diferența specifică tipului (ore / cost / linii / spend), iar finalul e identic: facturare din snapshot, înghețare, raportare prin SUM. Ce diferă între tipuri e doar cine completează ce, pe aceleași locuri.