175 lines
6.6 KiB
Markdown
175 lines
6.6 KiB
Markdown
---
|
||
id: FIN-WP-0002
|
||
type: workplan
|
||
title: "Client attribution and billing basis"
|
||
domain: financials
|
||
repo: fin-hub
|
||
status: active
|
||
owner: codex
|
||
topic_slug: financials
|
||
created: "2026-08-10"
|
||
updated: "2026-08-10"
|
||
related:
|
||
- FIN-WP-0001
|
||
- FIN-WP-0004
|
||
- CUST-WP-0058
|
||
state_hub_workstream_id: "ebc1d2de-ae11-4cde-b860-047922fc74b9"
|
||
---
|
||
|
||
# FIN-WP-0002 — Client attribution and billing basis
|
||
|
||
## Goal
|
||
|
||
Extend fin-hub's reporting model from service-level cost evidence to a
|
||
client × application × instance billing basis, including engagement revenue,
|
||
margin reporting, and explainable shared-infrastructure allocation.
|
||
|
||
fin-hub remains reporting-only. It does not generate invoices, execute or
|
||
track payments, perform bookkeeping, or become authoritative for client or
|
||
resource identity. An external GoBD-capable bookkeeping/invoicing system owns
|
||
invoice generation and payment tracking.
|
||
|
||
This workplan originates the proposal from the Custodian's
|
||
`CUST-WP-0058-T06` gap assessment. T00 reconciled the earlier scope exclusion:
|
||
client-level reporting and billing-basis exports are in scope, while legal
|
||
invoice generation, bookkeeping, payment handling, and identity authority
|
||
remain out of scope.
|
||
|
||
## Reconcile scope and authority boundaries
|
||
|
||
```task
|
||
id: FIN-WP-0002-T00
|
||
status: done
|
||
priority: high
|
||
state_hub_task_id: "280ff8c9-2a82-4a40-908c-37d6ca8ce3e2"
|
||
```
|
||
|
||
Reconcile this proposal with `SCOPE.md`, which currently lists multi-tenant
|
||
customer billing as out of scope. Define the permitted boundary between
|
||
client-level financial reporting and external invoicing/bookkeeping, and
|
||
update the scope or defer this workplan explicitly.
|
||
|
||
Also align with `FIN-WP-0004` so provider booked-cost evidence, analytical
|
||
allocation, customer billing basis, and resource-control technical allocation
|
||
have one authoritative owner each and do not double-count costs.
|
||
|
||
Done when the repository scope explicitly permits the intended reporting and
|
||
export surfaces, or the workplan is blocked/deferred with an identified owner
|
||
for the capability.
|
||
|
||
Completed 2026-08-10: `SCOPE.md` now includes client-level attribution,
|
||
engagement revenue/margin reporting, and billing-basis exports, while
|
||
explicitly excluding legal invoice generation/numbering, bookkeeping,
|
||
payments, banking, and client/resource identity authority. `FIN-WP-0004`
|
||
remains the coordination point for booked-cost versus technical-allocation
|
||
authority.
|
||
|
||
## Add client attribution
|
||
|
||
```task
|
||
id: FIN-WP-0002-T01
|
||
status: done
|
||
priority: high
|
||
state_hub_task_id: "904e9edc-a434-41e6-a4c7-ebb407469514"
|
||
```
|
||
|
||
After T00, extend cost rows with a stable client × application × instance cost
|
||
attribution key. Use an explicit external string identifier initially while
|
||
preserving a later reference seam to client-hub's authoritative app-instance
|
||
identity. Do not make fin-hub the client registry.
|
||
|
||
Cover unknown/unattributed values, uniqueness and period semantics,
|
||
corrections, migrations, validation, and backward compatibility for existing
|
||
service-level records.
|
||
|
||
Completed 2026-08-10: added a canonical validated external attribution key,
|
||
optional client/application/instance columns to `ServiceCost`, HostEurope CSV
|
||
ingestion and the SQLite ledger, additive migration for existing ledgers, and
|
||
currency-safe attributed reporting alongside the backward-compatible service
|
||
view. Partial or mismatched attribution is rejected; legacy rows remain
|
||
explicitly unattributed. Covered by the full test suite and documented in
|
||
`README.md`.
|
||
|
||
## Add engagement revenue and margin reporting
|
||
|
||
```task
|
||
id: FIN-WP-0002-T02
|
||
status: done
|
||
priority: high
|
||
state_hub_task_id: "f917bb0b-f44e-4642-9130-c1a004185180"
|
||
```
|
||
|
||
After T00 and T01, model the agreed engagement price or entitlement per
|
||
reporting period and compute revenue, attributed cost, and margin by client
|
||
and application. Preserve currency, effective periods, provenance, and price
|
||
revisions; do not treat a price record as an issued invoice or received
|
||
payment.
|
||
|
||
Completed 2026-08-10: added versioned engagement-price records with stable
|
||
IDs, reporting month, currency, source provenance, and explicit append-only
|
||
revision links. The SQLite ledger and CLI now report revenue, attributed cost,
|
||
and margin by client/application/instance without representing prices as
|
||
invoices or payments. Currency mismatches cannot silently join, superseded
|
||
prices remain auditable, and duplicate prices require an explicit revision.
|
||
|
||
## Define shared-infrastructure allocation
|
||
|
||
```task
|
||
id: FIN-WP-0002-T03
|
||
status: todo
|
||
priority: medium
|
||
state_hub_task_id: "899a5c29-843c-481f-a63a-42d4d327af5d"
|
||
```
|
||
|
||
After T00 and in coordination with `FIN-WP-0004`, define an explainable
|
||
per-instance allocation method for shared infrastructure. Start with the
|
||
available namespace/resource evidence, document assumptions and residual
|
||
unattributed cost, and keep technical allocation authority outside fin-hub
|
||
where resource-control supplies it.
|
||
|
||
Test allocation totals, rounding, missing evidence, shared overhead, revised
|
||
allocations, and prevention of duplicate booked cost.
|
||
|
||
## Export a per-client billing basis
|
||
|
||
```task
|
||
id: FIN-WP-0002-T04
|
||
status: wait
|
||
priority: medium
|
||
state_hub_task_id: "b5886131-82f6-49fb-a7e3-ba47d5b627a8"
|
||
```
|
||
|
||
After T00–T03, provide an idempotent billing-basis report/export by client and
|
||
period for consumption by an external invoicing system. Include stable record
|
||
identity, attribution key, period, price basis, allocated cost, margin,
|
||
currency, corrections, and provenance.
|
||
|
||
The export must not issue invoices, assign legal invoice numbers, execute or
|
||
track payments, or represent itself as bookkeeping evidence.
|
||
|
||
## Select the external invoicing system
|
||
|
||
```task
|
||
id: FIN-WP-0002-T05
|
||
status: wait
|
||
priority: high
|
||
state_hub_task_id: "d30b606f-43c1-4610-875d-c1fe578c412c"
|
||
```
|
||
|
||
Human gate: select the external GoBD-capable bookkeeping/invoicing system and
|
||
record the integration boundary, required export fields, custody model, and
|
||
retention responsibilities. Candidate products from the gap assessment are
|
||
lexoffice and sevDesk, but selection is an operator/business decision and is
|
||
not required to settle T00–T03.
|
||
|
||
## Acceptance
|
||
|
||
- [ ] Repository scope explicitly allows the reporting and export boundary.
|
||
- [ ] Costs can be reported by client × application × instance without making
|
||
fin-hub authoritative for client or resource identity.
|
||
- [ ] Revenue and margin are period-aware, currency-aware, and distinguishable
|
||
from invoices and payments.
|
||
- [ ] Shared-infrastructure allocations reconcile to authoritative booked
|
||
costs with assumptions and unattributed residuals visible.
|
||
- [ ] The billing-basis export is idempotent and contains no payment execution.
|
||
- [ ] A human records the external invoicing/bookkeeping system decision.
|