openapi: 3.0.3
info:
  title: Blockchain Negotiation Backend API
  description: |
    Comprehensive API for blockchain-based proposal negotiation system with advanced elicitation methods and grouping strategies.
    
    ## Features
    - Proposal management with blockchain integration
    - Advanced preference elicitation methods (AHP, Conjoint, BWS, DCE)
    - Intelligent proposal grouping strategies
    - Real-time negotiation and conflict resolution
    - Comprehensive analytics and reporting
    
    ## Authentication
    All endpoints require Bearer token authentication. Include your JWT token in the Authorization header:
    ```
    Authorization: Bearer <your-jwt-token>
    ```
  version: 1.0.0
  contact:
    name: Blockchain Negotiation Team
    email: support@blockchainnego.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: http://localhost:5000/api
    description: Development server
  - url: https://api.blockchainnego.com/api
    description: Production server

security:
  - bearerAuth: []

paths:
  # ========================================
  # PROPOSAL ENDPOINTS
  # ========================================
  /proposals:
    get:
      summary: Get all proposals (Admin only)
      description: Retrieve all proposals with pagination and filtering options
      tags: [Proposals]
      security:
        - bearerAuth: []
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
          description: Page number for pagination
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
          description: Number of proposals per page
      responses:
        '200':
          description: Proposals retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Proposals retrieved successfully"
                  data:
                    type: object
                    properties:
                      proposals:
                        type: array
                        items:
                          $ref: '#/components/schemas/Proposal'
                      totalProposals:
                        type: number
                        example: 123
                      currentPage:
                        type: number
                        example: 1
                      totalPages:
                        type: number
                        example: 13
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /proposals/all:
    get:
      summary: Get all proposals for processing (Admin only)
      description: Fetch all proposals with processing status for admin operations
      tags: [Proposals]
      security:
        - bearerAuth: []
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [pending, in_negotiation, finalized, rejected, all]
            default: all
          description: Filter proposals by status
      responses:
        '200':
          description: List of proposals retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Proposals retrieved successfully"
                  data:
                    type: object
                    properties:
                      count:
                        type: number
                        example: 123
                      proposals:
                        type: array
                        items:
                          $ref: '#/components/schemas/Proposal'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /proposals/{id}:
    get:
      summary: Get specific proposal by ID
      description: Retrieve detailed information about a specific proposal
      tags: [Proposals]
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Proposal ID
          example: "507f1f77bcf86cd799439011"
      responses:
        '200':
          description: Proposal retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Proposal retrieved successfully"
                  data:
                    $ref: '#/components/schemas/Proposal'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  # ========================================
  # ENHANCED SUMMARY ENDPOINTS
  # ========================================
  /enhanced-summaries:
    get:
      summary: Get all proposal summaries
      description: Retrieve all proposal summaries with search and filtering capabilities
      tags: [Enhanced Summaries]
      security:
        - bearerAuth: []
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
          description: Page number for pagination
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
          description: Number of summaries per page
        - name: search
          in: query
          schema:
            type: string
          description: Search in summary text
        - name: sortBy
          in: query
          schema:
            type: string
            enum: [createdAt, updatedAt, proposalTitle]
            default: createdAt
          description: Sort field
        - name: sortOrder
          in: query
          schema:
            type: string
            enum: [asc, desc]
            default: desc
          description: Sort order
      responses:
        '200':
          description: Summaries retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Summaries retrieved successfully"
                  data:
                    type: object
                    properties:
                      summaries:
                        type: array
                        items:
                          $ref: '#/components/schemas/EnhancedSummary'
                      totalSummaries:
                        type: number
                        example: 123
                      currentPage:
                        type: number
                        example: 1
                      totalPages:
                        type: number
                        example: 13
                      statistics:
                        type: object
                        properties:
                          totalSummaries:
                            type: number
                          avgSummaryLength:
                            type: number
        '500':
          $ref: '#/components/responses/InternalServerError'

  /enhanced-summaries/proposals-with-summaries:
    get:
      summary: Get all proposals with their summaries
      description: Retrieve all proposals along with their associated summaries
      tags: [Enhanced Summaries]
      security:
        - bearerAuth: []
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
          description: Page number for pagination
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
          description: Number of proposals per page
        - name: hasSummary
          in: query
          schema:
            type: boolean
          description: Filter proposals that have summaries
      responses:
        '200':
          description: Proposals with summaries retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Proposals with summaries retrieved successfully"
                  data:
                    type: object
                    properties:
                      proposals:
                        type: array
                        items:
                          $ref: '#/components/schemas/ProposalWithSummaries'
                      totalProposals:
                        type: number
                        example: 123
                      currentPage:
                        type: number
                        example: 1
                      totalPages:
                        type: number
                        example: 13
                      statistics:
                        type: object
                        properties:
                          totalSummaries:
                            type: number
                          proposalsWithSummaries:
                            type: number
                          avgSummariesPerProposal:
                            type: number
        '500':
          $ref: '#/components/responses/InternalServerError'

  /enhanced-summaries/{proposalId}:
    get:
      summary: Get summaries for a specific proposal
      description: Retrieve all summaries for a specific proposal
      tags: [Enhanced Summaries]
      security:
        - bearerAuth: []
      parameters:
        - name: proposalId
          in: path
          required: true
          schema:
            type: string
          description: Proposal ID
          example: "507f1f77bcf86cd799439011"
      responses:
        '200':
          description: Proposal summaries retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Proposal summaries retrieved successfully"
                  data:
                    type: object
                    properties:
                      proposal:
                        type: object
                        properties:
                          id:
                            type: string
                          title:
                            type: string
                          description:
                            type: string
                          submittedBy:
                            $ref: '#/components/schemas/User'
                      summaries:
                        type: array
                        items:
                          $ref: '#/components/schemas/EnhancedSummary'
                      statistics:
                        type: object
                        properties:
                          totalSummaries:
                            type: number
                          latestSummary:
                            $ref: '#/components/schemas/EnhancedSummary'
                          avgSummaryLength:
                            type: number
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /enhanced-summaries/statistics:
    get:
      summary: Get summary statistics
      description: Retrieve comprehensive statistics about proposal summaries
      tags: [Enhanced Summaries]
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Summary statistics retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Summary statistics retrieved successfully"
                  data:
                    $ref: '#/components/schemas/SummaryStatistics'
        '500':
          $ref: '#/components/responses/InternalServerError'

  # ========================================
  # PROPOSAL ELICITATION ENDPOINTS
  # ========================================
  /proposals-with-elicitation:
    get:
      summary: Get all proposals with their elicitation data
      description: Retrieve all proposals along with their elicitation data and summaries
      tags: [Proposal Elicitation]
      security:
        - bearerAuth: []
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
          description: Page number for pagination
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
          description: Number of proposals per page
        - name: hasElicitation
          in: query
          schema:
            type: boolean
          description: Filter proposals that have elicitation data
        - name: elicitationMethod
          in: query
          schema:
            type: string
            enum: [AHP, Conjoint, BWS, DCE, manual, nlp-extraction, role-based-fallback, nlp-fallback, enhanced-elicitation]
          description: Filter by elicitation method
      responses:
        '200':
          description: Proposals with elicitation data retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Proposals with elicitation data retrieved successfully"
                  data:
                    type: object
                    properties:
                      proposals:
                        type: array
                        items:
                          $ref: '#/components/schemas/ProposalWithElicitation'
                      totalProposals:
                        type: number
                        example: 123
                      currentPage:
                        type: number
                        example: 1
                      totalPages:
                        type: number
                        example: 13
                      statistics:
                        $ref: '#/components/schemas/ElicitationStatistics'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /proposals-with-elicitation/{proposalId}:
    get:
      summary: Get specific proposal with all elicitation data
      description: Retrieve a specific proposal with all its elicitation data and summaries
      tags: [Proposal Elicitation]
      security:
        - bearerAuth: []
      parameters:
        - name: proposalId
          in: path
          required: true
          schema:
            type: string
          description: Proposal ID
          example: "507f1f77bcf86cd799439011"
      responses:
        '200':
          description: Proposal with elicitation data retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Proposal with elicitation data retrieved successfully"
                  data:
                    type: object
                    properties:
                      proposal:
                        $ref: '#/components/schemas/Proposal'
                      elicitations:
                        type: array
                        items:
                          $ref: '#/components/schemas/ElicitationData'
                      summaries:
                        type: array
                        items:
                          $ref: '#/components/schemas/SummaryData'
                      elicitationsByMethod:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            $ref: '#/components/schemas/ElicitationData'
                      elicitationsByStakeholder:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            $ref: '#/components/schemas/ElicitationData'
                      statistics:
                        $ref: '#/components/schemas/ElicitationStatistics'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /proposals-with-elicitation/{proposalId}/elicitation/{method}:
    get:
      summary: Get specific elicitation data for a proposal by method
      description: Retrieve specific elicitation data for a proposal by method with optional stakeholder filtering
      tags: [Proposal Elicitation]
      security:
        - bearerAuth: []
      parameters:
        - name: proposalId
          in: path
          required: true
          schema:
            type: string
          description: Proposal ID
          example: "507f1f77bcf86cd799439011"
        - name: method
          in: path
          required: true
          schema:
            type: string
            enum: [AHP, Conjoint, BWS, DCE, manual, nlp-extraction, role-based-fallback, nlp-fallback, enhanced-elicitation]
          description: Elicitation method
          example: "AHP"
        - name: stakeholderRole
          in: query
          schema:
            type: string
            enum: [student, faculty, it_staff, admin]
          description: Filter by stakeholder role
      responses:
        '200':
          description: Specific elicitation data retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "AHP elicitation data retrieved successfully"
                  data:
                    type: object
                    properties:
                      proposal:
                        type: object
                        properties:
                          id:
                            type: string
                          title:
                            type: string
                          description:
                            type: string
                      method:
                        type: string
                        example: "AHP"
                      elicitations:
                        type: array
                        items:
                          $ref: '#/components/schemas/ElicitationData'
                      statistics:
                        type: object
                        properties:
                          totalElicitations:
                            type: number
                          avgConfidence:
                            type: number
                          avgProcessingTime:
                            type: number
                          stakeholderRoles:
                            type: array
                            items:
                              type: string
                          statusDistribution:
                            type: object
                            properties:
                              completed:
                                type: number
                              failed:
                                type: number
                              pending:
                                type: number
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /proposals-with-elicitation/statistics:
    get:
      summary: Get statistics for proposals with elicitation data
      description: Retrieve comprehensive statistics about proposals and their elicitation data
      tags: [Proposal Elicitation]
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Statistics retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Statistics retrieved successfully"
                  data:
                    type: object
                    properties:
                      overview:
                        type: object
                        properties:
                          totalProposals:
                            type: number
                          totalElicitations:
                            type: number
                          totalSummaries:
                            type: number
                          proposalsWithElicitation:
                            type: number
                          proposalsWithSummaries:
                            type: number
                          elicitationCoverage:
                            type: string
                          summaryCoverage:
                            type: string
                      methodDistribution:
                        type: array
                        items:
                          type: object
                          properties:
                            _id:
                              type: string
                            count:
                              type: number
                            avgConfidence:
                              type: number
                            avgProcessingTime:
                              type: number
                      stakeholderDistribution:
                        type: array
                        items:
                          type: object
                          properties:
                            _id:
                              type: string
                            count:
                              type: number
                      statusDistribution:
                        type: array
                        items:
                          type: object
                          properties:
                            _id:
                              type: string
                            count:
                              type: number
        '500':
          $ref: '#/components/responses/InternalServerError'

  # ========================================
  # RESEARCH ELICITATION ENDPOINTS
  # ========================================
  /research-elicitation/elicit/{proposalId}:
    post:
      summary: Elicit preferences using research methods
      description: Perform preference elicitation using advanced research methods (AHP, Conjoint, BWS, DCE)
      tags: [Research Elicitation]
      security:
        - bearerAuth: []
      parameters:
        - name: proposalId
          in: path
          required: true
          schema:
            type: string
          description: Proposal ID
          example: "507f1f77bcf86cd799439011"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResearchElicitationRequest'
            examples:
              ahp_example:
                summary: AHP Elicitation
                value:
                  method: "AHP"
                  stakeholderRole: "faculty"
                  options: {}
              conjoint_example:
                summary: Conjoint Analysis
                value:
                  method: "Conjoint"
                  stakeholderRole: "student"
                  options: {}
              bws_example:
                summary: Best-Worst Scaling
                value:
                  method: "BWS"
                  stakeholderRole: "it_staff"
                  options: {}
              dce_example:
                summary: Discrete Choice Experiments
                value:
                  method: "DCE"
                  stakeholderRole: "admin"
                  options: {}
      responses:
        '200':
          description: Elicitation completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResearchElicitationResponse'
              examples:
                ahp_success:
                  summary: AHP Success Response
                  value:
                    success: true
                    message: "AHP elicitation completed successfully"
                    data:
                      elicitationId: "507f1f77bcf86cd799439012"
                      method: "AHP"
                      confidence: 0.85
                      processingTime: 150
                      preferences:
                        cost: 0.15
                        timeline: 0.20
                        quality: 0.35
                        usability: 0.20
                        security: 0.10
                      rationale: "AHP analysis for faculty: quality (35.0%) is most important. Consistency ratio: 0.045 (acceptable). Based on pairwise comparisons with eigenvalue calculation."
                      analysis:
                        consistencyRatio: 0.045
                        isConsistent: true
        '400':
          $ref: '#/components/responses/BadRequestError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /research-elicitation/compare-methods/{proposalId}:
    post:
      summary: Compare multiple research elicitation methods
      description: Compare results from multiple elicitation methods for the same proposal
      tags: [Research Elicitation]
      security:
        - bearerAuth: []
      parameters:
        - name: proposalId
          in: path
          required: true
          schema:
            type: string
          description: Proposal ID
          example: "507f1f77bcf86cd799439011"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MethodComparisonRequest'
            examples:
              all_methods:
                summary: Compare All Methods
                value:
                  methods: ["AHP", "Conjoint", "BWS", "DCE"]
                  stakeholderRole: "student"
              subset_methods:
                summary: Compare Subset
                value:
                  methods: ["AHP", "BWS"]
                  stakeholderRole: "faculty"
      responses:
        '200':
          description: Method comparison completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MethodComparisonResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /research-elicitation/stats:
    get:
      summary: Get research elicitation statistics
      description: Retrieve comprehensive statistics about research elicitation methods
      tags: [Research Elicitation]
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Statistics retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Research elicitation statistics retrieved"
                  data:
                    $ref: '#/components/schemas/ResearchStatistics'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /research-elicitation/methods:
    get:
      summary: Get available research elicitation methods
      description: Retrieve information about all available research elicitation methods
      tags: [Research Elicitation]
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Methods retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Available research methods retrieved"
                  data:
                    type: object
                    properties:
                      methods:
                        type: array
                        items:
                          $ref: '#/components/schemas/ResearchMethod'
                      totalMethods:
                        type: number
                        example: 4
        '500':
          $ref: '#/components/responses/InternalServerError'

  # ========================================
  # GROUP ENDPOINTS
  # ========================================
  /groups:
    get:
      summary: Get all proposal groups
      description: Retrieve all proposal groups with their details, including proposals and metadata
      tags: [Groups]
      security:
        - bearerAuth: []
      parameters:
        - name: groupType
          in: query
          schema:
            type: string
            enum: [Topic Key Grouping, Stakeholder Overlap Grouping, Submission Role Grouping, Complexity Grouping, Elicitation Method Grouping]
          description: Filter by group type
          example: "Topic Key Grouping"
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
          description: Page number for pagination
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
          description: Number of groups per page
      responses:
        '200':
          description: Groups retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Groups retrieved successfully"
                  data:
                    type: object
                    properties:
                      groups:
                        type: array
                        items:
                          $ref: '#/components/schemas/ProposalGroup'
                      totalGroups:
                        type: number
                        example: 24
                      currentPage:
                        type: number
                        example: 1
                      totalPages:
                        type: number
                        example: 3
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /groups/{groupId}:
    get:
      summary: Get specific group details with elicitation data
      description: Retrieve detailed information about a specific group including all proposals and their elicitation data
      tags: [Groups]
      security:
        - bearerAuth: []
      parameters:
        - name: groupId
          in: path
          required: true
          schema:
            type: string
          description: Group ID
          example: "507f1f77bcf86cd799439012"
      responses:
        '200':
          description: Group details retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Group details retrieved successfully"
                  data:
                    type: object
                    properties:
                      group:
                        $ref: '#/components/schemas/ProposalGroup'
                      proposals:
                        type: array
                        items:
                          $ref: '#/components/schemas/Proposal'
                      elicitations:
                        type: array
                        items:
                          $ref: '#/components/schemas/ElicitationData'
                      summaries:
                        type: array
                        items:
                          $ref: '#/components/schemas/SummaryData'
                      statistics:
                        $ref: '#/components/schemas/GroupStatistics'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /groups/{groupId}/elicitation-data:
    get:
      summary: Get elicitation data for a specific group
      description: Retrieve all elicitation data for proposals in a specific group
      tags: [Groups]
      security:
        - bearerAuth: []
      parameters:
        - name: groupId
          in: path
          required: true
          schema:
            type: string
          description: Group ID
          example: "507f1f77bcf86cd799439012"
        - name: method
          in: query
          schema:
            type: string
            enum: [AHP, Conjoint, BWS, DCE, manual, nlp-extraction, role-based-fallback, nlp-fallback, enhanced-elicitation]
          description: Filter by elicitation method
        - name: stakeholderRole
          in: query
          schema:
            type: string
            enum: [student, faculty, it_staff, admin]
          description: Filter by stakeholder role
      responses:
        '200':
          description: Elicitation data retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Elicitation data retrieved successfully"
                  data:
                    type: object
                    properties:
                      groupId:
                        type: string
                      groupName:
                        type: string
                      groupType:
                        type: string
                      totalElicitations:
                        type: number
                      methodGroups:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            $ref: '#/components/schemas/ElicitationData'
                      statistics:
                        type: object
                        properties:
                          methods:
                            type: array
                            items:
                              $ref: '#/components/schemas/ElicitationMethodStats'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /groups/types:
    get:
      summary: Get all group types and their counts
      description: Retrieve statistics about different group types and their proposal counts
      tags: [Groups]
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Group types retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Group types retrieved successfully"
                  data:
                    type: object
                    properties:
                      groupTypes:
                        type: array
                        items:
                          $ref: '#/components/schemas/GroupType'
                      totalTypes:
                        type: number
        '500':
          $ref: '#/components/responses/InternalServerError'

  # ========================================
  # ELICITATION VERIFICATION ENDPOINTS
  # ========================================
  /elicitation-verification/methods:
    get:
      summary: Get all elicitation methods with statistics
      description: Retrieve comprehensive statistics for all 9 elicitation methods
      tags: [Elicitation Verification]
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Successfully retrieved method statistics
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      coreMethods:
                        type: array
                        items:
                          $ref: '#/components/schemas/ElicitationMethodStats'
                      researchMethods:
                        type: array
                        items:
                          $ref: '#/components/schemas/ElicitationMethodStats'
                      totalElicitations:
                        type: number
                        example: 1107
                      overallStats:
                        type: object
                        properties:
                          totalMethods:
                            type: number
                            example: 9
                          avgConfidence:
                            type: number
                            example: 0.866
                          avgProcessingTime:
                            type: number
                            example: 0.06
        '500':
          $ref: '#/components/responses/InternalServerError'

  /elicitation-verification/breakdown/{method}:
    get:
      summary: Get detailed breakdown for a specific method
      description: Retrieve detailed transparency breakdown for a specific elicitation method
      tags: [Elicitation Verification]
      security:
        - bearerAuth: []
      parameters:
        - name: method
          in: path
          required: true
          schema:
            type: string
            enum: [manual, nlp-extraction, role-based-fallback, nlp-fallback, enhanced-elicitation, AHP, Conjoint, BWS, DCE]
          description: Elicitation method name
          example: "manual"
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
          description: Number of results to return
      responses:
        '200':
          description: Successfully retrieved method breakdown
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      method:
                        type: string
                        example: "manual"
                      totalElicitations:
                        type: number
                        example: 123
                      sampleBreakdowns:
                        type: array
                        items:
                          $ref: '#/components/schemas/ElicitationVerification'
                      transparencySummary:
                        type: object
                        properties:
                          commonSources:
                            type: array
                            items:
                              type: string
                          commonRationales:
                            type: array
                            items:
                              type: string
                          avgSteps:
                            type: number
                          confidenceRange:
                            type: object
                            properties:
                              min:
                                type: number
                              max:
                                type: number
                              avg:
                                type: number
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /elicitation-verification/compare/{proposalId}:
    get:
      summary: Compare all methods for a specific proposal
      description: Compare results from all 9 elicitation methods for a specific proposal
      tags: [Elicitation Verification]
      security:
        - bearerAuth: []
      parameters:
        - name: proposalId
          in: path
          required: true
          schema:
            type: string
          description: Proposal ID
          example: "507f1f77bcf86cd799439011"
      responses:
        '200':
          description: Successfully compared methods for proposal
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      proposalId:
                        type: string
                      proposalTitle:
                        type: string
                      methodComparisons:
                        type: array
                        items:
                          $ref: '#/components/schemas/ElicitationVerification'
                      comparisonMetrics:
                        type: object
                        properties:
                          preferenceVariance:
                            type: object
                            additionalProperties:
                              type: object
                              properties:
                                mean:
                                  type: number
                                variance:
                                  type: number
                                standardDeviation:
                                  type: number
                          confidenceRange:
                            type: object
                            properties:
                              min:
                                type: number
                              max:
                                type: number
                              avg:
                                type: number
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /elicitation-verification/transparency/{elicitationId}:
    get:
      summary: Get full transparency details for a specific elicitation
      description: Retrieve complete transparency breakdown for a specific elicitation result
      tags: [Elicitation Verification]
      security:
        - bearerAuth: []
      parameters:
        - name: elicitationId
          in: path
          required: true
          schema:
            type: string
          description: Elicitation ID
          example: "507f1f77bcf86cd799439011"
      responses:
        '200':
          description: Successfully retrieved transparency details
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/TransparencyBreakdown'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /elicitation-verification/export/{method}:
    get:
      summary: Export all results for a specific method
      description: Export all elicitation results for a specific method with full transparency
      tags: [Elicitation Verification]
      security:
        - bearerAuth: []
      parameters:
        - name: method
          in: path
          required: true
          schema:
            type: string
            enum: [manual, nlp-extraction, role-based-fallback, nlp-fallback, enhanced-elicitation, AHP, Conjoint, BWS, DCE]
          description: Elicitation method name
          example: "manual"
        - name: format
          in: query
          schema:
            type: string
            enum: [json, csv]
            default: json
          description: Export format
      responses:
        '200':
          description: Successfully exported method results
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      method:
                        type: string
                      totalElicitations:
                        type: number
                      exportTimestamp:
                        type: string
                        format: date-time
                      results:
                        type: array
                        items:
                          $ref: '#/components/schemas/ElicitationVerification'
            text/csv:
              schema:
                type: string
                description: CSV file with elicitation results
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained from authentication endpoint

  schemas:
    Proposal:
      type: object
      properties:
        _id:
          type: string
          description: Proposal ID
          example: "507f1f77bcf86cd799439011"
        title:
          type: string
          description: Proposal title
          example: "Student Portal Enhancement"
        description:
          type: string
          description: Detailed proposal description
          example: "A comprehensive student portal system for managing academic activities, course registration, and communication."
        submittedBy:
          $ref: '#/components/schemas/User'
        status:
          type: string
          enum: [pending, in_negotiation, finalized, rejected]
          description: Proposal status
          example: "pending"
        stakeholders:
          type: array
          items:
            type: string
            enum: [admin, it_staff, faculty, student]
          description: List of stakeholder roles
          example: ["student", "faculty"]
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp
        updatedAt:
          type: string
          format: date-time
          description: Last update timestamp

    User:
      type: object
      properties:
        _id:
          type: string
          description: User ID
          example: "507f1f77bcf86cd799439011"
        name:
          type: string
          description: User's full name
          example: "John Doe"
        email:
          type: string
          format: email
          description: User's email address
          example: "john.doe@university.edu"
        role:
          type: string
          enum: [admin, it_staff, faculty, student]
          description: User's role
          example: "student"

    EnhancedSummary:
      type: object
      properties:
        _id:
          type: string
          description: Summary ID
          example: "507f1f77bcf86cd799439011"
        proposal:
          $ref: '#/components/schemas/Proposal'
        summary:
          type: string
          description: Generated summary text
          example: "A comprehensive student portal system for managing academic activities, course registration, and communication."
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp
        updatedAt:
          type: string
          format: date-time
          description: Last update timestamp

    ProposalWithSummaries:
      type: object
      properties:
        _id:
          type: string
        title:
          type: string
        description:
          type: string
        submittedBy:
          $ref: '#/components/schemas/User'
        summaries:
          type: array
          items:
            $ref: '#/components/schemas/EnhancedSummary'
        statistics:
          type: object
          properties:
            summaryCount:
              type: number
            latestSummary:
              $ref: '#/components/schemas/EnhancedSummary'

    ProposalWithElicitation:
      type: object
      properties:
        _id:
          type: string
        title:
          type: string
        description:
          type: string
        submittedBy:
          $ref: '#/components/schemas/User'
        elicitations:
          type: array
          items:
            $ref: '#/components/schemas/ElicitationData'
        summaries:
          type: array
          items:
            $ref: '#/components/schemas/SummaryData'
        statistics:
          type: object
          properties:
            elicitationCount:
              type: number
            summaryCount:
              type: number
            elicitationMethods:
              type: array
              items:
                type: string

    ElicitationData:
      type: object
      properties:
        _id:
          type: string
          description: Elicitation ID
          example: "507f1f77bcf86cd799439011"
        proposalId:
          type: object
          properties:
            _id:
              type: string
            title:
              type: string
        stakeholderId:
          type: object
          properties:
            _id:
              type: string
            name:
              type: string
            role:
              type: string
        elicitationMethod:
          type: object
          properties:
            method:
              type: string
              enum: [AHP, Conjoint, BWS, DCE, manual, nlp-extraction, role-based-fallback, nlp-fallback, enhanced-elicitation]
            confidence:
              type: number
              minimum: 0
              maximum: 1
              description: Confidence score (0-1)
            processingTime:
              type: number
              description: Processing time in milliseconds
        preferences:
          type: object
          description: Elicited preferences
          example:
            cost: 0.15
            timeline: 0.20
            quality: 0.35
            usability: 0.20
            security: 0.10
        status:
          type: string
          enum: [completed, failed, pending]
          description: Elicitation status
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp

    SummaryData:
      type: object
      properties:
        _id:
          type: string
        proposal:
          type: object
          properties:
            _id:
              type: string
            title:
              type: string
        summary:
          type: string
        createdAt:
          type: string
          format: date-time

    ProposalGroup:
      type: object
      properties:
        _id:
          type: string
          description: Group ID
          example: "507f1f77bcf86cd799439011"
        name:
          type: string
          description: Group name
          example: "Topic Key Grouping - student_portal"
        groupType:
          type: string
          description: Type of grouping strategy
          example: "Topic Key Grouping"
        proposals:
          type: array
          items:
            type: string
          description: Array of proposal IDs
          example: ["507f1f77bcf86cd799439012", "507f1f77bcf86cd799439013"]
        criteria:
          type: object
          description: Grouping criteria
          example:
            strategy: "Topic Key Grouping"
            groupName: "student_portal"
            proposalCount: 2
        status:
          type: string
          enum: [active, inactive, archived]
          description: Group status
          example: "active"
        metadata:
          type: object
          description: Additional metadata
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp
        updatedAt:
          type: string
          format: date-time
          description: Last update timestamp

    GroupStatistics:
      type: object
      properties:
        totalProposals:
          type: number
          description: Total number of proposals in the group
        totalElicitations:
          type: number
          description: Total number of elicitations for proposals in the group
        totalSummaries:
          type: number
          description: Total number of summaries for proposals in the group
        elicitationMethods:
          type: array
          items:
            type: string
          description: List of elicitation methods used
        stakeholderRoles:
          type: array
          items:
            type: string
          description: List of stakeholder roles involved

    GroupType:
      type: object
      properties:
        _id:
          type: string
          description: Group type name
        count:
          type: number
          description: Number of groups of this type
        totalProposals:
          type: number
          description: Total proposals across all groups of this type

    ElicitationMethodStats:
      type: object
      properties:
        method:
          type: string
          description: Elicitation method name
        count:
          type: number
          description: Number of elicitations using this method
        avgConfidence:
          type: number
          description: Average confidence score for this method

    ElicitationStatistics:
      type: object
      properties:
        totalElicitations:
          type: number
        totalSummaries:
          type: number
        uniqueMethods:
          type: array
          items:
            type: string
        uniqueStakeholders:
          type: array
          items:
            type: string
        avgConfidence:
          type: number
        avgProcessingTime:
          type: number
        statusDistribution:
          type: object
          properties:
            completed:
              type: number
            failed:
              type: number
            pending:
              type: number

    SummaryStatistics:
      type: object
      properties:
        overview:
          type: object
          properties:
            totalProposals:
              type: number
            totalSummaries:
              type: number
            proposalsWithSummaries:
              type: number
            summaryCoverage:
              type: number
              description: Percentage of proposals with summaries
        summaryStats:
          type: object
          properties:
            avgLength:
              type: number
            minLength:
              type: number
            maxLength:
              type: number
            totalLength:
              type: number
        summariesByDate:
          type: array
          items:
            type: object
            properties:
              _id:
                type: object
                properties:
                  year:
                    type: number
                  month:
                    type: number
              count:
                type: number

    ResearchElicitationRequest:
      type: object
      required:
        - method
      properties:
        method:
          type: string
          enum: [AHP, Conjoint, BWS, DCE]
          description: Research elicitation method
          example: "AHP"
        stakeholderRole:
          type: string
          enum: [student, faculty, it_staff, admin]
          default: student
          description: Stakeholder role
          example: "faculty"
        options:
          type: object
          description: Method-specific options
          example: {}

    ResearchElicitationResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: "AHP elicitation completed successfully"
        data:
          type: object
          properties:
            elicitationId:
              type: string
              example: "507f1f77bcf86cd799439012"
            method:
              type: string
              example: "AHP"
            confidence:
              type: number
              example: 0.85
            processingTime:
              type: number
              example: 150
            preferences:
              type: object
              example:
                cost: 0.15
                timeline: 0.20
                quality: 0.35
                usability: 0.20
                security: 0.10
            rationale:
              type: string
              example: "AHP analysis for faculty: quality (35.0%) is most important. Consistency ratio: 0.045 (acceptable)."
            analysis:
              type: object
              properties:
                consistencyRatio:
                  type: number
                isConsistent:
                  type: boolean

    MethodComparisonRequest:
      type: object
      properties:
        methods:
          type: array
          items:
            type: string
            enum: [AHP, Conjoint, BWS, DCE]
          default: [AHP, Conjoint, BWS, DCE]
          description: List of methods to compare
        stakeholderRole:
          type: string
          enum: [student, faculty, it_staff, admin]
          default: student
          description: Stakeholder role for comparison

    MethodComparisonResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: "Method comparison completed for 4/4 methods"
        data:
          type: object
          properties:
            proposalId:
              type: string
            stakeholderRole:
              type: string
            methods:
              type: object
              additionalProperties:
                type: object
                properties:
                  success:
                    type: boolean
                  confidence:
                    type: number
                  processingTime:
                    type: number
                  preferences:
                    type: object
            statistics:
              type: object
              properties:
                totalMethods:
                  type: number
                successfulMethods:
                  type: number
                failedMethods:
                  type: number
                avgConfidence:
                  type: number
                avgProcessingTime:
                  type: number
                totalProcessingTime:
                  type: number
            comparison:
              type: object
              properties:
                bestConfidence:
                  type: number
                fastestMethod:
                  type: string

    ResearchStatistics:
      type: object
      properties:
        totalRecords:
          type: number
          example: 25
        methods:
          type: array
          items:
            type: object
            properties:
              _id:
                type: string
                example: "AHP"
              count:
                type: number
                example: 10
              avgConfidence:
                type: number
                example: 0.85
              avgProcessingTime:
                type: number
                example: 150
              totalProcessingTime:
                type: number
                example: 1500
        summary:
          type: object
          properties:
            totalMethods:
              type: number
            avgConfidence:
              type: number
            avgProcessingTime:
              type: number

    ResearchMethod:
      type: object
      properties:
        id:
          type: string
          example: "AHP"
        name:
          type: string
          example: "Analytic Hierarchy Process"
        description:
          type: string
          example: "Pairwise comparisons with consistency checking"
        confidence:
          type: string
          example: "High"
        processingTime:
          type: string
          example: "Medium"
        complexity:
          type: string
          example: "High"
        useCase:
          type: string
          example: "Complex multi-criteria decisions"

    ElicitationVerification:
      type: object
      properties:
        method:
          type: string
          description: Elicitation method name
          example: "manual"
        proposalId:
          type: string
          description: Proposal ID
          example: "507f1f77bcf86cd799439011"
        stakeholderRole:
          type: string
          description: Stakeholder role
          example: "student"
        preferences:
          type: object
          description: Extracted preferences
          properties:
            criteria:
              type: array
              items:
                type: object
                properties:
                  criterion:
                    type: string
                    example: "cost"
                  weight:
                    type: number
                    example: 0.2
                  score:
                    type: number
                    example: 2.0
                  rationale:
                    type: string
                    example: "cost preference extracted using manual method"
                  confidence:
                    type: number
                    example: 0.95
            totalWeight:
              type: number
              example: 1.0
        breakdown:
          type: object
          description: Detailed breakdown with transparency
        confidence:
          type: number
          description: Confidence score
          example: 0.95
        processingTime:
          type: number
          description: Processing time in milliseconds
          example: 0
        transparency:
          type: object
          description: Transparency details
          properties:
            source:
              type: string
              example: "constants.ROLE_WEIGHTS"
            rationale:
              type: string
              example: "Manual input based on student role preferences"
            steps:
              type: array
              items:
                type: string
              example: ["1. Identify stakeholder role", "2. Retrieve role-based weights from constants"]

    TransparencyBreakdown:
      type: object
      properties:
        elicitationId:
          type: string
          description: Elicitation ID
        method:
          type: string
          description: Elicitation method name
        proposalId:
          type: string
          description: Proposal ID
        proposalTitle:
          type: string
          description: Proposal title
        stakeholderRole:
          type: string
          description: Stakeholder role
        preferences:
          type: object
          description: Extracted preferences
        fullBreakdown:
          type: object
          description: Complete breakdown details
        transparency:
          type: object
          description: Transparency information
        confidence:
          type: number
          description: Confidence score
        processingTime:
          type: number
          description: Processing time in milliseconds
        timestamp:
          type: string
          format: date-time
          description: Creation timestamp

  responses:
    BadRequestError:
      description: Bad request - Invalid input
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              message:
                type: string
                example: "Invalid request parameters"
              error:
                type: string
                example: "Detailed error message"

    UnauthorizedError:
      description: Unauthorized - Invalid or missing token
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              message:
                type: string
                example: "Access denied. No token provided."

    ForbiddenError:
      description: Forbidden - Insufficient permissions
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              message:
                type: string
                example: "Access denied. Insufficient permissions."

    NotFoundError:
      description: Resource not found
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              message:
                type: string
                example: "Resource not found"

    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              message:
                type: string
                example: "Internal server error"
              error:
                type: string
                example: "Detailed error message"

tags:
  - name: Proposals
    description: Proposal management and retrieval
  - name: Enhanced Summaries
    description: Enhanced proposal summary management
  - name: Proposal Elicitation
    description: Proposals with their elicitation data
  - name: Research Elicitation
    description: Advanced research elicitation methods (AHP, Conjoint, BWS, DCE)
  - name: Groups
    description: Proposal grouping and elicitation data management
  - name: Elicitation Verification
    description: Comprehensive verification and transparency endpoints for all elicitation methods


