openapi: 3.0.3
info:
  title: TenantPilot Customer Review Workspace Productization v1 (Conceptual)
  version: 0.1.0
  description: |
    Conceptual contract for the customer-safe productization follow-up in Spec 258.

    NOTE: These paths describe existing admin and tenant-scoped routes reused by
    the implementation. The schemas document expected derived page/view behavior
    for planning purposes only; they do not require a new public REST API.
servers:
  - url: /
paths:
  /admin/reviews/workspace:
    get:
      summary: View the productized customer review workspace
      description: |
        Existing canonical admin-plane workspace page for customer-safe review
        consumption. The route stays read-only and reuses current tenant review,
        finding, evidence, review-pack, localization, RBAC, and audit truth.
      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 released review detail from the customer review workspace
      description: |
        Existing tenant-scoped released-review detail route reused as the
        secondary context surface from the workspace page. 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'
        '403':
          description: Forbidden for an in-scope actor missing the record-level review permission
        '404':
          description: Not found for non-members, tenant mismatches, or out-of-scope review targets

  /admin/t/{tenant}/evidence/{evidenceSnapshot}:
    get:
      summary: Open an evidence proof route from the customer review flow
      description: |
        Existing tenant-scoped evidence detail route reused only when the actor
        explicitly asks for proof and has the required capability.
      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: Optional source-surface metadata if proof access is audited through the shared audit pipeline.
      responses:
        '200':
          description: Evidence proof detail rendered
          content:
            text/html:
              schema:
                type: string
        '403':
          description: Forbidden for an in-scope actor missing evidence capability
        '404':
          description: Not found for non-members, mismatched tenant scope, or unavailable proof targets

  /admin/review-packs/{reviewPack}/download:
    get:
      summary: Download the current review pack
      description: |
        Existing signed download route reused by the productized customer review
        flow. The pack must already exist, be ready, and not be expired.
      parameters:
        - in: path
          name: reviewPack
          required: true
          schema:
            type: integer
        - in: query
          name: source_surface
          required: false
          schema:
            type: string
          description: Existing download metadata hook used by the shared audit path.
      responses:
        '200':
          description: Review pack download stream
          content:
            application/zip:
              schema:
                type: string
                format: binary
        '403':
          description: Forbidden because of missing signature or invalid signed URL
        '404':
          description: Review pack not found, not ready, expired, or out of accessible tenant scope

components:
  schemas:
    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
        audit_expectation:
          type: string
          nullable: true
          description: |
            Planning-only note describing whether workspace-open auditing is
            already covered or requires a bounded shared-audit extension.

    CustomerReviewWorkspaceEntry:
      type: object
      required:
        - tenant_id
        - tenant_name
        - review_access
        - review_pack_access
        - evidence_proof_access
      properties:
        tenant_id:
          type: integer
        tenant_name:
          type: string
        latest_published_review_id:
          type: integer
          nullable: true
        latest_review_published_at:
          type: string
          format: date-time
          nullable: true
        outcome_summary:
          type: string
          nullable: true
        findings_summary:
          type: string
          nullable: true
        accepted_risk_accountability_summary:
          $ref: '#/components/schemas/AcceptedRiskAccountabilitySummary'
        review_access:
          $ref: '#/components/schemas/AccessState'
        review_pack_access:
          $ref: '#/components/schemas/AccessState'
        evidence_proof_access:
          $ref: '#/components/schemas/AccessState'
        redaction_note:
          type: string
          nullable: true
        absence_note:
          type: string
          nullable: true

    CustomerReviewDetailModel:
      type: object
      required:
        - review_id
        - tenant_id
        - launched_from_customer_workspace
        - operator_actions_hidden
      properties:
        review_id:
          type: integer
        tenant_id:
          type: integer
        launched_from_customer_workspace:
          type: boolean
        operator_actions_hidden:
          type: boolean
        narrative_outcome_summary:
          type: string
          nullable: true
        findings_summary:
          type: string
          nullable: true
        accepted_risk_accountability_summary:
          $ref: '#/components/schemas/AcceptedRiskAccountabilitySummary'
        evidence_summary:
          type: string
          nullable: true
        review_pack_access:
          $ref: '#/components/schemas/AccessState'
        evidence_proof_access:
          $ref: '#/components/schemas/AccessState'
        secondary_diagnostics_collapsed:
          type: boolean
          nullable: true

    AcceptedRiskAccountabilitySummary:
      type: object
      nullable: true
      properties:
        summary_text:
          type: string
        accountable_party:
          type: string
          nullable: true
        decision_reason:
          type: string
          nullable: true
        review_due_at:
          type: string
          format: date-time
          nullable: true
        expires_at:
          type: string
          format: date-time
          nullable: true
        completeness_note:
          type: string
          nullable: true

    AccessState:
      type: object
      required:
        - state
      properties:
        state:
          type: string
          enum:
            - available
            - absent
            - unavailable
            - expired
            - redacted
            - partial
        message:
          type: string
          nullable: true
        url:
          type: string
          nullable: true
        audit_action_id:
          type: string
          nullable: true
          description: Existing or bounded-additive shared audit action id for the explicit access moment.