542 lines
17 KiB
YAML
542 lines
17 KiB
YAML
openapi: 3.1.0
|
|
info:
|
|
title: Workspace Governance Attention Internal Surface Contract
|
|
version: 0.1.0
|
|
summary: Internal logical contract for governance-aware workspace overview semantics
|
|
description: |
|
|
This contract is an internal planning artifact for Spec 175. It documents how
|
|
the existing workspace overview must derive governance-aware summary metrics,
|
|
attention items, calmness claims, and drill-through destinations from visible
|
|
tenant truth. The rendered routes still return HTML. The structured schemas
|
|
below describe the internal page and widget models that must be derivable
|
|
before rendering. This does not add a public HTTP API.
|
|
servers:
|
|
- url: /internal
|
|
x-overview-consumers:
|
|
- surface: workspace.overview.summary_stats
|
|
summarySource:
|
|
- workspace_overview_builder
|
|
- tenant_governance_aggregate
|
|
- operation_run_activity
|
|
- alert_delivery_activity
|
|
guardScope:
|
|
- app/Support/Workspaces/WorkspaceOverviewBuilder.php
|
|
- app/Filament/Widgets/Workspace/WorkspaceSummaryStats.php
|
|
expectedContract:
|
|
- governance_metrics_count_visible_tenants_not_raw_issue_totals
|
|
- governance_metrics_are_distinct_from_activity_metrics
|
|
- surface: workspace.overview.needs_attention
|
|
summarySource:
|
|
- workspace_overview_builder
|
|
- tenant_governance_aggregate
|
|
- existing_evidence_review_truth
|
|
- operation_run_activity
|
|
- alert_delivery_activity
|
|
guardScope:
|
|
- app/Support/Workspaces/WorkspaceOverviewBuilder.php
|
|
- app/Filament/Widgets/Workspace/WorkspaceNeedsAttention.php
|
|
- resources/views/filament/widgets/workspace/workspace-needs-attention.blade.php
|
|
expectedContract:
|
|
- each_item_identifies_the_visible_tenant_when_tenant_bound
|
|
- all_attention_items_are_tenant_bound
|
|
- governance_issues_rank_above_activity_only_items
|
|
- compare_attention_only_uses_stale_or_compare_specific_action_required_signals
|
|
- each_item_has_one_matching_destination_or_a_safe_disabled_state
|
|
- surface: workspace.overview.calmness
|
|
summarySource:
|
|
- workspace_overview_builder
|
|
- tenant_governance_aggregate
|
|
- operation_run_activity
|
|
- alert_delivery_activity
|
|
guardScope:
|
|
- app/Support/Workspaces/WorkspaceOverviewBuilder.php
|
|
- resources/views/filament/pages/workspace-overview.blade.php
|
|
expectedContract:
|
|
- operations_quiet_alone_is_not_enough_for_calmness
|
|
- zero_tenant_and_low_permission_states_do_not_masquerade_as_healthy_calm
|
|
- zero_tenant_recovery_uses_switch_workspace_and_low_permission_recovery_uses_operations_index
|
|
- surface: workspace.overview.recent_operations
|
|
summarySource:
|
|
- workspace_overview_builder
|
|
- operation_run_recency_query
|
|
guardScope:
|
|
- app/Filament/Widgets/Workspace/WorkspaceRecentOperations.php
|
|
- resources/views/filament/widgets/workspace/workspace-recent-operations.blade.php
|
|
expectedContract:
|
|
- surface_role_is_diagnostic_recency_not_primary_governance_summary
|
|
- recent_operations_remain_filtered_to_visible_tenant_scope
|
|
- recent_operations_are_bounded_to_five
|
|
paths:
|
|
/admin:
|
|
get:
|
|
summary: Render the governance-aware workspace overview bundle
|
|
operationId: viewWorkspaceGovernanceAttentionOverview
|
|
responses:
|
|
'200':
|
|
description: Workspace overview rendered with governance-aware summary, attention, calmness, and recency semantics
|
|
content:
|
|
text/html:
|
|
schema:
|
|
type: string
|
|
application/vnd.tenantpilot.workspace-governance-attention+json:
|
|
schema:
|
|
$ref: '#/components/schemas/WorkspaceGovernanceOverviewBundle'
|
|
'302':
|
|
description: No workspace context is active yet, so the request is redirected to `/admin/choose-workspace`
|
|
'404':
|
|
description: Workspace is outside entitlement scope
|
|
/admin/choose-tenant:
|
|
get:
|
|
summary: Explicit tenant-entry destination used by workspace drill-down when the operator wants to pick a tenant deliberately
|
|
operationId: openChooseTenantFromWorkspaceOverview
|
|
responses:
|
|
'200':
|
|
description: Choose-tenant page opened inside the authenticated admin panel and may bootstrap workspace context from the selected tenant if no workspace is currently active
|
|
/admin/choose-workspace:
|
|
get:
|
|
summary: Default workspace-switch recovery destination for zero-tenant or wrong-workspace states
|
|
operationId: openChooseWorkspaceFromWorkspaceOverview
|
|
responses:
|
|
'200':
|
|
description: Choose-workspace page opened so the operator can recover to another entitled workspace context even when no workspace is currently active
|
|
/admin/t/{tenant}:
|
|
get:
|
|
summary: Tenant dashboard fallback or broad tenant drill-through from workspace attention
|
|
operationId: openTenantDashboardFromWorkspaceAttention
|
|
parameters:
|
|
- name: tenant
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: Tenant dashboard opened for the visible tenant named by the workspace item when the dashboard is the allowed fallback or primary tenant landing
|
|
'404':
|
|
description: Tenant is outside entitlement scope
|
|
/admin/t/{tenant}/findings:
|
|
get:
|
|
summary: Tenant findings destination used by workspace governance and findings attention
|
|
operationId: openTenantFindingsFromWorkspaceAttention
|
|
parameters:
|
|
- name: tenant
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: tab
|
|
in: query
|
|
required: false
|
|
schema:
|
|
$ref: '#/components/schemas/FindingsTab'
|
|
- name: high_severity
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type: boolean
|
|
- name: governance_validity
|
|
in: query
|
|
required: false
|
|
schema:
|
|
$ref: '#/components/schemas/GovernanceValidityFilter'
|
|
description: Reproduces directly filterable governance-validity subsets such as `missing_support` or `expiring`; aggregate lapsed-governance attention falls back to the tenant dashboard when the full invalid-governance family cannot be reproduced without narrowing.
|
|
responses:
|
|
'200':
|
|
description: Tenant findings list opened with a subset matching the originating workspace attention item
|
|
'403':
|
|
description: Actor is in scope but lacks findings inspection capability
|
|
'404':
|
|
description: Tenant is outside entitlement scope
|
|
/admin/t/{tenant}/baseline-compare-landing:
|
|
get:
|
|
summary: Tenant baseline compare landing used by workspace compare attention
|
|
operationId: openTenantBaselineCompareFromWorkspaceAttention
|
|
parameters:
|
|
- name: tenant
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: Tenant baseline compare landing opened with the same compare posture family summarized by the workspace item
|
|
'403':
|
|
description: Actor is in scope but lacks the current tenant-view capability required by the compare landing
|
|
'404':
|
|
description: Tenant is outside entitlement scope
|
|
/admin/t/{tenant}/evidence:
|
|
get:
|
|
summary: Tenant evidence destination used only when existing evidence truth is the most precise workspace next jump
|
|
operationId: openTenantEvidenceFromWorkspaceAttention
|
|
parameters:
|
|
- name: tenant
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: Tenant evidence surface opened for the visible tenant named by the workspace item
|
|
'403':
|
|
description: Actor is in scope but lacks evidence inspection capability
|
|
'404':
|
|
description: Tenant is outside entitlement scope
|
|
/admin/t/{tenant}/reviews:
|
|
get:
|
|
summary: Tenant reviews destination used only when existing review truth is the most precise workspace next jump
|
|
operationId: openTenantReviewsFromWorkspaceAttention
|
|
parameters:
|
|
- name: tenant
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: Tenant reviews surface opened for the visible tenant named by the workspace item
|
|
'403':
|
|
description: Actor is in scope but lacks review inspection capability
|
|
'404':
|
|
description: Tenant is outside entitlement scope
|
|
/admin/operations:
|
|
get:
|
|
summary: Canonical operations index used by workspace activity and operations-follow-up signals
|
|
operationId: openOperationsFromWorkspaceOverview
|
|
parameters:
|
|
- name: tenant_id
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type:
|
|
- integer
|
|
- string
|
|
description: Optional tenant filter when the workspace item points to one tenant's operations follow-up.
|
|
- name: activeTab
|
|
in: query
|
|
required: false
|
|
schema:
|
|
$ref: '#/components/schemas/OperationsTab'
|
|
responses:
|
|
'200':
|
|
description: Canonical operations index opened with any tenant and tab continuity required by the workspace signal; this remains the workspace-member-safe fallback for low-permission workspace states
|
|
'404':
|
|
description: Requested tenant context is outside entitlement scope
|
|
/admin/operations/{run}:
|
|
get:
|
|
summary: Canonical operation detail opened from workspace recent operations or operations attention
|
|
operationId: openOperationDetailFromWorkspaceOverview
|
|
parameters:
|
|
- name: run
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type:
|
|
- integer
|
|
- string
|
|
responses:
|
|
'200':
|
|
description: Canonical operation detail opened for the visible run
|
|
'403':
|
|
description: Actor is in scope but lacks operation detail capability
|
|
'404':
|
|
description: Operation run is outside entitlement scope
|
|
/admin/alerts:
|
|
get:
|
|
summary: Canonical alerts overview used for alert-only follow-up from the workspace home
|
|
operationId: openAlertsOverviewFromWorkspaceOverview
|
|
responses:
|
|
'200':
|
|
description: Alerts overview opened for the current workspace, including delivery follow-up and alert-health context
|
|
'403':
|
|
description: Actor is in scope but lacks alerts inspection capability
|
|
'404':
|
|
description: Workspace is outside entitlement scope
|
|
components:
|
|
schemas:
|
|
MetricCategory:
|
|
type: string
|
|
enum:
|
|
- scope
|
|
- governance_risk
|
|
- activity
|
|
- alerts
|
|
AttentionFamily:
|
|
type: string
|
|
enum:
|
|
- governance
|
|
- findings
|
|
- compare
|
|
- evidence
|
|
- review
|
|
- operations
|
|
- alerts
|
|
AttentionUrgency:
|
|
type: string
|
|
enum:
|
|
- critical
|
|
- high
|
|
- medium
|
|
- supporting
|
|
DestinationKind:
|
|
type: string
|
|
enum:
|
|
- choose_tenant
|
|
- tenant_dashboard
|
|
- tenant_findings
|
|
- baseline_compare_landing
|
|
- tenant_evidence
|
|
- tenant_reviews
|
|
- operations_index
|
|
- operation_detail
|
|
- alerts_overview
|
|
- switch_workspace
|
|
- none
|
|
CheckedDomain:
|
|
type: string
|
|
enum:
|
|
- governance
|
|
- findings
|
|
- compare
|
|
- evidence
|
|
- review
|
|
- operations
|
|
- alerts
|
|
- tenant_access
|
|
FindingsTab:
|
|
type: string
|
|
enum:
|
|
- all
|
|
- needs_action
|
|
- overdue
|
|
- risk_accepted
|
|
- resolved
|
|
GovernanceValidityFilter:
|
|
type: string
|
|
enum:
|
|
- missing_support
|
|
- expiring
|
|
- valid
|
|
OperationsTab:
|
|
type: string
|
|
enum:
|
|
- all
|
|
- active
|
|
- blocked
|
|
- failed
|
|
- partial
|
|
- succeeded
|
|
DrillthroughTarget:
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- kind
|
|
- disabled
|
|
properties:
|
|
kind:
|
|
$ref: '#/components/schemas/DestinationKind'
|
|
url:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
tenantRouteKey:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
label:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
disabled:
|
|
type: boolean
|
|
helperText:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
filters:
|
|
type:
|
|
- object
|
|
- 'null'
|
|
additionalProperties: true
|
|
WorkspaceSummaryMetric:
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- key
|
|
- label
|
|
- value
|
|
- category
|
|
- description
|
|
- color
|
|
properties:
|
|
key:
|
|
type: string
|
|
label:
|
|
type: string
|
|
value:
|
|
type: integer
|
|
minimum: 0
|
|
category:
|
|
$ref: '#/components/schemas/MetricCategory'
|
|
description:
|
|
type: string
|
|
color:
|
|
type: string
|
|
destination:
|
|
oneOf:
|
|
- $ref: '#/components/schemas/DrillthroughTarget'
|
|
- type: 'null'
|
|
WorkspaceAttentionItem:
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- key
|
|
- tenantId
|
|
- tenantLabel
|
|
- family
|
|
- urgency
|
|
- title
|
|
- body
|
|
- badge
|
|
- badgeColor
|
|
anyOf:
|
|
- required:
|
|
- destination
|
|
properties:
|
|
destination:
|
|
$ref: '#/components/schemas/DrillthroughTarget'
|
|
- required:
|
|
- actionDisabled
|
|
- helperText
|
|
properties:
|
|
actionDisabled:
|
|
const: true
|
|
helperText:
|
|
type: string
|
|
properties:
|
|
key:
|
|
type: string
|
|
tenantId:
|
|
type: integer
|
|
tenantLabel:
|
|
type: string
|
|
family:
|
|
$ref: '#/components/schemas/AttentionFamily'
|
|
urgency:
|
|
$ref: '#/components/schemas/AttentionUrgency'
|
|
title:
|
|
type: string
|
|
body:
|
|
type: string
|
|
supportingMessage:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
badge:
|
|
type: string
|
|
badgeColor:
|
|
type: string
|
|
destination:
|
|
oneOf:
|
|
- $ref: '#/components/schemas/DrillthroughTarget'
|
|
- type: 'null'
|
|
actionDisabled:
|
|
type:
|
|
- boolean
|
|
- 'null'
|
|
helperText:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
WorkspaceRecentOperation:
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- id
|
|
- title
|
|
- statusLabel
|
|
- statusColor
|
|
- outcomeLabel
|
|
- outcomeColor
|
|
- startedAt
|
|
- destination
|
|
properties:
|
|
id:
|
|
type: integer
|
|
title:
|
|
type: string
|
|
tenantLabel:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
statusLabel:
|
|
type: string
|
|
statusColor:
|
|
type: string
|
|
outcomeLabel:
|
|
type: string
|
|
outcomeColor:
|
|
type: string
|
|
guidance:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
startedAt:
|
|
type: string
|
|
destination:
|
|
$ref: '#/components/schemas/DrillthroughTarget'
|
|
WorkspaceCalmnessState:
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- isCalm
|
|
- checkedDomains
|
|
- title
|
|
- body
|
|
- nextAction
|
|
properties:
|
|
isCalm:
|
|
type: boolean
|
|
checkedDomains:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/CheckedDomain'
|
|
title:
|
|
type: string
|
|
body:
|
|
type: string
|
|
nextAction:
|
|
description: Defaults to `switch_workspace` for zero-tenant recovery and `operations_index` for low-permission workspace-state recovery unless a more specific allowed action exists.
|
|
$ref: '#/components/schemas/DrillthroughTarget'
|
|
WorkspaceGovernanceOverviewBundle:
|
|
type: object
|
|
additionalProperties: false
|
|
required:
|
|
- workspaceId
|
|
- workspaceName
|
|
- summaryMetrics
|
|
- attentionItems
|
|
- recentOperations
|
|
- calmness
|
|
properties:
|
|
workspaceId:
|
|
type: integer
|
|
workspaceName:
|
|
type: string
|
|
summaryMetrics:
|
|
type: array
|
|
maxItems: 8
|
|
items:
|
|
$ref: '#/components/schemas/WorkspaceSummaryMetric'
|
|
attentionItems:
|
|
type: array
|
|
maxItems: 5
|
|
items:
|
|
$ref: '#/components/schemas/WorkspaceAttentionItem'
|
|
recentOperations:
|
|
type: array
|
|
maxItems: 5
|
|
items:
|
|
$ref: '#/components/schemas/WorkspaceRecentOperation'
|
|
calmness:
|
|
$ref: '#/components/schemas/WorkspaceCalmnessState'
|