openapi: 3.0.0
info:
  title: 用户管理模块API
  version: 1.0.0
  description: 用户与团队管理的最小契约（骨架）

paths:
  /api/v1/users/me:
    get:
      summary: 获取当前用户信息
      tags: [用户]
      security:
        - bearerAuth: []
      responses:
        200:
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseUser'
        401:
          description: 未授权

  /api/v1/users:
    get:
      summary: 用户列表
      tags: [用户]
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: page
          schema: { type: integer, minimum: 1, default: 1 }
        - in: query
          name: size
          schema: { type: integer, minimum: 1, maximum: 100, default: 10 }
        - in: query
          name: role
          schema: { type: string }
        - in: query
          name: is_active
          schema: { type: boolean }
      responses:
        200:
          description: 成功
        403:
          description: 权限不足

    post:
      summary: 创建用户（管理员）
      tags: [用户]
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCreate'
      responses:
        201:
          description: 已创建
        409:
          description: 用户名或邮箱冲突

  /api/v1/users/{id}:
    get:
      summary: 获取指定用户
      tags: [用户]
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: integer }
      responses:
        200:
          description: 成功
        404:
          description: 未找到

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    ResponseUser:
      type: object
      properties:
        code:
          type: integer
          example: 200
        message:
          type: string
          example: success
        data:
          $ref: '#/components/schemas/User'

    User:
      type: object
      properties:
        id: { type: integer }
        username: { type: string }
        email: { type: string }
        role: { type: string }
        is_active: { type: boolean }

    UserCreate:
      type: object
      required: [username, email, password]
      properties:
        username: { type: string, minLength: 3, maxLength: 20 }
        email: { type: string, format: email }
        password: { type: string, minLength: 8 }
        role:
          type: string
          enum: [trainee, manager, admin]