TenantAtlas/specs/222-findings-intake-team-queue/data-model.md

# Data Model: Findings Intake & Team Queue V1

## Overview

This feature does not add or modify persisted entities. It introduces three derived models:

- the canonical admin-plane `Findings intake` queue at `/admin/findings/intake`
- the fixed `Unassigned` and `Needs triage` queue-view state
- the post-claim handoff result that points the operator into the existing `My Findings` surface

All three remain projections over existing finding, tenant membership, workspace context, and audit truth.

## Existing Persistent Inputs

### 1. Finding

- Purpose: Tenant-owned workflow record representing current governance or remediation work.
- Key persisted fields used by this feature:
  - `id`
  - `workspace_id`
  - `tenant_id`
  - `status`
  - `severity`
  - `due_at`
  - `subject_display_name`
  - `owner_user_id`
  - `assignee_user_id`
  - `reopened_at`
  - `triaged_at`
  - `in_progress_at`
- Relationships used by this feature:
  - `tenant()`
  - `ownerUser()`
  - `assigneeUser()`

Relevant existing semantics:

- `Finding::openStatuses()` defines intake inclusion and intentionally excludes `acknowledged`.
- `Finding::openStatusesForQuery()` remains relevant for `My Findings`, but not for intake.
- Spec 219 defines owner-versus-assignee meaning.
- Spec 221 defines the post-claim destination when a finding becomes assigned to the current user.

### 2. Tenant

- Purpose: Tenant boundary for queue disclosure, claim authorization, and tenant-plane detail drilldown.
- Key persisted fields used by this feature:
  - `id`
  - `workspace_id`
  - `name`
  - `external_id`
  - `status`

### 3. TenantMembership And Capability Truth

- Purpose: Per-tenant entitlement and capability boundary for queue visibility and claim.
- Sources:
  - `tenant_memberships`
  - existing `CapabilityResolver`
- Key values used by this feature:
  - tenant membership presence
  - role-derived `TENANT_FINDINGS_VIEW`
  - role-derived `TENANT_FINDINGS_ASSIGN`

Queue disclosure, tab badges, filter options, and claim affordances must only materialize for tenants where the actor remains a member and is authorized for the relevant finding capability.

### 4. Workspace Context

- Purpose: Active workspace selection in the admin plane.
- Source: Existing workspace session context, not a new persisted model for this feature.
- Effect on this feature:
  - gates entry into the admin intake page
  - constrains visible tenants to the current workspace
  - feeds the default active-tenant prefilter through `CanonicalAdminTenantFilterState`

### 5. AuditLog

- Purpose: Existing audit record for security- and workflow-relevant mutations.
- Effect on this feature:
  - successful claims write an audit entry through the existing `finding.assigned` action ID
  - the audit payload records before/after assignment state, workspace, tenant, actor, and target finding

## Derived Presentation Entities

### 1. IntakeFindingRow

Logical row model for `/admin/findings/intake`.

| Field | Meaning | Source |
|---|---|---|
| `findingId` | Target finding identifier | `Finding.id` |
| `tenantId` | Tenant route scope for detail drilldown | `Finding.tenant_id` |
| `tenantLabel` | Tenant name visible in the queue | `Tenant.name` |
| `summary` | Operator-facing finding summary | `Finding.subject_display_name` plus existing fallback logic |
| `severity` | Severity badge value | `Finding.severity` |
| `status` | Lifecycle badge value | `Finding.status` |
| `dueAt` | Due date if present | `Finding.due_at` |
| `dueState` | Derived urgency label such as overdue or due soon | existing findings due-state logic |
| `ownerLabel` | Accountable owner when present | `ownerUser.name` |
| `intakeReason` | Why the row still belongs in shared intake | derived from lifecycle plus assignment truth |
| `detailUrl` | Tenant finding detail route | derived from tenant finding view route |
| `navigationContext` | Return-path payload back to intake | derived from `CanonicalNavigationContext` |
| `claimEnabled` | Whether the current actor may claim now | derived from assign capability and current claimable state |

Validation rules:

- Row inclusion requires all of the following:
  - finding belongs to the current workspace
  - finding belongs to a tenant the current user may inspect
  - finding status is in `Finding::openStatuses()`
  - `assignee_user_id` is `null`
- Already-assigned findings are excluded even if overdue or reopened.
- `acknowledged` findings are excluded.
- Hidden-tenant or capability-blocked findings produce no row, no count, no tab badge contribution, and no tenant filter option.

Derived queue reason:

- `Needs triage` when status is `new` or `reopened`
- `Unassigned` when status is `triaged` or `in_progress`

### 2. FindingsIntakeState

Logical state model for the intake page.

| Field | Meaning |
|---|---|
| `workspaceId` | Current admin workspace scope |
| `queueView` | Fixed queue mode: `unassigned` or `needs_triage` |
| `tenantFilter` | Optional active-tenant prefilter, defaulted from canonical admin tenant context |
| `fixedScope` | Constant indicator that the page remains restricted to unassigned intake rows |

Rules:

- `queueView` is limited to `unassigned` and `needs_triage`.
- `tenantFilter` is clearable; `fixedScope` is not.
- `tenantFilter` values may only reference entitled tenants.
- Invalid or stale tenant filter state is discarded rather than widening visibility.
- Summary counts and tab badges reflect only visible intake rows after the active queue view and tenant prefilter are applied.

### 3. ClaimOutcome

Logical mutation result for `Claim finding`.

| Field | Meaning | Source |
|---|---|---|
| `findingId` | Claimed finding identifier | `Finding.id` |
| `tenantId` | Tenant scope of the claimed finding | `Finding.tenant_id` |
| `assigneeUserId` | New assignee after success | current user ID |
| `auditActionId` | Stable audit action identifier | existing `finding.assigned` |
| `nextPrimaryAction` | Primary handoff after success | `Open my findings` |
| `nextInspectAction` | Optional inspect fallback | existing tenant finding detail route |

Validation rules:

- Actor must remain a tenant member for the target finding.
- Actor must have `TENANT_FINDINGS_ASSIGN`.
- The locked record must still have `assignee_user_id = null` at mutation time.
- Claim leaves `owner_user_id` unchanged.
- Claim leaves workflow status unchanged.
- Success removes the row from intake immediately because the assignee is no longer null.
- Conflict does not mutate the row and must return honest feedback so the queue can refresh.

## State And Ordering Rules

### Intake inclusion order

1. Restrict to the current workspace.
2. Restrict to visible tenant IDs.
3. Restrict to `assignee_user_id IS NULL`.
4. Restrict to `Finding::openStatuses()`.
5. Apply the fixed queue view:
   - `unassigned` keeps all included rows
   - `needs_triage` keeps only `new` and `reopened`
6. Apply optional tenant prefilter.
7. Sort overdue rows first, reopened rows second, new rows third, then remaining backlog.
8. Within each bucket, rows with due dates sort by `dueAt` ascending, rows without due dates sort last, and remaining ties sort by `findingId` descending.

### Urgency semantics

- Overdue rows are the highest-priority bucket.
- Reopened non-overdue rows are the next bucket.
- New rows follow reopened rows.
- Triaged and in-progress unassigned rows remain visible in `Unassigned`, but never in `Needs triage`.

### Claim semantics

- Claim is not a lifecycle status transition.
- Claim performs one responsibility transition only: `assignee_user_id` moves from `null` to the current user.
- Owner accountability remains unchanged.
- Successful claim makes the finding eligible for `My Findings` immediately because the record is now assigned.
- Stale-row conflicts must fail before save when the locked record already has an assignee.

### Empty-state semantics

- If no visible intake rows exist anywhere in scope, the page shows a calm empty state with one CTA into `My Findings`.
- If the active tenant prefilter causes the empty state while other visible tenants still contain intake rows, the empty state must explain the tenant boundary and offer `Clear tenant filter`.
- Neither branch may reveal hidden tenant names or hidden queue quantities.

## Authorization-Sensitive Output

- Tenant labels, tab badges, filter values, rows, and counts are only derived from entitled tenants.
- Queue visibility remains workspace-context dependent.
- Claim affordances remain visible only inside in-scope membership context and must still enforce `403` server-side for members missing assign capability.
- Detail navigation remains tenant-scoped and must preserve existing `404` and `403` semantics on the destination.
- The derived queue state remains useful without revealing hidden tenant names, row counts, or empty-state hints.