# fin-hub Client-Billing Gap Assessment

**Created:** 2026-07-10
**Workplan:** `CUST-WP-0058-T06`
**Baseline reviewed:** `FIN-WP-0000/0001` (finished) — models `budget.py`,
`service_cost.py`; HostEurope CSV ingest; runway calculator; fin→ops coupling.
**Contract obligations:** business-app service contract §5 (cost attribution
key `client × app × instance`, per-instance cost reporting).

## What exists

- `ServiceCost`: per-service infra cost, keyed `service_id × environment ×
  period_month` (EUR, source-tagged) — fin→ops attribution works.
- Budgets, commitments, runway projection with alert thresholds.
- Manual CSV ingest (HostEurope) as designed for v0.1.

## Gaps vs. commercial operation

| # | Gap | Detail | Severity |
| --- | --- | --- | --- |
| G1 | **No client dimension** | `ServiceCost` cannot express `client × app × instance` (§5.1). Instance-per-client (DR-1 C) makes this the primary reporting axis. | high |
| G2 | **No revenue side** | Costs and budgets only; engagement pricing is not recorded, so margin-per-client — the input to DR-1's cost-optimization decision — cannot be computed. | high |
| G3 | **No per-instance cost split** | HostEurope CSV gives host-level cost; client instances share cluster nodes. An allocation method (namespace/resource-based split) is needed for §5.2. | medium |
| G4 | **Invoicing boundary undecided** | fin-hub SCOPE excludes payment/invoicing. Something must own invoice generation for clients. | medium |
| G5 | **No client-hub reference seam** | Once client-hub exists, cost rows should reference its `app_instance` / cost key instead of free-form strings. | low (sequencing) |

## Boundary recommendation (G4)

Keep fin-hub **reporting-only**: it owns attribution, margin, and runway; an
external bookkeeping/invoicing system (e.g. lexoffice/sevDesk — Bernd's
choice, GoBD-relevant) owns invoice generation and payment tracking. fin-hub
provides the per-engagement billing basis (attributed cost + entitlement
price) as an export, never executes payments. This keeps constitution §4
financial custody with the human/GmbH.

## Proposed workplan skeleton (for `/home/worsch/fin-hub`)

```
FIN-WP-0002 — client attribution and billing basis
  T01  Add client attribution: cost rows carry client/app/instance key
       (string key now; client-hub FK seam later, G5) (todo, high)
  T02  Engagement revenue model: price per engagement period, margin view
       per client × app (todo, high)
  T03  Per-instance allocation method for shared infra (namespace-based
       split; documented assumptions) (todo, medium)
  T04  Billing-basis export per client × period (feeds external invoicing;
       no payment execution) (todo, medium)
  T05  Decision + doc: external invoicing system selection (human gate,
       GoBD) (wait, high)
```

Posted to the fin-hub lane via State Hub message; implementation belongs in
the fin-hub repo (ADR-001 — the workplan file originates there).