openapi: 3.0.3
info:
  title: Comment API
  description: 评论系统API接口定义
  version: 1.0.0
  contact:
    name: API Support
    email: support@example.com
servers:
  - url: 'http://localhost:8080'
    description: 本地开发环境
  - url: "https://dec-dev.k3d.kuaizu.cn/application/comment"
    description: 开发环境
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    BaseResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          description: 返回码，0表示成功，非0表示错误
          example: 0
        message:
          type: string
          description: 返回信息
          example: "success"
    ErrorResponse:
      allOf:
        - $ref: '#/components/schemas/BaseResponse'
        - type: object
          properties:
            data:
              type: object
              nullable: true
    CommentStatus:
      type: integer
      enum: [1, 2, 3]
      x-enum-varnames: [Pending, Approved, Rejected]
      x-enum-descriptions: ["待审核", "已审核", "已拒绝"]
    ReplyStatus:
      type: integer
      enum: [1, 2, 3]
      x-enum-varnames: [Pending, Approved, Rejected]
      x-enum-descriptions: ["待审核", "已审核", "已拒绝"]
    ReviewStatus:
      type: integer
      enum: [2, 3]
      x-enum-varnames: [Approved, Rejected]
      x-enum-descriptions: ["已审核", "已拒绝"]
    CommentData:
      type: object
      properties:
        id:
          type: integer
          description: 评论ID
        orderId:
          type: integer
          description: 订单ID
        productId:
          type: integer
          description: 商品ID
        userId:
          type: integer
          description: 用户ID
        vendorId:
          type: integer
          description: 供应商ID
        storeId:
          type: integer
          description: 店铺ID
        processRating:
          type: integer
          description: 体验流程评分（1-5分）
          minimum: 1
          maximum: 5
        serviceRating:
          type: integer
          description: 服务态度评分（1-5分）
          minimum: 1
          maximum: 5
        priceRating:
          type: integer
          description: 租赁价格评分（1-5分）
          minimum: 1
          maximum: 5
        repurchaseScore:
          type: integer
          description: 再次租赁/购买意愿（0-10分）
          minimum: 0
          maximum: 10
        recommendScore:
          type: integer
          description: 推荐意愿（0-10分）
          minimum: 0
          maximum: 10
        content:
          type: string
          description: 评论内容
        status:
          $ref: '#/components/schemas/CommentStatus'
        createdAt:
          type: string
          format: date-time
          description: 创建时间
        updatedAt:
          type: string
          format: date-time
          description: 更新时间
        userInfo:
          type: object
          description: 用户信息
          properties:
            username:
              type: string
              description: 用户名
            nickname:
              type: string
              description: 用户昵称
            avatar:
              type: string
              description: 用户头像
        productInfo:
          type: object
          description: 商品信息
          properties:
            name:
              type: string
              description: 商品名称
            image:
              type: string
              description: 商品图片
            price:
              type: number
              format: float
              description: 商品价格
        order:
          type: object
          description: 订单信息
          properties:
            storeName:
              type: string
              description: 门店名称
            rentStartTime:
              type: string
              description: 租赁开始时间
            rentEndTime:
              type: string
              description: 租赁结束时间
            rentDays:
              type: integer
              description: 租赁天数
            innerTradeNo:
              type: string
              description: 内部交易号
        reply:
          $ref: '#/components/schemas/ReplyData'
    ReplyData:
      type: object
      properties:
        id:
          type: integer
          description: 回复ID
        userId:
          type: integer
          description: 回复用户ID
        content:
          type: string
          description: 回复内容
        status:
          $ref: '#/components/schemas/ReplyStatus'
        createdAt:
          type: string
          format: date-time
          description: 创建时间
        updatedAt:
          type: string
          format: date-time
          description: 更新时间
        userInfo:
          type: object
          description: 回复用户信息
          properties:
            username:
              type: string
              description: 用户名
            nickname:
              type: string
              description: 用户昵称
            avatar:
              type: string
              description: 用户头像
    CommentResponse:
      allOf:
        - $ref: '#/components/schemas/BaseResponse'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/CommentData'
    CommentListResponse:
      allOf:
        - $ref: '#/components/schemas/BaseResponse'
        - type: object
          properties:
            data:
              type: object
              properties:
                total:
                  type: integer
                  description: 总记录数
                list:
                  type: array
                  items:
                    $ref: '#/components/schemas/CommentData'
    CommentCreateRequest:
      type: object
      required:
        - orderId
        - productId
        - userId
        - vendorId
        - storeId
        - processRating
        - serviceRating
        - priceRating
      properties:
        orderId:
          type: integer
          description: 订单ID
          x-oapi-codegen-extra-tags:
            binding: "required"
            validate: "required"
        productId:
          type: integer
          description: 商品ID
          x-oapi-codegen-extra-tags:
            binding: "required"
            validate: "required"
        userId:
          type: integer
          description: 用户ID
          x-oapi-codegen-extra-tags:
            binding: "required"
            validate: "required"
        vendorId:
          type: integer
          description: 供应商ID
          x-oapi-codegen-extra-tags:
            binding: "required"
            validate: "required"
        storeId:
          type: integer
          description: 店铺ID
          x-oapi-codegen-extra-tags:
            binding: "required"
            validate: "required"
        processRating:
          type: integer
          description: 体验流程评分（1-5分）
          minimum: 1
          maximum: 5
          x-oapi-codegen-extra-tags:
            binding: "required,min=1,max=5"
            validate: "required,min=1,max=5"
        serviceRating:
          type: integer
          description: 服务态度评分（1-5分）
          minimum: 1
          maximum: 5
          x-oapi-codegen-extra-tags:
            binding: "required,min=1,max=5"
            validate: "required,min=1,max=5"
        priceRating:
          type: integer
          description: 租赁价格评分（1-5分）
          minimum: 1
          maximum: 5
          x-oapi-codegen-extra-tags:
            binding: "required,min=1,max=5"
            validate: "required,min=1,max=5"
        repurchaseScore:
          type: integer
          description: 再次租赁/购买意愿（0-10分）
          minimum: 0
          maximum: 10
          x-oapi-codegen-extra-tags:
            binding: "omitempty,min=0,max=10"
            validate: "omitempty,min=0,max=10"
        recommendScore:
          type: integer
          description: 推荐意愿（0-10分）
          minimum: 0
          maximum: 10
          x-oapi-codegen-extra-tags:
            binding: "omitempty,min=0,max=10"
            validate: "omitempty,min=0,max=10"
        content:
          type: string
          description: 评论内容
          x-oapi-codegen-extra-tags:
            binding: "omitempty"
            validate: "omitempty"
        userName:
          type: string
          description: 用户名
          x-oapi-codegen-extra-tags:
            binding: "omitempty"
            validate: "omitempty"
    CommentReviewRequest:
      type: object
      required:
        - status
      properties:
        status:
          $ref: '#/components/schemas/ReviewStatus'
          x-oapi-codegen-extra-tags:
            binding: "required,oneof=1 2"
            validate: "required,oneof=1 2"
        reviewReason:
          type: string
          description: 审核原因
          x-oapi-codegen-extra-tags:
            binding: "omitempty"
            validate: "omitempty"
    ReplyCreateRequest:
      type: object
      required:
        - userId
        - content
      properties:
        userId:
          type: integer
          description: 回复用户ID
          x-oapi-codegen-extra-tags:
            binding: "required"
            validate: "required"
        content:
          type: string
          description: 回复内容
          x-oapi-codegen-extra-tags:
            binding: "required"
            validate: "required"
paths:
  # 评论列表
  /comments:
    get:
      operationId: ListComments
      summary: 获取评论列表
      description: 分页获取评论列表，支持多种筛选条件
      tags:
        - comment
      security:
        - BearerAuth: []
      parameters:
        - name: pageNum
          in: query
          required: false
          description: 页码，从1开始
          schema:
            type: integer
            default: 1
          x-oapi-codegen-extra-tags:
            binding: "omitempty,min=1"
            validate: "omitempty,min=1"
        - name: pageSize
          in: query
          required: false
          description: 每页条数
          schema:
            type: integer
            default: 20
          x-oapi-codegen-extra-tags:
            binding: "omitempty,min=1,max=100"
            validate: "omitempty,min=1,max=100"
        - name: productId
          in: query
          required: false
          description: 商品ID
          schema:
            type: integer
          x-oapi-codegen-extra-tags:
            binding: "omitempty"
            validate: "omitempty"
        - name: orderId
          in: query
          required: false
          description: 订单ID
          schema:
            type: integer
          x-oapi-codegen-extra-tags:
            binding: "omitempty"
            validate: "omitempty"
        - name: statuses
          in: query
          required: false
          description: 评论状态
          schema:
            type: array
            items:
              $ref: '#/components/schemas/CommentStatus'
          style: form
          explode: false
          x-oapi-codegen-extra-tags:
            binding: "omitempty,dive,oneof=1 2 3"
            validate: "omitempty,dive,oneof=1 2 3"
        - name: startTime
          in: query
          required: false
          description: 评价开始时间
          schema:
            type: string
            format: date-time
          x-oapi-codegen-extra-tags:
            binding: "omitempty"
            validate: "omitempty"
        - name: endTime
          in: query
          required: false
          description: 评价结束时间
          schema:
            type: string
            format: date-time
          x-oapi-codegen-extra-tags:
            binding: "omitempty"
            validate: "omitempty"
        - name: storeName
          in: query
          required: false
          description: 门店名称
          schema:
            type: string
          x-oapi-codegen-extra-tags:
            binding: "omitempty"
            validate: "omitempty"
        - name: actualLeaseStartTime
          in: query
          required: false
          description: 实际租赁开始时间
          schema:
            type: string
            format: date-time
          x-oapi-codegen-extra-tags:
            binding: "omitempty"
            validate: "omitempty"
        - name: actualLeaseEndTime
          in: query
          required: false
          description: 实际租赁结束时间
          schema:
            type: string
            format: date-time
          x-oapi-codegen-extra-tags:
            binding: "omitempty"
            validate: "omitempty"
        - name: leaseDaysCompare
          in: query
          required: false
          description: 租赁天数比较方式（gt=大于, eq=等于, lt=小于）
          schema:
            type: string
            enum: [gt, eq, lt]
          x-oapi-codegen-extra-tags:
            binding: "omitempty,oneof=gt eq lt"
            validate: "omitempty,oneof=gt eq lt"
        - name: leaseDays
          in: query
          required: false
          description: 租赁天数
          schema:
            type: integer
            minimum: 0
          x-oapi-codegen-extra-tags:
            binding: "omitempty,min=0"
            validate: "omitempty,min=0"
        - name: sort
          in: query
          required: false
          description: 排序字段
          schema:
            type: string
            default: createdAt
          x-oapi-codegen-extra-tags:
            binding: "omitempty,oneof=createdAt updatedAt"
            validate: "omitempty,oneof=createdAt updatedAt"
        - name: order
          in: query
          required: false
          description: 排序方向
          schema:
            type: string
            default: desc
          x-oapi-codegen-extra-tags:
            binding: "omitempty,oneof=asc desc"
            validate: "omitempty,oneof=asc desc"
        - name: isAdmin
          in: query
          required: false
          description: 是否为管理员查询
          schema:
            type: boolean
          x-oapi-codegen-extra-tags:
            binding: "omitempty"
            validate: "omitempty"
        - name: expand
          in: query
          required: false
          description: 展开项
          schema:
            type: array
            items:
              type: string
              enum: [user, product, reply]
          style: form
          explode: false
          x-oapi-codegen-extra-tags:
            binding: "omitempty,dive,oneof=user product reply"
            validate: "omitempty,dive,oneof=user product reply"
        - name: innerTradeNo
          in: query
          required: false
          description: 订单号(支持模糊查询)
          schema:
            type: string
          x-oapi-codegen-extra-tags:
            binding: "omitempty"
            validate: "omitempty"
      responses:
        '200':
          description: 成功返回
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommentListResponse'
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 服务器内部错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: CreateComment
      summary: 提交评论
      description: 提交新的评论
      tags:
        - comment
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommentCreateRequest'
      responses:
        '200':
          description: 成功返回
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommentResponse'
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 服务器内部错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  # 评论详情
  /comments/{id}:
    get:
      operationId: GetComment
      summary: 获取评论详情
      description: 获取评论详情，包含回复信息
      tags:
        - comment
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: 评论ID
          schema:
            type: integer
          x-oapi-codegen-extra-tags:
            binding: "required"
            validate: "required"
        - name: expand
          in: query
          required: false
          description: 展开项
          schema:
            type: array
            items:
              type: string
              enum: [user, product, reply]
          style: form
          explode: false
          x-oapi-codegen-extra-tags:
            binding: "omitempty,dive,oneof=user product reply"
            validate: "omitempty,dive,oneof=user product reply"
      responses:
        '200':
          description: 成功返回
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommentResponse'
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 评论不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 服务器内部错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      operationId: ReviewComment
      summary: 审核评论
      description: 审核评论
      tags:
        - comment
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: 评论ID
          schema:
            type: integer
          x-oapi-codegen-extra-tags:
            binding: "required"
            validate: "required"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommentReviewRequest'
      responses:
        '200':
          description: 成功返回
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommentResponse'
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 评论不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 服务器内部错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  # 评论回复
  /comments/{id}/reply:
    post:
      operationId: CreateReply
      summary: 回复评论
      description: 回复评论
      tags:
        - comment
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: 评论ID
          schema:
            type: integer
          x-oapi-codegen-extra-tags:
            binding: "required"
            validate: "required"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReplyCreateRequest'
      responses:
        '200':
          description: 成功返回
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommentResponse'
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 评论不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 服务器内部错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse' 