A06 — Staff and campaign financial API projection

Status: blocked. Updated: 2026-09-06. Assigned agent: unassigned. Implementation PR: none.

Issues and acceptance covered

#51, #52. The acceptance boundary is the implementation scope and completion checks below; see the issue acceptance matrix for parent coverage. Shared definitions: financial contract; proof anchors: evidence index.

Dependencies and blockers

A03, A02 for observed/performance composition, source lifecycle/funding contracts #34/#35. Retain business guards; private creator campaign access remains #50.

Repository and expected files

Backend: GET finance consumers in src/api/routes/admin.ts (stats/chart/campaign list/detail/user list/detail), src/api/routes/campaigns.ts only safe compatibility projections, proposed dedicated admin analytics router. No campaign mutation or payout execution changes.

Existing behavior and verified gap

Campaign list totalSpent uses CPM, detail uses RPM; user totals use legacy paidOut; overview pending payout count uses PENDING only. Public campaigns already expose configured budgets, but new private liabilities must not be added there (E04/E05/E07).

Proposed implementation boundary

Compose one campaign/staff read result from A03 and A02. Provide funded/committed/spend/expense/remaining/outstanding/paid and posted earning series with explicit scopes; replace duplicated GET financial calculations via narrow adapters. Keep operational status stocks separate from event throughput. Eligible queue consumes payout eligibility service, not analytics rules.

Expected API / data contract

Additive exact analyticsV2 finance to existing guarded endpoints or dedicated protected reads; safe legacy CPM totalSpent adapter with documented basis. Financial and table filters explicitly distinct if UX requires; return full-scope summary plus page metadata. No new confidential fields on public campaigns.

Required tests

CPM 2/RPM 1.5 list/detail equality on named fields; budget remaining 70, no payout double debit; cross-creator sum/unattributed bucket; all payout statuses; platform/date and financial current-status independence; current route auth; compatibility JSON; performance+posting time bases.

Suggested agent tier

Smart owner handles shared financial/permission scope and integration review. Lower-cost agent may replace route-local arithmetic with approved adapter calls under exact hunk ownership.

Expected PR boundary and reason

One staff/campaign GET adapter PR stacked on A03/A02. No schema or lifecycle/funding mutation work. Unlocks A11/A13; agrees contract consumed by A10. Keep compatibility additive, avoid unrelated cleanup, and list exact stacked commits and later units unlocked in the PR. If observed scope grows beyond this boundary, update the plan before splitting or adding work.

RBAC requirements / TODOs

Preserve ANALYTICS, CAMPAIGN_MANAGEMENT and requireStaffAccess guards where currently attached. TODO(RBAC): Attach approved cross-creator finance/campaign read access at these exact routes before broadening audiences; preserve TOTP on unrelated writes.

Completion and reconciliation checks

Creator/staff campaign totals agree after basis and coverage alignment. Financial stock not limited to current page/status. CPM spend never relabels RPM expense. Auth/PII behavior unchanged except approved additive read payload.

Record actual tests, source schema/contract versions, PR/merge SHA, manual evidence and residual coverage before changing status to review/complete. Any unexpected migration must first satisfy the migration gates; never bundle upstream financial writer work into this analytics unit.