ahmido
55aef627aa
## Summary - harden findings and finding-exception Filament surfaces so workflow state, governance validity, overdue urgency, and next action are operator-first - add tenant stats widgets, segmented tabs, richer governance warnings, and baseline/dashboard attention propagation for overdue and lapsed governance states - add Spec 166 artifacts plus regression coverage for findings, badges, baseline summaries, tenantless operation viewer behavior, and critical table standards ## Verification - `vendor/bin/sail bin pint --dirty --format agent` - `vendor/bin/sail artisan test --compact` ## Filament Notes - Livewire v4.0+ compliance: yes, implementation stays on Filament v5 / Livewire v4 APIs only - Provider registration: unchanged, Laravel 12 panel/provider registration remains in `bootstrap/providers.php` - Global search: unchanged in this slice; `FindingExceptionResource` stays not globally searchable, no new globally searchable resource was introduced - Destructive actions: existing revoke/reject/approve/renew/workflow mutations remain capability-gated and confirmation-gated where already defined - Asset strategy: no new assets added; existing deploy process remains unchanged, including `php artisan filament:assets` when registered assets are used - Testing plan delivered: findings list/detail, exception register, dashboard attention, baseline summary, badge semantics, and tenantless operation viewer coverage Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #197
149 lines
6.9 KiB
Markdown
149 lines
6.9 KiB
Markdown
# Data Model: Finding Governance Health & Resolution Semantics Surface Hardening
|
|
|
|
## 1. Finding
|
|
|
|
- **Purpose**: Tenant-owned issue record that carries workflow lifecycle, severity, due state, ownership, and evidence-backed diagnostic context.
|
|
- **Ownership**: Tenant-owned (`workspace_id` + `tenant_id` already exist).
|
|
- **Relevant existing fields**:
|
|
- `id`
|
|
- `workspace_id`
|
|
- `tenant_id`
|
|
- `finding_type`
|
|
- `status`: `new`, `acknowledged`, `triaged`, `in_progress`, `reopened`, `resolved`, `closed`, `risk_accepted`
|
|
- `severity`
|
|
- `owner_user_id`
|
|
- `assignee_user_id`
|
|
- `due_at`
|
|
- `sla_days`
|
|
- `resolved_at`, `resolved_reason`
|
|
- `closed_at`, `closed_reason`, `closed_by_user_id`
|
|
- `reopened_at`, `triaged_at`, `in_progress_at`
|
|
- `current_operation_run_id`, `baseline_operation_run_id`
|
|
- `evidence_jsonb`
|
|
- **Relationships**:
|
|
- belongs to `Tenant`
|
|
- has one current `FindingException`
|
|
- belongs to owner, assignee, acknowledged-by, and closed-by users
|
|
- **Existing invariants preserved**:
|
|
- Workflow status remains the source of lifecycle truth.
|
|
- `risk_accepted` remains a finding workflow state, not proof of healthy governance by itself.
|
|
- Open-status and terminal-status helper behavior does not change in this slice.
|
|
|
|
## 2. FindingException
|
|
|
|
- **Purpose**: Tenant-owned governance record that determines whether accepted risk is currently backed by valid, expiring, expired, revoked, rejected, or missing-support governance.
|
|
- **Ownership**: Tenant-owned (`workspace_id` + `tenant_id` already exist).
|
|
- **Relevant existing fields**:
|
|
- `id`
|
|
- `workspace_id`
|
|
- `tenant_id`
|
|
- `finding_id`
|
|
- `status`: `pending`, `active`, `expiring`, `expired`, `rejected`, `revoked`, `superseded`
|
|
- `current_validity_state`: `valid`, `expiring`, `expired`, `revoked`, `rejected`, `missing_support`
|
|
- `requested_by_user_id`
|
|
- `owner_user_id`
|
|
- `approved_by_user_id`
|
|
- `request_reason`, `approval_reason`, `rejection_reason`, `revocation_reason`
|
|
- `requested_at`, `approved_at`, `rejected_at`, `revoked_at`
|
|
- `effective_from`, `review_due_at`, `expires_at`
|
|
- `current_decision_id`
|
|
- `evidence_summary`
|
|
- **Relationships**:
|
|
- belongs to `Finding`
|
|
- belongs to requester, owner, approver, and current decision
|
|
- has many decisions and evidence references
|
|
- **Existing invariants preserved**:
|
|
- Governance validity remains derived from exception state and timing.
|
|
- The exception remains the authoritative source for healthy versus lapsed governance.
|
|
|
|
## 3. Derived Surface Projection: Finding Governance Surface State
|
|
|
|
- **Purpose**: Non-persisted operator-facing projection used by findings list, finding detail, exception surfaces, and summary widgets.
|
|
- **Derived from**:
|
|
- `Finding.status`
|
|
- `Finding.severity`
|
|
- `Finding.owner_user_id`, `Finding.assignee_user_id`, `Finding.due_at`
|
|
- linked `FindingException`
|
|
- `FindingRiskGovernanceResolver::resolveFindingState()`
|
|
- `FindingRiskGovernanceResolver::resolveWarningMessage()`
|
|
- **Proposed derived fields**:
|
|
- `workflow_status`: current finding status value
|
|
- `workflow_family`: `active`, `accepted_risk`, or `historical`
|
|
- `governance_validity`: `valid`, `expiring`, `expired`, `revoked`, `rejected`, `missing_support`, or `null`
|
|
- `governance_attention`: `healthy`, `attention_needed`, or `not_applicable`
|
|
- `governance_warning`: nullable operator-readable warning message
|
|
- `due_attention`: `overdue`, `due_soon`, `none`
|
|
- `ownership_attention`: `assigned`, `owner_missing`, `assignee_missing`, or `both_missing` where relevant
|
|
- `resolution_context`: nullable secondary text such as `no longer observed` when derivable
|
|
- `primary_next_action`: derived operator guidance such as inspect exception, renew governance, review overdue finding, or review historical closure
|
|
- **Invariant**:
|
|
- This projection is derived only. It must not become a new stored truth or a replacement status enum.
|
|
|
|
## 4. Derived Surface Projection: Finding Detail Status Zone
|
|
|
|
- **Purpose**: Non-persisted grouping for the leading zone on finding detail.
|
|
- **Derived from**:
|
|
- the Finding Governance Surface State
|
|
- existing finding severity and related owner or assignee relationships
|
|
- existing exception owner or approver details when relevant
|
|
- **Required visible fields**:
|
|
- lifecycle status
|
|
- severity or priority
|
|
- governance validity and warning when applicable
|
|
- owner and assignee context
|
|
- due or SLA urgency
|
|
- next-step guidance
|
|
- **Invariant**:
|
|
- This zone reorganizes existing truth only; it does not add a new domain layer.
|
|
|
|
## 5. Derived Surface Projection: Tenant Governance Attention Summary
|
|
|
|
- **Purpose**: Non-persisted aggregate for dashboard and baseline-compare summary surfaces.
|
|
- **Derived from**:
|
|
- findings with open or terminal statuses
|
|
- overdue findings in open workflow states
|
|
- accepted-risk findings whose governance projection resolves to expiring, expired, revoked, rejected, or missing-support states
|
|
- existing compare summary state from `BaselineCompareStats`
|
|
- **Proposed aggregate values**:
|
|
- `overdue_open_findings_count`
|
|
- `expiring_governance_count`
|
|
- `lapsed_governance_count`
|
|
- `active_non_new_findings_count`
|
|
- `high_severity_active_findings_count`
|
|
- `healthy_checks` fallback only when none of the above require attention
|
|
- **Invariant**:
|
|
- Summary surfaces remain glance-first and DB-only. They surface operator-critical truth without becoming a new reporting system.
|
|
|
|
## Surface State Families
|
|
|
|
### Finding workflow families
|
|
|
|
- `active`: `new`, `acknowledged`, `triaged`, `in_progress`, `reopened`
|
|
- `accepted_risk`: `risk_accepted`
|
|
- `historical`: `resolved`, `closed`
|
|
|
|
### Governance-health families
|
|
|
|
- `healthy`: accepted risk with `valid` governance
|
|
- `attention_needed`: accepted risk with `expiring`, `expired`, `revoked`, `rejected`, or `missing_support` governance
|
|
- `not_applicable`: active or historical findings without current governance relevance
|
|
|
|
### Urgency families
|
|
|
|
- `overdue`: open finding with due date in the past
|
|
- `due_soon`: open finding approaching due threshold if current UI supports it
|
|
- `none`: no immediate due urgency signal
|
|
|
|
## Relationship Rules
|
|
|
|
- A finding can exist without an exception.
|
|
- A finding in `risk_accepted` status without a valid linked exception must project as governance attention, not as healthy accepted risk.
|
|
- A finding outside `risk_accepted` may still have historical exception context, but workflow lifecycle remains the primary status dimension.
|
|
- Exception surfaces and finding surfaces must render the same governance truth for the same finding or exception combination.
|
|
|
|
## Behavioral Invariants For This Spec
|
|
|
|
- No new persisted entity, table, enum, or status family is introduced.
|
|
- `resolved` and `closed` remain workflow states and do not gain implicit technical-remediation meaning.
|
|
- Governance validity remains derived from exception truth, not from finding status alone.
|
|
- Summary attention must not count only `new` findings when overdue or lapsed-governance conditions already exist. |