openapi: 3.0.3
info:
  title: SmartFlow Agent Query API
  version: 0.8.0
  description: Agent 会话列表与聊天历史查询接口。
servers:
  - url: http://localhost:8080
paths:
  /api/v1/agent/conversation-list:
    get:
      tags:
        - Agent
      summary: 获取 Agent 会话列表
      description: |
        获取当前登录用户的 Agent 会话列表。
        支持历史分页参数 `page/page_size`，并兼容懒加载参数 `limit`。
        当同时传入 `page_size` 与 `limit` 时，以 `limit` 为准。
      security:
        - BearerAuth: []
      parameters:
        - name: page
          in: query
          description: 页码，默认 1。
          required: false
          schema:
            type: integer
            minimum: 1
            example: 1
        - name: page_size
          in: query
          description: 历史分页页大小，默认 20。
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            example: 20
        - name: limit
          in: query
          description: 懒加载条数，作为 `page_size` 的别名使用。
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            example: 20
        - name: status
          in: query
          description: 会话状态过滤，仅支持 `active` 或 `archived`。
          required: false
          schema:
            type: string
            enum:
              - active
              - archived
            example: active
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationListEnvelope'
              examples:
                success:
                  value:
                    status: "10000"
                    info: success
                    data:
                      list:
                        - conversation_id: 8df59142-29a2-4bf6-85b6-c5e3f4e9cb89
                          title: 明天课程与任务安排
                          has_title: true
                          message_count: 14
                          last_message_at: "2026-03-24T22:18:45+08:00"
                          status: active
                          created_at: "2026-03-24T20:01:12+08:00"
                      page: 1
                      page_size: 20
                      limit: 20
                      total: 1
                      has_more: false
        '400':
          description: 参数错误或会话状态非法
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 未登录或 token 无效
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/agent/conversation-history:
    get:
      tags:
        - Agent
      summary: 获取 Agent 会话聊天历史
      description: |
        获取指定会话的聊天历史。
        服务端会先校验会话是否属于当前用户，再优先读取 Redis，
        Redis 未命中时回源数据库，并把结果回填到 Redis。
      security:
        - BearerAuth: []
      parameters:
        - name: conversation_id
          in: query
          description: 会话 ID。
          required: true
          schema:
            type: string
            format: uuid
            example: 8df59142-29a2-4bf6-85b6-c5e3f4e9cb89
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationHistoryEnvelope'
              examples:
                success:
                  value:
                    status: "10000"
                    info: success
                    data:
                      - id: 101
                        role: user
                        content: 帮我看下明天最重要的任务
                        created_at: "2026-03-24T22:15:01+08:00"
                      - id: 102
                        role: assistant
                        content: 明天优先处理数据库联调和接口验收。
                        created_at: "2026-03-24T22:15:06+08:00"
        '400':
          description: 缺少参数或会话不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 未登录或 token 无效
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    ErrorResponse:
      type: object
      required:
        - status
        - info
      properties:
        status:
          type: string
          example: "40005"
        info:
          type: string
          example: wrong param type
    ConversationListEnvelope:
      type: object
      required:
        - status
        - info
        - data
      properties:
        status:
          type: string
          example: "10000"
        info:
          type: string
          example: success
        data:
          $ref: '#/components/schemas/ConversationListResponse'
    ConversationListResponse:
      type: object
      required:
        - list
        - page
        - page_size
        - limit
        - total
        - has_more
      properties:
        list:
          type: array
          items:
            $ref: '#/components/schemas/ConversationListItem'
        page:
          type: integer
          example: 1
        page_size:
          type: integer
          example: 20
        limit:
          type: integer
          description: 当前实际使用的懒加载条数。
          example: 20
        total:
          type: integer
          format: int64
          example: 56
        has_more:
          type: boolean
          example: true
    ConversationListItem:
      type: object
      required:
        - conversation_id
        - title
        - has_title
        - message_count
        - status
      properties:
        conversation_id:
          type: string
          format: uuid
        title:
          type: string
          example: 明天课程与任务安排
        has_title:
          type: boolean
          example: true
        message_count:
          type: integer
          example: 14
        last_message_at:
          type: string
          format: date-time
          nullable: true
        status:
          type: string
          example: active
        created_at:
          type: string
          format: date-time
          nullable: true
    ConversationHistoryEnvelope:
      type: object
      required:
        - status
        - info
        - data
      properties:
        status:
          type: string
          example: "10000"
        info:
          type: string
          example: success
        data:
          type: array
          items:
            $ref: '#/components/schemas/ConversationHistoryItem'
    ConversationHistoryItem:
      type: object
      required:
        - role
        - content
      properties:
        id:
          type: integer
          description: 数据库主键；命中 Redis 时可能为空。
          example: 102
        role:
          type: string
          enum:
            - user
            - assistant
            - system
          example: assistant
        content:
          type: string
          example: 明天优先处理数据库联调和接口验收。
        created_at:
          type: string
          format: date-time
          nullable: true
        reasoning_content:
          type: string
          description: 推理内容；命中数据库历史时通常为空。
          example: ""