Tenant Billing Profile
En resumen
Tenant Billing Profile is a tenant-scoped singleton that drives every billing-side decision — language, currency, payment terms, dunning cadence, late-fee policy and issuer identity — backed by four pydantic validators, an in-process 60-second TTL cache for sub-millisecond hits, platform-defaults fallback when no profile exists, a dry-run preview that shows the impact of cadence changes on outstanding invoices and onboarding seed that enforces the singleton invariant at the service layer.
Cómo funciona
BillingProfile is a singleton per tenant exposing the configurable surface that backs invoicing, dunning and the entire reminder cadence. Four pydantic validators enforce consistency: language must be a supported ISO code, the late-fee policy must match its required fields (none, fixed, percentage or interest_rate), the dunning cadence must be sorted ascending with unique offsets and stage names, and payment terms must align with their tone. The dunning cadence itself is a list of DunningStageConfig rows with offset_days (0-720), stage_name, template_id and channel (email, letter or both); ascending sort and uniqueness are guaranteed at write time.
The late-fee policy is one of none, fixed (fixed amount), percentage (of outstanding) or interest_rate (annualised), with matching field validation and a legal_reference field for the national statute that justifies the rate — Code de commerce L. 441-6 (France), BGB section 288 Abs. 2 (Germany), Inkassolagen 1974:182 section 6 (Sweden). To stay fast, the profile is cached in-process with TTL 60 seconds per tenant; every mutation calls invalidate_billing_profile_cache(tenant_id), giving cold reads under 50 ms p95 and cache hits well under 1 ms. If a tenant has no profile yet, get_platform_defaults() returns hard-coded defaults (Easy Software System In Europe AB as issuer, English, EUR, 30-day terms, 14/30/60 dunning cadence) and resolve_profile_or_defaults logs a structured warning billing_profile.fallback_to_defaults so operators know which tenants are still on defaults.
The API at GET and PUT /tenants/{id}/billing-profile is RBAC-gated through _assert_tenant_access. The dry-run preview at POST /tenants/{id}/billing-profile/dunning-stages/preview returns, for each prospective stage, the count of invoices that would currently be at that stage and the total_outstanding amount, so operators can see exactly what a cadence change would do before saving. Onboarding seeds a profile via create_default_billing_profile(tenant_id, issuer_*, ...); double-create is rejected at the service layer rather than as a database constraint, keeping the singleton invariant owned by the service.
Capacidades clave
- Tenant singleton holding language, currency, payment terms, dunning cadence, late-fee policy and issuer identity
- Four pydantic validators enforcing language, late-fee field consistency, dunning sort and uniqueness, and term tone
- Configurable dunning cadence with offset_days 0-720, stage_name, template_id and channel per stage
- Late-fee policy with legal reference for national statutes (FR, DE, SE)
- In-process TTL 60 second cache giving cold p95 under 50 ms and cache hit under 1 ms
- Platform defaults fallback with structured warning so operators see who is still on defaults
- Dry-run preview showing invoices and total outstanding per stage before cadence is saved
En la práctica
A tenant admin opens Billing Profile to switch from a 30-day to 21-day payment term and tighten the dunning cadence from 14/30/60 to 10/20/45. Before saving she clicks Preview impact; the system runs POST /tenants/{id}/billing-profile/dunning-stages/preview and returns, for the three new stages, that 47 invoices totalling 28 300 EUR would currently be at stage one, 22 invoices at 14 100 EUR at stage two and 8 invoices at 5 200 EUR at stage three. She accepts, the validators check ascending sort and uniqueness, the profile saves, the cache is invalidated, and within seconds the new cadence drives the next /invoices/send-due-reminders run.
Late-fee policy is left at percentage with the Inkassolagen reference because the federation operates in Sweden.
Funcionalidades de este subsistema
7| ID | Status | Funcionalidades |
|---|---|---|
| F08.13.01 | Entregado | BillingProfile-modell — tenant-scoped singleton med språk/valuta/betalningstid/ton/dunning-stages/dröjsmålsavgift/issuer-identitet. Fyra pydantic-validatorer (språk, dröjsmåls-policy→fält, dunning-kadens sortering/unika, payment-terms-ton). ✅ PL-T092 |
| F08.13.02 | Entregado | Konfigurerbar dunning-kadens — DunningStageConfig med offset_days (0–720), stage_name, template_id, channel (email/letter/both). Stigande sortering + unika offsets/namn enforced. ✅ PL-T092 |
| F08.13.03 | Entregado | Dröjsmålsavgifts-policy — none/fixed/percentage/interest_rate med matchande fält-kravsvalidering och legal_reference för nationell lagstiftning (Code de commerce L. 441-6, BGB § 288 Abs. 2, Inkassolagen 1974:182 § 6). ✅ PL-T092 |
| F08.13.04 | Entregado | Profil-cache — in-process TTL 60 s per tenant; invalidate_billing_profile_cache(tenant_id) vid alla mutationer. ≤ 50 ms p95 på cold read, ≪ 1 ms på cache hit. ✅ PL-T092 |
| F08.13.05 | Entregado | Platform defaults fallback — get_platform_defaults() returnerar hårdkodad konfig (Easy Software System In Europe AB, engelska, EUR, 30d, 14/30/60 dunning). resolve_profile_or_defaults fallback-loggar strukturerad varning (billing_profile.fallback_to_defaults). ✅ PL-T092 |
| F08.13.06 | Entregado | API — GET/PUT /tenants/{id}/billing-profile (tenant-admin RBAC via _assert_tenant_access), POST /tenants/{id}/billing-profile/dunning-stages/preview för dry-run av kadensändringar (antal fakturor + total_outstanding per stadium idag). ✅ PL-T092 |
| F08.13.07 | Entregado | Onboarding-seed — create_default_billing_profile(tenant_id, issuer_*, ...) skapar profilen vid tenant-onboarding; avvisar dubbel-skapelse på service-nivå (singleton-invariant ägd av servicen, ej DB-constraint). ✅ PL-T092 |