ars-backend/docs/ChatSession/chat-session-openapi.yaml

openapi: 3.0.3
info:
  title: ChatSession & Message API
  version: 1.0.0
  description: |
    ChatSession & Message MVP-1，支持会话创建、消息追加、增量查询。自然语言：中文。
servers:
  - url: http://localhost:8000/api
    description: 本地开发（FrankenPHP / Docker）
tags:
  - name: ChatSession
    description: 会话管理与消息
paths:
  /sessions:
    post:
      tags: [ChatSession]
      summary: 创建会话
      security:
        - bearerAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSessionRequest'
      responses:
        "201":
          description: 创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatSession'
        "401":
          description: 未授权
    get:
      tags: [ChatSession]
      summary: 会话列表
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: page
          schema:
            type: integer
            default: 1
        - in: query
          name: per_page
          schema:
            type: integer
            default: 15
            maximum: 100
        - in: query
          name: status
          schema:
            type: string
            enum: [OPEN, LOCKED, CLOSED]
        - in: query
          name: q
          schema:
            type: string
          description: 模糊匹配 session_name
      responses:
        "200":
          description: 分页会话列表
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ChatSession'
                  links:
                    $ref: '#/components/schemas/PaginationLinks'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
        "401":
          description: 未授权
  /sessions/{session_id}/messages:
    post:
      tags: [ChatSession]
      summary: 追加消息（含幂等与状态门禁）
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: session_id
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppendMessageRequest'
      responses:
        "201":
          description: 追加成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResource'
        "403":
          description: 状态门禁禁止
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "401":
          description: 未授权
    get:
      tags: [ChatSession]
      summary: 按 seq 增量查询消息
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: session_id
          required: true
          schema:
            type: string
            format: uuid
        - in: query
          name: after_seq
          schema:
            type: integer
            default: 0
          description: 仅返回 seq 大于该值的消息
        - in: query
          name: limit
          schema:
            type: integer
            default: 50
            maximum: 200
          description: 返回数量上限
      responses:
        "200":
          description: 按 seq 升序的消息列表
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/MessageResource'
        "401":
          description: 未授权
  /sessions/{session_id}:
    patch:
      tags: [ChatSession]
      summary: 更新会话（重命名/状态）
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: session_id
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSessionRequest'
      responses:
        "200":
          description: 更新成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatSession'
        "403":
          description: 状态门禁禁止
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "422":
          description: 校验失败
        "401":
          description: 未授权
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    ChatSession:
      type: object
      properties:
        session_id:
          type: string
          format: uuid
        session_name:
          type: string
          nullable: true
        status:
          type: string
          enum: [OPEN, LOCKED, CLOSED]
        last_seq:
          type: integer
        last_message_id:
          type: string
          format: uuid
          nullable: true
        last_message_at:
          type: string
          format: date-time
          nullable: true
        last_message_preview:
          type: string
        last_message_role:
          type: string
          nullable: true
        last_message_type:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    CreateSessionRequest:
      type: object
      properties:
        session_name:
          type: string
          maxLength: 255
    UpdateSessionRequest:
      type: object
      properties:
        session_name:
          type: string
          minLength: 1
          maxLength: 255
        status:
          type: string
          enum: [OPEN, LOCKED, CLOSED]
    AppendMessageRequest:
      type: object
      required: [role, type]
      properties:
        role:
          type: string
          enum: [USER, AGENT, TOOL, SYSTEM]
        type:
          type: string
          maxLength: 64
          example: user.prompt
        content:
          type: string
          nullable: true
        payload:
          type: object
          nullable: true
        reply_to:
          type: string
          format: uuid
          nullable: true
        dedupe_key:
          type: string
          maxLength: 128
          nullable: true
    MessageResource:
      type: object
      properties:
        message_id:
          type: string
          format: uuid
        session_id:
          type: string
          format: uuid
        seq:
          type: integer
        role:
          type: string
          enum: [USER, AGENT, TOOL, SYSTEM]
        type:
          type: string
        content:
          type: string
          nullable: true
        payload:
          type: object
          nullable: true
        reply_to:
          type: string
          format: uuid
          nullable: true
        dedupe_key:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
    Error:
      type: object
      properties:
        message:
          type: string
          example: Session is closed
    PaginationLinks:
      type: object
      properties:
        first:
          type: string
          example: http://localhost:8000/api/sessions?page=1
        last:
          type: string
          example: http://localhost:8000/api/sessions?page=1
        prev:
          type: string
          nullable: true
        next:
          type: string
          nullable: true
    PaginationMeta:
      type: object
      properties:
        current_page:
          type: integer
        from:
          type: integer
          nullable: true
        last_page:
          type: integer
        path:
          type: string
        per_page:
          type: integer
        to:
          type: integer
          nullable: true
        total:
          type: integer