ahmido
a74ab12f04
## Summary - add the Evidence Snapshot domain with immutable tenant-scoped snapshots, per-dimension items, queued generation, audit actions, badge mappings, and Filament list/detail surfaces - add the workspace evidence overview, capability and policy wiring, Livewire update-path hardening, and review-pack integration through explicit evidence snapshot resolution - add spec 153 artifacts, migrations, factories, and focused Pest coverage for evidence, review-pack reuse, authorization, action-surface regressions, and audit behavior ## Testing - `vendor/bin/sail artisan test --compact --stop-on-failure` - `CI=1 vendor/bin/sail artisan test --compact` - `vendor/bin/sail bin pint --dirty --format agent` ## Notes - branch: `153-evidence-domain-foundation` - commit: `b7dfa279` - spec: `specs/153-evidence-domain-foundation/` Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #183
275 lines
7.6 KiB
YAML
275 lines
7.6 KiB
YAML
openapi: 3.1.0
|
|
info:
|
|
title: Evidence Domain Foundation
|
|
version: 0.1.0
|
|
description: |
|
|
Planning contract for the tenant evidence snapshot domain. These routes describe
|
|
the expected HTTP-level behavior behind Filament surfaces and downstream consumers.
|
|
servers:
|
|
- url: http://localhost
|
|
paths:
|
|
/admin/t/{tenant}/evidence:
|
|
get:
|
|
operationId: listEvidenceSnapshots
|
|
summary: List evidence snapshots for a tenant
|
|
parameters:
|
|
- $ref: '#/components/parameters/TenantId'
|
|
responses:
|
|
'200':
|
|
description: Snapshot list
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/EvidenceSnapshot'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
post:
|
|
operationId: createEvidenceSnapshot
|
|
summary: Queue evidence snapshot creation for a tenant
|
|
parameters:
|
|
- $ref: '#/components/parameters/TenantId'
|
|
requestBody:
|
|
required: false
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/CreateSnapshotRequest'
|
|
responses:
|
|
'202':
|
|
description: Snapshot generation accepted or existing matching snapshot reused
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/SnapshotGenerationResponse'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
|
|
/admin/t/{tenant}/evidence/{snapshot}:
|
|
get:
|
|
operationId: viewEvidenceSnapshot
|
|
summary: View one evidence snapshot and its dimension items
|
|
parameters:
|
|
- $ref: '#/components/parameters/TenantId'
|
|
- $ref: '#/components/parameters/SnapshotId'
|
|
responses:
|
|
'200':
|
|
description: Snapshot detail
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/EvidenceSnapshotDetail'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
|
|
/admin/t/{tenant}/evidence/{snapshot}/refresh:
|
|
post:
|
|
operationId: refreshEvidenceSnapshot
|
|
summary: Queue creation of a new snapshot from current evidence state
|
|
parameters:
|
|
- $ref: '#/components/parameters/TenantId'
|
|
- $ref: '#/components/parameters/SnapshotId'
|
|
responses:
|
|
'202':
|
|
description: Refresh accepted
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/SnapshotGenerationResponse'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
|
|
/admin/t/{tenant}/evidence/{snapshot}/expire:
|
|
post:
|
|
operationId: expireEvidenceSnapshot
|
|
summary: Expire a snapshot without mutating its captured content
|
|
parameters:
|
|
- $ref: '#/components/parameters/TenantId'
|
|
- $ref: '#/components/parameters/SnapshotId'
|
|
responses:
|
|
'200':
|
|
description: Snapshot expired
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/EvidenceSnapshot'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
|
|
/admin/evidence/overview:
|
|
get:
|
|
operationId: evidenceOverview
|
|
summary: List workspace-scoped evidence completeness across authorized tenants
|
|
parameters:
|
|
- name: tenant_id
|
|
in: query
|
|
required: false
|
|
description: Optional entitled-tenant prefilter carried from tenant context into the canonical overview.
|
|
schema:
|
|
type: integer
|
|
responses:
|
|
'200':
|
|
description: Workspace evidence overview
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/EvidenceOverviewRow'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
|
|
components:
|
|
parameters:
|
|
TenantId:
|
|
name: tenant
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
SnapshotId:
|
|
name: snapshot
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
|
|
responses:
|
|
Forbidden:
|
|
description: In-scope member lacks the required capability
|
|
NotFound:
|
|
description: Workspace or tenant not entitled, or snapshot is outside scope
|
|
|
|
schemas:
|
|
CreateSnapshotRequest:
|
|
type: object
|
|
properties:
|
|
required_dimensions:
|
|
type: array
|
|
items:
|
|
type: string
|
|
allow_stale:
|
|
type: boolean
|
|
default: false
|
|
SnapshotGenerationResponse:
|
|
type: object
|
|
properties:
|
|
snapshot_id:
|
|
type: integer
|
|
operation_run_id:
|
|
type: integer
|
|
nullable: true
|
|
reused:
|
|
type: boolean
|
|
status:
|
|
type: string
|
|
enum: [queued, generating, active]
|
|
EvidenceSnapshot:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
tenant_id:
|
|
type: integer
|
|
status:
|
|
type: string
|
|
enum: [queued, generating, active, superseded, expired, failed]
|
|
completeness_state:
|
|
type: string
|
|
enum: [complete, partial, missing, stale]
|
|
fingerprint:
|
|
type: string
|
|
nullable: true
|
|
generated_at:
|
|
type: string
|
|
format: date-time
|
|
nullable: true
|
|
expires_at:
|
|
type: string
|
|
format: date-time
|
|
nullable: true
|
|
summary:
|
|
type: object
|
|
EvidenceSnapshotDetail:
|
|
allOf:
|
|
- $ref: '#/components/schemas/EvidenceSnapshot'
|
|
- type: object
|
|
properties:
|
|
items:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/EvidenceSnapshotItem'
|
|
EvidenceSnapshotItem:
|
|
type: object
|
|
properties:
|
|
dimension_key:
|
|
type: string
|
|
state:
|
|
type: string
|
|
enum: [complete, partial, missing, stale]
|
|
required:
|
|
type: boolean
|
|
source_kind:
|
|
type: string
|
|
source_record_type:
|
|
type: string
|
|
nullable: true
|
|
source_record_id:
|
|
type: string
|
|
nullable: true
|
|
source_fingerprint:
|
|
type: string
|
|
nullable: true
|
|
measured_at:
|
|
type: string
|
|
format: date-time
|
|
nullable: true
|
|
freshness_at:
|
|
type: string
|
|
format: date-time
|
|
nullable: true
|
|
summary_payload:
|
|
type: object
|
|
EvidenceOverviewRow:
|
|
type: object
|
|
properties:
|
|
tenant_id:
|
|
type: integer
|
|
latest_snapshot_id:
|
|
type: integer
|
|
nullable: true
|
|
snapshot_id:
|
|
type: integer
|
|
nullable: true
|
|
completeness_state:
|
|
type: string
|
|
enum: [complete, partial, missing, stale]
|
|
nullable: true
|
|
generated_at:
|
|
type: string
|
|
format: date-time
|
|
nullable: true
|
|
missing_dimensions:
|
|
type: integer
|
|
stale_dimensions:
|
|
type: integer
|