e61c7ed15c
Service contract v0.1 accepted (Bernd 2026-07-10). Client-hub scoped as core-hub extension (client/engagement/app_instance/support_state, CLNT-WP skeleton). fin-hub gap assessment: 5 gaps, FIN-WP-0002 skeleton posted to fin-hub lane (msg 9c8e8ed4); recommendation fin-hub stays reporting-only. Remaining: T07 delivery-lane pilot, T08 closeout. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
53 lines
2.9 KiB
Markdown
53 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).
|