292 lines
8.3 KiB
YAML
292 lines
8.3 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: TenantPilot Compliance Evidence Mapping v1 (Conceptual)
|
|
version: 0.1.0
|
|
description: |
|
|
Conceptual contract for the Compliance Evidence Mapping v1 planning package.
|
|
|
|
These paths describe existing Filament admin and tenant-scoped routes reused by
|
|
the implementation. The schemas document the shared interpretation contract the
|
|
feature is expected to add to existing review payloads; they do not define a new
|
|
public REST API.
|
|
servers:
|
|
- url: /
|
|
paths:
|
|
/admin/reviews/workspace:
|
|
get:
|
|
summary: View the compliance evidence mapping workspace
|
|
description: |
|
|
Existing admin-plane customer review workspace page reused as the primary
|
|
decision surface for mapped control readiness summaries. The route remains
|
|
read-only and tenant-safe.
|
|
parameters:
|
|
- in: query
|
|
name: tenant
|
|
required: false
|
|
schema:
|
|
type: string
|
|
description: |
|
|
Optional tenant prefilter using the existing tenant id or external id
|
|
pattern already accepted by the workspace page.
|
|
responses:
|
|
'200':
|
|
description: Workspace page rendered
|
|
content:
|
|
text/html:
|
|
schema:
|
|
type: string
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/CustomerReviewWorkspacePageModel'
|
|
'404':
|
|
description: Not found for non-members, actors without entitled tenants, or explicit out-of-scope tenant targeting
|
|
|
|
/admin/t/{tenant}/reviews/{review}:
|
|
get:
|
|
summary: Open the mapped control explanation for a released review
|
|
description: |
|
|
Existing tenant-scoped released-review detail route reused as the secondary
|
|
context surface from the customer review workspace. The customer-workspace
|
|
flow uses the existing `customer_workspace=1` query flag to keep the detail
|
|
read-only and customer-safe.
|
|
parameters:
|
|
- in: path
|
|
name: tenant
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
- in: path
|
|
name: review
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
- in: query
|
|
name: customer_workspace
|
|
required: false
|
|
schema:
|
|
type: boolean
|
|
description: Existing query-context flag that suppresses operator lifecycle actions on the detail surface.
|
|
responses:
|
|
'200':
|
|
description: Released review detail rendered
|
|
content:
|
|
text/html:
|
|
schema:
|
|
type: string
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/CustomerReviewDetailModel'
|
|
'404':
|
|
description: Not found for non-members, tenant mismatches, or out-of-scope review targets
|
|
|
|
/admin/t/{tenant}/evidence/{evidenceSnapshot}:
|
|
get:
|
|
summary: Open supporting evidence from a mapped control explanation
|
|
description: |
|
|
Existing tenant-scoped evidence detail route reused only after explicit
|
|
drilldown from the released-review detail surface and existing capability
|
|
checks.
|
|
parameters:
|
|
- in: path
|
|
name: tenant
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
- in: path
|
|
name: evidenceSnapshot
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
- in: query
|
|
name: source_surface
|
|
required: false
|
|
schema:
|
|
type: string
|
|
description: Existing source-surface metadata hook reused by the shared audit path.
|
|
responses:
|
|
'200':
|
|
description: Evidence proof detail rendered
|
|
content:
|
|
text/html:
|
|
schema:
|
|
type: string
|
|
'403':
|
|
description: Forbidden for an in-scope actor missing the evidence capability
|
|
'404':
|
|
description: Not found for non-members, mismatched tenant scope, or unavailable evidence targets
|
|
|
|
components:
|
|
schemas:
|
|
ControlInterpretationVersion:
|
|
type: object
|
|
required:
|
|
- version_key
|
|
- display_label
|
|
- non_certification_disclosure
|
|
properties:
|
|
version_key:
|
|
type: string
|
|
example: compliance_evidence_mapping.v1
|
|
display_label:
|
|
type: string
|
|
non_certification_disclosure:
|
|
type: string
|
|
|
|
AccessState:
|
|
type: object
|
|
required:
|
|
- state
|
|
- message
|
|
properties:
|
|
state:
|
|
type: string
|
|
enum:
|
|
- available
|
|
- absent
|
|
- unavailable
|
|
- expired
|
|
- redacted
|
|
- partial
|
|
message:
|
|
type: string
|
|
url:
|
|
type: string
|
|
nullable: true
|
|
|
|
CustomerControlSummary:
|
|
type: object
|
|
required:
|
|
- control_key
|
|
- control_name
|
|
- readiness_bucket
|
|
- limitation_flags
|
|
- customer_summary
|
|
- recommended_next_action
|
|
properties:
|
|
control_key:
|
|
type: string
|
|
control_name:
|
|
type: string
|
|
domain_key:
|
|
type: string
|
|
nullable: true
|
|
readiness_bucket:
|
|
type: string
|
|
enum:
|
|
- follow_up_required
|
|
- review_recommended
|
|
- evidence_on_record
|
|
limitation_flags:
|
|
type: array
|
|
items:
|
|
type: string
|
|
enum:
|
|
- accepted_risk_influenced
|
|
- partial_mapping
|
|
- stale_evidence
|
|
- supporting_evidence_unavailable
|
|
- unmapped
|
|
customer_summary:
|
|
type: string
|
|
evidence_basis_summary:
|
|
type: string
|
|
nullable: true
|
|
accepted_risk_summary:
|
|
type: string
|
|
nullable: true
|
|
recommended_next_action:
|
|
type: string
|
|
detail_anchor:
|
|
type: string
|
|
nullable: true
|
|
|
|
CustomerControlExplanation:
|
|
allOf:
|
|
- $ref: '#/components/schemas/CustomerControlSummary'
|
|
- type: object
|
|
properties:
|
|
explanation_text:
|
|
type: string
|
|
evidence_basis_items:
|
|
type: array
|
|
items:
|
|
type: string
|
|
proof_access:
|
|
$ref: '#/components/schemas/AccessState'
|
|
|
|
CustomerReviewWorkspaceEntry:
|
|
type: object
|
|
required:
|
|
- tenant_id
|
|
- tenant_name
|
|
- latest_published_review_id
|
|
- latest_review_published_at
|
|
- interpretation
|
|
- control_summaries
|
|
properties:
|
|
tenant_id:
|
|
type: integer
|
|
tenant_name:
|
|
type: string
|
|
latest_published_review_id:
|
|
type: integer
|
|
latest_review_published_at:
|
|
type: string
|
|
format: date-time
|
|
interpretation:
|
|
$ref: '#/components/schemas/ControlInterpretationVersion'
|
|
control_summaries:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/CustomerControlSummary'
|
|
follow_up_summary:
|
|
type: string
|
|
nullable: true
|
|
|
|
CustomerReviewWorkspacePageModel:
|
|
type: object
|
|
required:
|
|
- workspace_id
|
|
- entries
|
|
properties:
|
|
workspace_id:
|
|
type: integer
|
|
tenant_filter_id:
|
|
type: integer
|
|
nullable: true
|
|
entries:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/CustomerReviewWorkspaceEntry'
|
|
empty_state_message:
|
|
type: string
|
|
nullable: true
|
|
|
|
CustomerReviewDetailModel:
|
|
type: object
|
|
required:
|
|
- review_id
|
|
- tenant_id
|
|
- customer_workspace_context
|
|
- interpretation
|
|
- controls
|
|
- operator_actions_hidden
|
|
properties:
|
|
review_id:
|
|
type: integer
|
|
tenant_id:
|
|
type: integer
|
|
customer_workspace_context:
|
|
type: boolean
|
|
interpretation:
|
|
$ref: '#/components/schemas/ControlInterpretationVersion'
|
|
controls:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/CustomerControlExplanation'
|
|
operator_actions_hidden:
|
|
type: boolean
|
|
supporting_evidence_collapsed_by_default:
|
|
type: boolean
|
|
raw_support_details_hidden_by_default:
|
|
type: boolean |