document-management/backend/openapi/paths/roles.yaml

Roles:
  get:
    operationId: listRoles
    summary: 分页查询角色
    parameters:
      - $ref: '../components/parameters.yaml#/XRequestId'
      - name: keyword
        in: query
        schema:
          type: string
      - name: status
        in: query
        schema:
          $ref: '../components/schemas.yaml#/EnabledStatus'
      - name: page
        in: query
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: pageSize
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
    responses:
      '200':
        description: 角色分页结果
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/RolePageResponse'
      '400':
        $ref: '../components/responses.yaml#/InvalidArgument'
      '401':
        $ref: '../components/responses.yaml#/AuthenticationError'
      '403':
        $ref: '../components/responses.yaml#/Forbidden'
      '500':
        $ref: '../components/responses.yaml#/InternalError'
  post:
    operationId: createRole
    summary: 创建角色（同时初始化10行权限矩阵）
    parameters:
      - $ref: '../components/parameters.yaml#/XRequestId'
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '../components/schemas.yaml#/CreateRoleRequest'
    responses:
      '201':
        description: 创建成功
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/RoleResponse'
      '400':
        $ref: '../components/responses.yaml#/InvalidArgument'
      '401':
        $ref: '../components/responses.yaml#/AuthenticationError'
      '403':
        $ref: '../components/responses.yaml#/Forbidden'
      '409':
        $ref: '../components/responses.yaml#/Conflict'
      '500':
        $ref: '../components/responses.yaml#/InternalError'

RolesReorder:
  put:
    operationId: reorderRoles
    summary: 管理员拖动重排角色列表（契约1.27）
    description: orderedIds为拖动后的目标顺序，被提交角色按原槽位次序互换（未提交角色相对次序不变），全体角色按步长10重编号sort_no。
    parameters:
      - $ref: '../components/parameters.yaml#/XRequestId'
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '../components/schemas.yaml#/ReorderByIdsRequest'
    responses:
      '200':
        description: 重排结果
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/ReorderResultResponse'
      '400':
        $ref: '../components/responses.yaml#/InvalidArgument'
      '401':
        $ref: '../components/responses.yaml#/AuthenticationError'
      '403':
        $ref: '../components/responses.yaml#/Forbidden'
      '404':
        $ref: '../components/responses.yaml#/NotFound'
      '409':
        $ref: '../components/responses.yaml#/Conflict'
      '500':
        $ref: '../components/responses.yaml#/InternalError'

Role:
  parameters:
    - name: id
      in: path
      required: true
      schema:
        $ref: '../components/schemas.yaml#/StringId'
  put:
    operationId: updateRole
    summary: 编辑角色（含默认角色切换）
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '../components/schemas.yaml#/UpdateRoleRequest'
    responses:
      '200':
        description: 编辑成功
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/RoleResponse'
      '400':
        $ref: '../components/responses.yaml#/InvalidArgument'
      '401':
        $ref: '../components/responses.yaml#/AuthenticationError'
      '403':
        $ref: '../components/responses.yaml#/Forbidden'
      '404':
        $ref: '../components/responses.yaml#/NotFound'
      '409':
        $ref: '../components/responses.yaml#/Conflict'
      '500':
        $ref: '../components/responses.yaml#/InternalError'
  delete:
    operationId: deleteRole
    summary: 逻辑删除角色（有关联用户时拒绝）
    parameters:
      - name: rowVersion
        in: query
        required: true
        schema: {type: integer, minimum: 0}
    responses:
      '200':
        description: 删除成功
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/DeleteRoleResponse'
      '400':
        $ref: '../components/responses.yaml#/InvalidArgument'
      '401':
        $ref: '../components/responses.yaml#/AuthenticationError'
      '403':
        $ref: '../components/responses.yaml#/Forbidden'
      '404':
        $ref: '../components/responses.yaml#/NotFound'
      '409':
        $ref: '../components/responses.yaml#/Conflict'
      '500':
        $ref: '../components/responses.yaml#/InternalError'

RolePermissions:
  parameters:
    - name: id
      in: path
      required: true
      schema:
        $ref: '../components/schemas.yaml#/StringId'
  get:
    operationId: listRolePermissions
    summary: 查询角色权限矩阵（10行）
    parameters:
      - $ref: '../components/parameters.yaml#/XRequestId'
    responses:
      '200':
        description: 权限矩阵
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/RoleMatrixListResponse'
      '401':
        $ref: '../components/responses.yaml#/AuthenticationError'
      '403':
        $ref: '../components/responses.yaml#/Forbidden'
      '404':
        $ref: '../components/responses.yaml#/NotFound'
      '500':
        $ref: '../components/responses.yaml#/InternalError'
  put:
    operationId: updateRolePermissions
    summary: 权限矩阵整存整取
    description: 敏感操作，强制二次认证（X-DMS-Reauth-Token，缺失或无效返回403 REAUTH_REQUIRED）。
    parameters:
      - $ref: '../components/parameters.yaml#/XRequestId'
      - $ref: '../components/parameters.yaml#/XDmsReauthToken'
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '../components/schemas.yaml#/UpdateRolePermissionsRequest'
    responses:
      '200':
        description: 保存成功
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/RolePermissionsResponse'
      '400':
        $ref: '../components/responses.yaml#/InvalidArgument'
      '401':
        $ref: '../components/responses.yaml#/AuthenticationError'
      '403':
        $ref: '../components/responses.yaml#/Forbidden'
      '404':
        $ref: '../components/responses.yaml#/NotFound'
      '409':
        $ref: '../components/responses.yaml#/Conflict'
      '500':
        $ref: '../components/responses.yaml#/InternalError'

RoleUsers:
  parameters:
    - name: id
      in: path
      required: true
      schema:
        $ref: '../components/schemas.yaml#/StringId'
  get:
    operationId: listRoleUsers
    summary: 查询角色关联用户ID列表
    parameters:
      - $ref: '../components/parameters.yaml#/XRequestId'
    responses:
      '200':
        description: 用户ID列表
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/RoleUsersResponse'
      '401':
        $ref: '../components/responses.yaml#/AuthenticationError'
      '403':
        $ref: '../components/responses.yaml#/Forbidden'
      '404':
        $ref: '../components/responses.yaml#/NotFound'
      '500':
        $ref: '../components/responses.yaml#/InternalError'
  put:
    operationId: updateRoleUsers
    summary: 整存角色关联用户集合（仅普通用户）
    parameters:
      - $ref: '../components/parameters.yaml#/XRequestId'
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '../components/schemas.yaml#/UpdateRoleUsersRequest'
    responses:
      '200':
        description: 保存成功
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/RoleUsersResponse'
      '400':
        $ref: '../components/responses.yaml#/InvalidArgument'
      '401':
        $ref: '../components/responses.yaml#/AuthenticationError'
      '403':
        $ref: '../components/responses.yaml#/Forbidden'
      '404':
        $ref: '../components/responses.yaml#/NotFound'
      '409':
        $ref: '../components/responses.yaml#/Conflict'
      '500':
        $ref: '../components/responses.yaml#/InternalError'