openapi: 3.1.0
info:
  title: Nasak Feedback API
  version: 1.0.0-alpha.1
  description: Authenticated feedback history, follow-up comments, private attachments, moderation, and board promotion.
servers:
  - url: https://api.nasak.ir/v1/feedback
paths:
  /:
    get:
      operationId: listMyFeedback
      summary: List feedback submitted by the current user
      security: [{ cookieSession: [] }]
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
    post:
      operationId: createMyFeedback
      summary: Submit a suggestion, criticism, solution, or idea
      security: [{ cookieSession: [] }]
      x-idempotency-exempt: true
      x-migration-note: Compatibility mutation with same-origin, validation, and rate-limit controls.
      requestBody: { $ref: '#/components/requestBodies/Mutation' }
      responses:
        '201': { $ref: '#/components/responses/Success' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
  /{id}/comments:
    post:
      operationId: commentOnMyFeedback
      summary: Add a follow-up comment to owned feedback
      parameters: [{ $ref: '#/components/parameters/Id' }]
      security: [{ cookieSession: [] }]
      x-idempotency-exempt: true
      x-migration-note: Compatibility mutation with ownership verification.
      requestBody: { $ref: '#/components/requestBodies/Mutation' }
      responses:
        '201': { $ref: '#/components/responses/Success' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
  /attachments/{id}:
    get:
      operationId: downloadFeedbackAttachment
      summary: Download a private feedback attachment after access verification
      parameters: [{ $ref: '#/components/parameters/Id' }]
      security: [{ cookieSession: [] }]
      responses:
        '200': { description: Private attachment stream. }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
  /admin:
    get:
      operationId: listAdminFeedback
      summary: List and search feedback for central moderation
      security: [{ cookieSession: [] }]
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
  /admin/{id}:
    patch:
      operationId: updateAdminFeedback
      summary: Update feedback status and administrative response
      parameters: [{ $ref: '#/components/parameters/Id' }]
      security: [{ cookieSession: [] }]
      x-idempotency-exempt: true
      x-migration-note: Audited compatibility moderation mutation.
      requestBody: { $ref: '#/components/requestBodies/Mutation' }
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
  /admin/{id}/comments:
    post:
      operationId: commentOnAdminFeedback
      summary: Add an administrative follow-up comment
      parameters: [{ $ref: '#/components/parameters/Id' }]
      security: [{ cookieSession: [] }]
      x-idempotency-exempt: true
      x-migration-note: Audited compatibility mutation.
      requestBody: { $ref: '#/components/requestBodies/Mutation' }
      responses:
        '201': { $ref: '#/components/responses/Success' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
  /admin/{id}/board:
    post:
      operationId: promoteFeedbackToBoard
      summary: Promote safe feedback into the public site board workflow
      parameters: [{ $ref: '#/components/parameters/Id' }]
      security: [{ cookieSession: [] }]
      x-idempotency-exempt: true
      x-migration-note: Audited promotion with board visibility policy checks.
      requestBody: { $ref: '#/components/requestBodies/Mutation' }
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
components:
  securitySchemes:
    cookieSession: { type: apiKey, in: cookie, name: pdf_library_session }
  parameters:
    Id:
      name: id
      in: path
      required: true
      schema: { type: string, format: uuid }
  requestBodies:
    Mutation:
      required: true
      content:
        application/json:
          schema: { type: object, additionalProperties: true }
  schemas:
    Error:
      type: object
      additionalProperties: true
      required: [error]
      properties: { error: { type: string } }
  responses:
    Success:
      description: Successful user-scoped response.
      content:
        application/json:
          schema: { type: object, additionalProperties: true }
    BadRequest:
      description: Invalid request.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    Unauthorized:
      description: Authentication is required.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    Forbidden:
      description: Feedback access is denied.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    TooManyRequests:
      description: Rate limit exceeded.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }