54 lines
2.9 KiB
Markdown
54 lines
2.9 KiB
Markdown
|
# 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).
|