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

CurrentUser:
  get:
    operationId: getCurrentUser
    summary: 查询当前用户
    parameters:
      - $ref: '../components/parameters.yaml#/XRequestId'
    responses:
      '200':
        description: 当前用户摘要
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/UserResponse'
      '400':
        $ref: '../components/responses.yaml#/InvalidArgument'
      '401':
        $ref: '../components/responses.yaml#/AuthenticationError'
      '403':
        $ref: '../components/responses.yaml#/Forbidden'
      '500':
        $ref: '../components/responses.yaml#/InternalError'

CurrentUserUiTheme:
  put:
    operationId: updateCurrentUserUiTheme
    summary: 更新本人界面主题偏好（契约1.20）
    description: 账号级漫游偏好；仅本人可改，无需管理权限。纯视觉偏好，不校验rowVersion、不使Token失效、不写审计日志。
    parameters:
      - $ref: '../components/parameters.yaml#/XRequestId'
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '../components/schemas.yaml#/UpdateUiThemeRequest'
    responses:
      '200':
        description: 更新成功，返回最新用户摘要
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/UserResponse'
      '400':
        $ref: '../components/responses.yaml#/InvalidArgument'
      '401':
        $ref: '../components/responses.yaml#/AuthenticationError'
      '500':
        $ref: '../components/responses.yaml#/InternalError'

Users:
  get:
    operationId: listUsers
    summary: 分页查询人员
    description: 锚点管理员（管理范围非全局）不传organizationId时静默收敛到管理范围子树；显式请求的organizationId（含后代展开）与管理范围无交集时返回403 FORBIDDEN（"无权限查看该机构的用户"）。
    parameters:
      - $ref: '../components/parameters.yaml#/XRequestId'
      - name: organizationId
        in: query
        schema:
          $ref: '../components/schemas.yaml#/StringId'
      - name: includeDescendants
        in: query
        schema:
          type: boolean
          default: false
      - 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#/UserPageResponse'
      '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: createUser
    summary: 创建用户
    description: 防提权（契约1.30⑥）——仅当目标roleCode=ADMIN且其生效角色具备机构/用户编辑位（manageOrgEdit/manageUserEdit任一）时校验，目标最终生效管理范围（按「角色锚点优先，角色SELF回落用户级三态」解析）不得超出操作者管理范围，解析为全局或范围外机构返回403 FORBIDDEN（"目标超出管理范围"）；无管理位角色（含默认角色）与USER类别目标不受限，内置admin作为操作者恒全局不受限。
    parameters:
      - $ref: '../components/parameters.yaml#/XRequestId'
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '../components/schemas.yaml#/CreateUserRequest'
    responses:
      '201':
        description: 创建成功
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/UserResponse'
      '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'

UsersReorder:
  put:
    operationId: reorderUsers
    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'

User:
  parameters:
    - name: id
      in: path
      required: true
      schema:
        $ref: '../components/schemas.yaml#/StringId'
  put:
    operationId: updateUser
    summary: 编辑用户
    description: 当securityLevel/roleCode/roleId/status实际变化时强制二次认证（X-DMS-Reauth-Token，缺失或无效返回403 REAUTH_REQUIRED）；纯改名等不触发。防提权（契约1.30⑥）——目标ADMIN生效管理范围超出操作者时返回403 FORBIDDEN（"目标超出管理范围"），未提交managedOrgId时按保持原值判定，该校验先于二次认证执行（换角色场景先报越权而非REAUTH_REQUIRED）。
    parameters:
      - $ref: '../components/parameters.yaml#/XDmsReauthToken'
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '../components/schemas.yaml#/UpdateUserRequest'
    responses:
      '200':
        description: 编辑成功
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/UserResponse'
      '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: deleteUser
    summary: 逻辑删除用户
    parameters:
      - name: rowVersion
        in: query
        required: true
        schema: {type: integer, minimum: 0}
    responses:
      '200':
        description: 删除成功
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/DeleteUserResponse'
      '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'

UserResetPassword:
  parameters:
    - name: id
      in: path
      required: true
      schema:
        $ref: '../components/schemas.yaml#/StringId'
  post:
    operationId: resetUserPassword
    summary: 重置用户密码
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '../components/schemas.yaml#/ResetUserPasswordRequest'
    responses:
      '200':
        description: 重置成功
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/ResetPasswordResponse'
      '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'