A09 — Campaign-relative group and member analytics API

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

Issues and acceptance covered

#28, #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

A02/A03; #26/#27 rate provenance integration, #37 observation contract, #41 review event basis for accepted events. #76 must fix CUID audit validation before realistic membership mutation fixtures. D-04 additive variant only if explicitly requested.

Repository and expected files

Backend: src/api/routes/adminClipperGroups.ts additive analytics GET, proposed src/utils/analytics/groups.ts/tests; read ClipperGroupMembership intervals and upstream observations/earnings. Preserve domain.ts CRUD and campaign ownership.

Existing behavior and verified gap

Groups and history exist but have no performance or finance DTO. Overlapping membership is valid; group rate candidates are not persisted yet. Historical webUserId can be null (E13).

Proposed implementation boundary

Provide selected-period submitted/accepted event counts, observed performance and gross earning/paid summaries per group/member with fact-time membership, campaign scope, and archived support. Compute group de-duplicated sums and campaign group union with unattributed bucket. Distinguish optional rate-winning-source view from member cohort performance.

Expected API / data contract

Bounded group analytics DTO with campaign/group/window/cohort basis/asOf, member pagination, full group summary, union/unattributed coverage and explicit non-additivity. No new global group or arbitrary primary membership.

Required tests

Boundary at joinedAt and exclusive leftAt; leave/rejoin, same creator in two groups, ties, archived groups, wrong campaign, null legacy identity, payout after leaving, full summary stable under paging; group member sum and union reconciliation.

Suggested agent tier

Smart owner implements/reviews temporal attribution and joins. Lower-cost agent can expand known membership fixture combinations and route serializers.

Expected PR boundary and reason

One group analytics backend PR, tightly covering #28 plus #52 integration. Stacked on A02/A03 and producer contracts; unlocks A16. No rate CRUD or membership workflow edits. 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

Retain router requireAuth + CLIPPER_GROUP_ADMINISTRATION. TODO(RBAC): Require approved campaign-group analytics and member financial access; group roster visibility alone must not imply unrestricted creator financial visibility.

Completion and reconciliation checks

Member rows plus unknown bucket reconcile to each group; union of fact IDs plus unattributed reconciles to campaign. Sum of overlapping group tiles is explicitly not a campaign total. Archive/rate edit cannot rewrite recorded money.

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.