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

OrganizationTree:
  get:
    operationId: getOrganizationTree
    summary: 查询组织树
    description: 响应按请求者生效管理范围裁剪（契约1.33）——锚点管理员仅返回管理范围子树内机构（森林形式，根从锚点机构起，范围外机构与其祖先链不出现，keyword/status 过滤在裁剪后的集合内进行）；全局管理员不受限，返回全部机构。只读放开（契约1.45）：不要求ADMIN类别，任意登录用户可调；普通用户（USER）恒返回本人所在部门为根的子树（沿ENABLED机构边，无部门空树），与GET /api/v1/users收敛口径一致。
    parameters:
      - $ref: '../components/parameters.yaml#/XRequestId'
      - name: keyword
        in: query
        schema:
          type: string
      - name: status
        in: query
        description: 按状态过滤；不传时返回全部机构（含停用，契约1.29），停用节点仍保留其祖先链以便展示树形层级。
        schema:
          $ref: '../components/schemas.yaml#/EnabledStatus'
    responses:
      '200':
        description: 组织树
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/OrganizationTreeResponse'
      '400':
        $ref: '../components/responses.yaml#/InvalidArgument'
      '401':
        $ref: '../components/responses.yaml#/AuthenticationError'
      '403':
        $ref: '../components/responses.yaml#/Forbidden'
      '500':
        $ref: '../components/responses.yaml#/InternalError'

Organizations:
  post:
    operationId: createOrganization
    summary: 创建机构
    parameters:
      - $ref: '../components/parameters.yaml#/XRequestId'
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '../components/schemas.yaml#/CreateOrganizationRequest'
    responses:
      '201':
        description: 创建成功
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/OrganizationResponse'
      '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'

OrganizationsReorder:
  put:
    operationId: reorderOrganizations
    summary: 管理员拖动重排同级机构（契约1.27）
    description: parentId为null表示顶层机构排序，否则为该父机构直接子级排序；orderedIds为拖动后的目标顺序，被提交机构按原槽位次序互换（未提交机构相对次序不变），同级按步长10重编号sort_no。
    parameters:
      - $ref: '../components/parameters.yaml#/XRequestId'
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '../components/schemas.yaml#/ReorderOrganizationsRequest'
    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'

Organization:
  parameters:
    - name: id
      in: path
      required: true
      schema:
        $ref: '../components/schemas.yaml#/StringId'
  put:
    operationId: updateOrganization
    summary: 编辑机构
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '../components/schemas.yaml#/UpdateOrganizationRequest'
    responses:
      '200':
        description: 编辑成功
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/OrganizationResponse'
      '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: deleteOrganization
    summary: 逻辑删除机构
    parameters:
      - name: rowVersion
        in: query
        required: true
        schema: {type: integer, minimum: 0}
    responses:
      '200':
        description: 删除成功
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/DeleteOrganizationResponse'
      '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'

OrganizationIpAssignments:
  parameters:
    - name: id
      in: path
      required: true
      schema:
        $ref: '../components/schemas.yaml#/StringId'
  get:
    operationId: listOrganizationIpAssignments
    summary: 查询部门可登录IP条目ID列表（空列表表示不限制）
    parameters:
      - $ref: '../components/parameters.yaml#/XRequestId'
    responses:
      '200':
        description: IP条目ID列表
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/OrgIpAssignmentListResponse'
      '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: updateOrganizationIpAssignments
    summary: 整存部门可登录IP列表（空数组=清空=不限制）
    parameters:
      - $ref: '../components/parameters.yaml#/XRequestId'
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '../components/schemas.yaml#/UpdateOrgIpAssignmentsRequest'
    responses:
      '200':
        description: 保存成功
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/OrgIpAssignmentsResponse'
      '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'

# 契约1.55 高级检索·提供单位选项：机构树第 N 级启用机构清单
# （N=DMS_SEARCH_ORG_FILTER_LEVEL 缺省 2），不做契约1.45的部门子树裁剪。
# 契约1.66 响应新增 childOrganizations（第 N+1 级启用机构），下拉分两行选择。

OrganizationFilterOptions:
  get:
    operationId: getOrganizationFilterOptions
    summary: 高级检索·提供单位机构选项（契约1.55，1.66 两行）
    description: 返回机构树第 orgFilterLevel 级启用机构清单及第 N+1 级子机构清单（均按 sort_no 升序、null 最后、同值按 id），供全局检索「提供单位」下拉分两行选择（契约1.66：第一行 N 级机构、第二行 N+1 级机构）；任意登录用户可调。级别由 DMS_SEARCH_ORG_FILTER_LEVEL 配置（缺省2：二级机构）。不做契约1.45的部门子树裁剪——检索维度面向全机构，选中后由列表接口按该机构及其下级子树过滤。
    security:
      - BearerAuth: []
    parameters:
      - $ref: '../components/parameters.yaml#/XRequestId'
    responses:
      '200':
        description: 提供单位机构选项
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [orgFilterLevel, organizations, childOrganizations]
              properties:
                orgFilterLevel: {type: integer, description: 提供单位下拉第一行展示的机构级别（1=一级机构，2=二级机构）}
                organizations:
                  type: array
                  description: 第一行：第 N 级启用机构（契约1.55）
                  items:
                    type: object
                    additionalProperties: false
                    required: [id, orgName]
                    properties:
                      id: {type: string}
                      orgName: {type: string}
                childOrganizations:
                  type: array
                  description: 第二行：第 N+1 级启用机构（契约1.66 提供单位两行筛选）
                  items:
                    type: object
                    additionalProperties: false
                    required: [id, orgName]
                    properties:
                      id: {type: string}
                      orgName: {type: string}
      '401': {$ref: '../components/responses.yaml#/AuthenticationError'}
      '500': {$ref: '../components/responses.yaml#/InternalError'}