openapi: 3.0.3
info:
  title: RamEx 拉曼光谱分析系统 API
  description: |
    RamEx（Raman Expression Analysis）是一个专业的拉曼光谱数据分析平台API。

    ## 认证方式
    所有API接口（除了Token验证接口）都需要提供有效的Token进行认证。

    Token可以通过以下三种方式传递：
    1. **Authorization Header**: `Authorization: Token <your_token>`
    2. **URL参数**: `?token=<your_token>`
    3. **JSON数据**: `{"token": "<your_token>"}`

    ## 工作流程
    1. 使用第三方Token验证身份
    2. 创建项目
    3. 上传拉曼光谱数据（ZIP格式）
    4. 确认分组信息
    5. 执行数据预处理
    6. 进行无元数据分析或基于元数据分析
    7. 查看和导出结果

  version: 1.0.0
  contact:
    email: support@ramex.com
  license:
    name: BSD License

servers:
  - url: http://localhost:8000/api
    description: 本地开发服务器
  - url: http://your-domain.com/api
    description: 生产服务器

tags:
  - name: 认证
    description: Token验证和用户信息接口
  - name: 项目管理
    description: 项目的创建、查询、更新和删除
  - name: 数据管理
    description: 数据文件的上传、选择、更新和删除
  - name: 数据预处理
    description: 拉曼光谱数据预处理功能
  - name: 无元数据分析
    description: 不依赖外部元数据的分析方法
  - name: 基于元数据分析
    description: 基于元数据的高级分析方法
  - name: 结果管理
    description: 分析结果的查看和导出

components:
  securitySchemes:
    TokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Token认证，格式: Token <your_token>'

  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: 错误代码
            message:
              type: string
              description: 错误信息
      required:
        - error

    Project:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: 项目唯一标识符
          example: "7fb9352d-1797-4d8d-bed7-cc388352f65c"
        name:
          type: string
          description: 项目名称
          example: "酵母拉曼光谱分析"
        description:
          type: string
          description: 项目描述
          example: "酵母细胞在不同时间点的拉曼光谱数据分析"
        created_at:
          type: string
          format: date-time
          description: 创建时间
        last_modified:
          type: string
          format: date-time
          description: 最后修改时间
        status:
          type: string
          enum:
            - initialized
            - data_loaded
            - preprocessing
            - preprocessing_completed
            - analysis
            - completed
            - error
          description: |
            项目状态:
            - initialized: 已初始化
            - data_loaded: 数据已加载
            - preprocessing: 数据预处理中
            - preprocessing_completed: 数据预处理完成
            - analysis: 分析中
            - completed: 已完成
            - error: 出错
      required:
        - name

    ProjectDetail:
      allOf:
        - $ref: '#/components/schemas/Project'
        - type: object
          properties:
            data_files:
              type: array
              items:
                $ref: '#/components/schemas/DataFile'
              description: 项目的所有数据文件
            active_data_file:
              $ref: '#/components/schemas/DataFile'
              description: 当前活动的数据文件
            data_files_count:
              type: integer
              description: 数据文件总数

    DataFile:
      type: object
      properties:
        id:
          type: integer
          description: 文件ID
        filename:
          type: string
          description: 文件名
          example: "yeast_data.zip"
        uploaded_at:
          type: string
          format: date-time
          description: 上传时间
        wavenumber_min:
          type: number
          format: float
          description: 最小波数 (cm⁻¹)
          example: 500.0
        wavenumber_max:
          type: number
          format: float
          description: 最大波数 (cm⁻¹)
          example: 3150.0
        group_index:
          type: integer
          description: 分组索引（文件名中用于分组的部分位置）
          example: 2

    TokenValidationResponse:
      type: object
      properties:
        valid:
          type: boolean
          description: Token是否有效
        message:
          type: string
          description: 验证消息
        user_info:
          type: object
          properties:
            third_party_username:
              type: string
              description: 第三方用户名
            local_user_exists:
              type: boolean
              description: 本地用户是否已存在
            local_username:
              type: string
              description: 本地用户名
            local_user_id:
              type: integer
              description: 本地用户ID
        token_info:
          type: object
          properties:
            token_preview:
              type: string
              description: Token预览
            token_length:
              type: integer
              description: Token长度

    UserInfo:
      type: object
      properties:
        user_info:
          type: object
          properties:
            local_user_id:
              type: integer
              description: 本地用户ID
            local_username:
              type: string
              description: 本地用户名
            email:
              type: string
              description: 邮箱
            date_joined:
              type: string
              format: date-time
              description: 注册时间
            last_login:
              type: string
              format: date-time
              description: 最后登录时间
        third_party_info:
          type: object
          properties:
            third_party_user_id:
              type: integer
              description: 第三方用户ID
            third_party_username:
              type: string
              description: 第三方用户名
            created_at:
              type: string
              format: date-time
              description: 映射创建时间
        statistics:
          type: object
          properties:
            projects_count:
              type: integer
              description: 项目总数
        data_directories:
          type: object
          properties:
            user_base_dir:
              type: string
              description: 用户基础目录
            projects_dir:
              type: string
              description: 项目目录

paths:
  /token/validate/:
    post:
      tags:
        - 认证
      summary: 验证Token
      description: |
        验证Token的有效性并获取用户信息。
        此接口不需要认证，用于首次验证Token。
      operationId: validateToken
      security: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                token:
                  type: string
                  description: 要验证的Token
                  example: "0c47b3d5b1aa561a5032f50e95bf069afa9a9e55"
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                token:
                  type: string
      parameters:
        - name: token
          in: query
          description: Token（也可以通过URL参数传递）
          schema:
            type: string
      responses:
        '200':
          description: Token验证成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenValidationResponse'
        '400':
          description: Token参数缺失
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Token无效或已过期
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    get:
      tags:
        - 认证
      summary: 验证Token（GET方式）
      description: 通过GET方法验证Token，Token通过URL参数传递
      operationId: validateTokenGet
      security: []
      parameters:
        - name: token
          in: query
          required: true
          description: 要验证的Token
          schema:
            type: string
      responses:
        '200':
          description: Token验证成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenValidationResponse'
        '400':
          description: Token参数缺失
        '401':
          description: Token无效

  /user/info/:
    get:
      tags:
        - 认证
      summary: 获取当前用户信息
      description: 获取已认证用户的详细信息，包括本地用户信息、第三方映射信息和统计数据
      operationId: getUserInfo
      security:
        - TokenAuth: []
      responses:
        '200':
          description: 成功获取用户信息
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserInfo'
        '401':
          description: 用户未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /projects/:
    get:
      tags:
        - 项目管理
      summary: 获取项目列表
      description: 获取当前用户的所有项目列表
      operationId: listProjects
      security:
        - TokenAuth: []
      responses:
        '200':
          description: 成功获取项目列表
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Project'
        '401':
          description: 未授权

    post:
      tags:
        - 项目管理
      summary: 创建新项目
      description: 创建一个新的拉曼光谱分析项目
      operationId: createProject
      security:
        - TokenAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: 项目名称
                  example: "酵母拉曼光谱分析"
                description:
                  type: string
                  description: 项目描述
                  example: "酵母细胞在不同时间点的拉曼光谱数据分析"
              required:
                - name
      responses:
        '201':
          description: 项目创建成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Project'
                  - type: object
                    properties:
                      next_steps:
                        type: array
                        items:
                          type: object
                          properties:
                            step:
                              type: string
                            url:
                              type: string
                            description:
                              type: string
        '400':
          description: 请求参数错误
        '401':
          description: 未授权

  /projects/{project_id}/:
    get:
      tags:
        - 项目管理
      summary: 获取项目详情
      description: 获取指定项目的详细信息，包括所有数据文件
      operationId: getProject
      security:
        - TokenAuth: []
      parameters:
        - name: project_id
          in: path
          required: true
          description: 项目UUID
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: 成功获取项目详情
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectDetail'
        '404':
          description: 项目不存在

    put:
      tags:
        - 项目管理
      summary: 更新项目（完整更新）
      description: 完整更新项目信息
      operationId: updateProject
      security:
        - TokenAuth: []
      parameters:
        - name: project_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                description:
                  type: string
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '404':
          description: 项目不存在

    patch:
      tags:
        - 项目管理
      summary: 更新项目（部分更新）
      description: 部分更新项目信息
      operationId: partialUpdateProject
      security:
        - TokenAuth: []
      parameters:
        - name: project_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                description:
                  type: string
      responses:
        '200':
          description: 更新成功
        '404':
          description: 项目不存在

    delete:
      tags:
        - 项目管理
      summary: 删除项目
      description: 删除项目及其所有关联的数据文件
      operationId: deleteProject
      security:
        - TokenAuth: []
      parameters:
        - name: project_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: 删除成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "success"
                  message:
                    type: string
                    example: "项目已成功删除"
        '404':
          description: 项目不存在
        '500':
          description: 删除文件时出错

  /projects/{project_id}/data/upload/:
    post:
      tags:
        - 数据管理
      summary: 上传数据文件
      description: |
        上传拉曼光谱数据文件（ZIP格式）。
        ZIP文件应包含多个.txt格式的拉曼光谱数据文件。
      operationId: uploadData
      security:
        - TokenAuth: []
      parameters:
        - name: project_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                files:
                  type: string
                  format: binary
                  description: ZIP格式的数据文件
                group_index:
                  type: integer
                  description: 分组索引（文件名中用于分组的部分位置，按下划线分隔）
                  default: 2
                  example: 2
                Wavenumber range:
                  type: string
                  description: 波数范围，格式为"最小值,最大值"
                  example: "500,3150"
              required:
                - files
      responses:
        '200':
          description: 上传成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "success"
                  group_names:
                    type: array
                    items:
                      type: string
                    description: 检测到的分组名称
                    example: ["Control", "Treatment"]
                  next_steps:
                    type: array
                    items:
                      type: object
                  message:
                    type: string
        '400':
          description: 请求参数错误
        '404':
          description: 项目不存在
        '500':
          description: 处理文件时出错

  /projects/{project_id}/data/group_info/:
    get:
      tags:
        - 数据管理
      summary: 获取分组信息
      description: 获取当前活动数据文件的分组信息
      operationId: getGroupInfo
      security:
        - TokenAuth: []
      parameters:
        - name: project_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: 成功获取分组信息
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  group_names:
                    type: array
                    items:
                      type: string
        '400':
          description: 项目没有活动数据文件
        '404':
          description: 项目不存在

  /projects/{project_id}/data/save_rds/:
    post:
      tags:
        - 数据管理
      summary: 保存确认的RDS数据
      description: 确认分组信息并保存RDS数据文件
      operationId: saveRdsData
      security:
        - TokenAuth: []
      parameters:
        - name: project_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                group_order:
                  type: array
                  items:
                    type: string
                  description: 分组顺序（可选）
                  example: ["Control", "Treatment"]
      responses:
        '200':
          description: 保存成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  message:
                    type: string
                  next_url:
                    type: string
        '400':
          description: 项目没有活动数据文件
        '404':
          description: 项目不存在

  /projects/{project_id}/data/{file_id}/select/:
    post:
      tags:
        - 数据管理
      summary: 选择活动数据文件
      description: 将指定的数据文件设置为当前活动文件
      operationId: selectDataFile
      security:
        - TokenAuth: []
      parameters:
        - name: project_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: file_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 设置成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  message:
                    type: string
                  active_file:
                    $ref: '#/components/schemas/DataFile'
        '404':
          description: 项目或文件不存在

  /projects/{project_id}/data/{file_id}/update/:
    post:
      tags:
        - 数据管理
      summary: 更新数据文件
      description: 更新数据文件的波数范围
      operationId: updateDataFile
      security:
        - TokenAuth: []
      parameters:
        - name: project_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: file_id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                wavenumber_range:
                  type: string
                  description: 波数范围，格式为"最小值,最大值"
                  example: "500,3150"
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  message:
                    type: string
                  data_file:
                    $ref: '#/components/schemas/DataFile'
        '400':
          description: 波数范围格式无效
        '404':
          description: 项目或文件不存在

  /projects/{project_id}/data/{file_id}/delete/:
    delete:
      tags:
        - 数据管理
      summary: 删除数据文件
      description: 删除指定的数据文件
      operationId: deleteDataFile
      security:
        - TokenAuth: []
      parameters:
        - name: project_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: file_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 删除成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  message:
                    type: string
        '404':
          description: 项目或文件不存在

  /projects/{project_id}/preprocessing/status/:
    get:
      tags:
        - 数据预处理
      summary: 获取预处理状态
      description: 获取项目的最新预处理任务状态
      operationId: getPreprocessingStatus
      security:
        - TokenAuth: []
      parameters:
        - name: project_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: 成功获取状态
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum: [not_started, processing, completed, error]
                  parameters:
                    type: object
                    description: 预处理参数
                  result:
                    type: object
                    description: 预处理结果
        '404':
          description: 项目不存在

  /projects/{project_id}/preprocessing/:
    post:
      tags:
        - 数据预处理
      summary: 执行数据预处理
      description: |
        对拉曼光谱数据执行预处理操作。

        预处理包括：
        - 质量控制（异常值检测）
        - 峰值去除（宇宙射线）
        - 平滑处理
        - 标准化
        - 基线校正
      operationId: runPreprocessing
      security:
        - TokenAuth: []
      parameters:
        - name: project_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                quality_control:
                  type: object
                  description: 质量控制参数
                  properties:
                    euclidean_distance:
                      type: object
                      properties:
                        enabled:
                          type: boolean
                        max_distance:
                          type: number
                    snr:
                      type: object
                      properties:
                        enabled:
                          type: boolean
                        strictness:
                          type: string
                          enum: [low, medium, high]
                spike_removal:
                  type: object
                  description: 峰值去除参数
                  properties:
                    enabled:
                      type: boolean
                    intensity:
                      type: number
                smoothing:
                  type: object
                  description: 平滑处理参数
                  properties:
                    method:
                      type: string
                      enum: [savitzky_golay, whittaker, moving_average]
                    window_size:
                      type: integer
                normalization:
                  type: object
                  description: 标准化参数
                  properties:
                    method:
                      type: string
                      enum: [minmax, zscore, vector, area]
                baseline_correction:
                  type: object
                  description: 基线校正参数
                  properties:
                    method:
                      type: string
                      enum: [polynomial, als]
                    degree:
                      type: integer
      responses:
        '200':
          description: 预处理完成
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  message:
                    type: string
                  plot_url:
                    type: string
                    description: 预处理结果图表URL
                  result:
                    type: object
        '400':
          description: 项目状态不适合进行预处理
        '404':
          description: 项目不存在
        '500':
          description: 预处理执行失败

  /projects/{project_id}/preprocessing/export/:
    get:
      tags:
        - 数据预处理
      summary: 导出预处理数据
      description: 下载预处理后的RDS数据文件
      operationId: exportPreprocessing
      security:
        - TokenAuth: []
      parameters:
        - name: project_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: 文件下载
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '404':
          description: 项目或文件不存在

  /projects/{project_id}/meta-free/status/:
    get:
      tags:
        - 无元数据分析
      summary: 获取无元数据分析状态
      description: 获取项目的最新无元数据分析任务状态
      operationId: getMetaFreeStatus
      security:
        - TokenAuth: []
      parameters:
        - name: project_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: 成功获取状态
        '404':
          description: 项目不存在

  /projects/{project_id}/meta-free/:
    post:
      tags:
        - 无元数据分析
      summary: 执行无元数据分析
      description: |
        执行不依赖外部元数据的分析方法。

        支持的分析方法：
        - 降维分析（PCA、LDA、ICA）
        - 聚类分析（K-means、层次聚类）
        - 多维度尺度分析（MDS）
        - 光谱分解（NMF）
        - 峰值检测和分析
      operationId: runMetaFreeAnalysis
      security:
        - TokenAuth: []
      parameters:
        - name: project_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                analysis_methods:
                  type: array
                  items:
                    type: string
                    enum: [pca, lda, ica, kmeans, hierarchical, mds, nmf, peak_detection]
                  description: 要执行的分析方法列表
                parameters:
                  type: object
                  description: 各分析方法的参数
                  properties:
                    pca:
                      type: object
                      properties:
                        n_components:
                          type: integer
                          description: 主成分数量
                    lda:
                      type: object
                      properties:
                        n_components:
                          type: integer
                    kmeans:
                      type: object
                      properties:
                        n_clusters:
                          type: integer
                          description: 聚类数量
      responses:
        '200':
          description: 分析完成
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  message:
                    type: string
                  result:
                    type: object
        '400':
          description: 项目状态不适合进行分析
        '404':
          description: 项目不存在
        '500':
          description: 分析执行失败

  /projects/{project_id}/meta-free/results/:
    get:
      tags:
        - 无元数据分析
      summary: 获取无元数据分析结果
      description: 获取无元数据分析的结果数据
      operationId: getMetaFreeResults
      security:
        - TokenAuth: []
      parameters:
        - name: project_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: 成功获取结果
          content:
            application/json:
              schema:
                type: object
        '404':
          description: 项目不存在或无结果

  /projects/{project_id}/meta-free/export/:
    get:
      tags:
        - 无元数据分析
      summary: 导出无元数据分析结果
      description: 下载无元数据分析结果文件
      operationId: exportMetaFreeResults
      security:
        - TokenAuth: []
      parameters:
        - name: project_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: format
          in: query
          description: 导出格式
          schema:
            type: string
            enum: [png, svg, pdf, csv, rds]
      responses:
        '200':
          description: 文件下载
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '404':
          description: 项目或结果不存在

  /projects/{project_id}/meta-based/status/:
    get:
      tags:
        - 基于元数据分析
      summary: 获取基于元数据分析状态
      description: 获取项目的最新基于元数据分析任务状态
      operationId: getMetaBasedStatus
      security:
        - TokenAuth: []
      parameters:
        - name: project_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: 成功获取状态
        '404':
          description: 项目不存在

  /projects/{project_id}/meta-based/:
    post:
      tags:
        - 基于元数据分析
      summary: 执行基于元数据分析
      description: |
        执行基于元数据的高级分析方法。

        支持的分析方法：
        - 分类分析（SVM、随机森林、逻辑回归）
        - 回归分析（线性回归、PLSR）
        - 统计检验（ANOVA、多重比较、非参数检验）
        - 生物标志物发现
      operationId: runMetaBasedAnalysis
      security:
        - TokenAuth: []
      parameters:
        - name: project_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                metadata_file:
                  type: string
                  format: binary
                  description: 元数据CSV文件
                analysis_methods:
                  type: string
                  description: 分析方法列表（JSON字符串）
                parameters:
                  type: string
                  description: 分析参数（JSON字符串）
      responses:
        '200':
          description: 分析完成
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  message:
                    type: string
                  result:
                    type: object
        '400':
          description: 项目状态不适合进行分析或元数据文件格式错误
        '404':
          description: 项目不存在
        '500':
          description: 分析执行失败

  /projects/{project_id}/meta-based/results/:
    get:
      tags:
        - 基于元数据分析
      summary: 获取基于元数据分析结果
      description: 获取基于元数据分析的结果数据
      operationId: getMetaBasedResults
      security:
        - TokenAuth: []
      parameters:
        - name: project_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: 成功获取结果
          content:
            application/json:
              schema:
                type: object
        '404':
          description: 项目不存在或无结果

  /projects/{project_id}/meta-based/export/:
    get:
      tags:
        - 基于元数据分析
      summary: 导出基于元数据分析结果
      description: 下载基于元数据分析结果文件
      operationId: exportMetaBasedResults
      security:
        - TokenAuth: []
      parameters:
        - name: project_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: format
          in: query
          description: 导出格式
          schema:
            type: string
            enum: [png, svg, pdf, csv, excel, rds]
      responses:
        '200':
          description: 文件下载
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '404':
          description: 项目或结果不存在

  /projects/{project_id}/results/summary/:
    get:
      tags:
        - 结果管理
      summary: 获取结果摘要
      description: 获取项目所有分析结果的摘要信息
      operationId: getResultsSummary
      security:
        - TokenAuth: []
      parameters:
        - name: project_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: 成功获取结果摘要
          content:
            application/json:
              schema:
                type: object
                properties:
                  project_info:
                    $ref: '#/components/schemas/Project'
                  preprocessing_status:
                    type: string
                  meta_free_status:
                    type: string
                  meta_based_status:
                    type: string
                  available_exports:
                    type: array
                    items:
                      type: string
        '404':
          description: 项目不存在

  /projects/{project_id}/results/export/:
    post:
      tags:
        - 结果管理
      summary: 创建导出任务
      description: 创建一个结果导出任务
      operationId: createExportTask
      security:
        - TokenAuth: []
      parameters:
        - name: project_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                format:
                  type: string
                  enum: [zip, pdf, excel]
                  description: 导出格式
                components:
                  type: array
                  items:
                    type: string
                  description: 要导出的组件列表
                  example: ["preprocessing", "pca", "lda"]
      responses:
        '201':
          description: 导出任务创建成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  export_id:
                    type: string
                    format: uuid
                  status:
                    type: string
                  message:
                    type: string
        '400':
          description: 请求参数错误
        '404':
          description: 项目不存在

  /projects/{project_id}/results/export/{export_id}/:
    get:
      tags:
        - 结果管理
      summary: 获取导出任务状态
      description: 获取指定导出任务的状态和下载链接
      operationId: getExportStatus
      security:
        - TokenAuth: []
      parameters:
        - name: project_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: export_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: 成功获取导出状态
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum: [pending, processing, completed, error]
                  download_url:
                    type: string
                    description: 下载链接（仅当status为completed时）
                  created_at:
                    type: string
                    format: date-time
                  completed_at:
                    type: string
                    format: date-time
        '404':
          description: 项目或导出任务不存在