document-management/backend/openapi/components/schemas.yaml

StringId:
  type: string
  pattern: '^[0-9]+$'
  description: 数据库BIGINT在JSON中的安全十进制字符串表达。

UtcDateTime:
  type: string
  format: date-time
  pattern: 'Z$'
  example: '2026-07-23T03:00:00.000Z'

RoleCode:
  type: string
  enum: [USER, ADMIN]

AllowedModule:
  type: string
  enum: [DOCUMENT_BROWSER, BACKEND_MANAGEMENT, AUDIT_LOG, ORGANIZATION_USER_MANAGEMENT]

DocumentType:
  type: string
  enum: [MAIN, SUB_PLAN, ATTACHMENT]

DocumentStatus:
  type: string
  enum: [DRAFT, PUBLISHED, ARCHIVED]

SecurityLevel:
  type: string
  enum: [PUBLIC, INTERNAL, SECRET, CONFIDENTIAL, TOP_SECRET]
  x-comparison-values:
    PUBLIC: 10
    INTERNAL: 20
    SECRET: 30
    CONFIDENTIAL: 40
    TOP_SECRET: 50

AttachmentType:
  type: string
  enum: [SUPPORT_ACHIEVEMENT, TRAINING_MATERIAL, TYPICAL_CASE]

AllowedAction:
  type: string
  enum:
    - VIEW
    - DOWNLOAD
    - EDIT
    - CONFIG_PERMISSION
    - DELETE
    - BIND_ATTACHMENT
    - UNBIND_ATTACHMENT

CategoryType:
  type: string
  enum: [SCENE, STYLE, SITUATION, VERSION, OTHER]

EnabledStatus:
  type: string
  enum: [ENABLED, DISABLED]

AuditResult:
  type: string
  enum: [SUCCESS, FAILURE]

AuditAction:
  type: string
  enum:
    - LOGIN
    - LOGOUT
    - VIEW_DOCUMENT
    - DOWNLOAD_DOCUMENT
    - UPLOAD_DOCUMENT
    - BATCH_IMPORT
    - EDIT_DOCUMENT
    - DELETE_DOCUMENT
    - CREATE_CATEGORY
    - EDIT_CATEGORY
    - DELETE_CATEGORY
    - CHANGE_PERMISSION
    - UPLOAD_PERMISSION_VOUCHER
    - DELETE_PERMISSION_VOUCHER
    - MOVE_DOCUMENT
    - MOVE_ATTACHMENT
    - BIND_ATTACHMENT
    - UNBIND_ATTACHMENT
    - RESTORE_DOCUMENT
    - CREATE_ORGANIZATION
    - EDIT_ORGANIZATION
    - DELETE_ORGANIZATION
    - CREATE_USER
    - EDIT_USER
    - DELETE_USER
    - RESET_USER_PASSWORD
    - DOCUMENT_PASSWORD_SET
    - DOCUMENT_PASSWORD_REMOVE
    - CREATE_IP_ENTRY
    - EDIT_IP_ENTRY
    - DELETE_IP_ENTRY
    - ASSIGN_ORG_IP

AuditTarget:
  type: string
  enum:
    - AUTH
    - CATEGORY
    - DOCUMENT
    - ATTACHMENT
    - PERMISSION
    - ATTACHMENT_BINDING
    - ORGANIZATION
    - USER
    - IP_ENTRY

PageResult:
  type: object
  required: [items, page, pageSize, total, totalPages]
  properties:
    items:
      type: array
      items: {}
    page:
      type: integer
      minimum: 1
      default: 1
    pageSize:
      type: integer
      minimum: 1
      maximum: 100
      default: 20
    total:
      type: integer
      minimum: 0
    totalPages:
      type: integer
      minimum: 0

HealthData:
  type: object
  additionalProperties: false
  required: [service, status]
  properties:
    service:
      type: string
      enum: [dms]
    status:
      type: string
      enum: [UP]

HealthResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code:
      type: string
      enum: [OK]
    message:
      type: string
      enum: [success]
    data:
      $ref: '#/HealthData'
    requestId:
      type: string
      format: uuid

ErrorResponse:
  type: object
  additionalProperties: false
  required: [code, message, details, requestId]
  properties:
    code:
      type: string
      enum:
        - INVALID_ARGUMENT
        - INVALID_CREDENTIALS
        - TOKEN_INVALID
        - TOKEN_EXPIRED
        - USER_DISABLED
        - AUTH_VERSION_MISMATCH
        - FORBIDDEN
        - SECURITY_LEVEL_FORBIDDEN
        - DOCUMENT_VIEW_FORBIDDEN
        - DOCUMENT_DOWNLOAD_FORBIDDEN
        - RESOURCE_NOT_FOUND
        - FILE_NOT_FOUND
        - UNSUPPORTED_FILE_TYPE
        - PREVIEW_UNAVAILABLE
        - PAYLOAD_TOO_LARGE
        - BATCH_MANIFEST_MISMATCH
        - DATA_VERSION_CONFLICT
        - DOCUMENT_NAME_CONFLICT
        - CATEGORY_IN_USE
        - CATEGORY_NOT_LEAF
        - MAIN_PLAN_HAS_CHILDREN
        - ATTACHMENT_IN_USE
        - ATTACHMENT_HAS_NO_ACL
        - SUB_PLAN_PERMISSION_INHERITED
        - DUPLICATE_PERMISSION_SUBJECT
        - MAIN_PLAN_NOT_FOUND
        - INTERNAL_ERROR
        - DOCUMENT_NOT_DELETED
        - FILE_INTEGRITY_MISMATCH
        - FILE_PATH_INVALID
        - RESTORE_FILE_CHANGED
        - RESTORE_CATEGORY_INVALID
        - RESTORE_PARENT_INVALID
        - RESTORE_RELATION_CONFLICT
        - DOCUMENT_NOT_IN_MOVE_SCOPE
        - ORGANIZATION_IN_USE
        - USER_SELF_PROTECTION
        - CATEGORY_FLAT_MODE_CONFLICT
        - PREVIEW_CONVERTER_UNAVAILABLE
        - PREVIEW_CONVERSION_TIMEOUT
        - PREVIEW_CONVERSION_FAILED
    message:
      type: string
    details:
      type: object
      nullable: true
      additionalProperties: true
    requestId:
      type: string
      format: uuid

UserSummary:
  type: object
  additionalProperties: false
  required:
    - id
    - username
    - realName
    - organizationId
    - organizationName
    - roleCode
    - roleId
    - roleName
    - securityLevel
    - status
    - allowedModules
    - authVersion
    - rowVersion
    - lastLoginAt
    - lastLoginIp
    - uiTheme
    - permCategoryEdit
    - permOrgEdit
    - permUserEdit
    - managedOrgId
  properties:
    id:
      $ref: '#/StringId'
    username:
      type: string
    realName:
      type: string
    organizationId:
      allOf:
        - $ref: '#/StringId'
      nullable: true
    organizationName:
      type: string
      nullable: true
    roleCode:
      $ref: '#/RoleCode'
    roleId:
      allOf:
        - $ref: '#/StringId'
      nullable: true
      description: 自定义角色ID；ADMIN恒为空。
    roleName:
      type: string
      nullable: true
      description: 自定义角色名称；角色被删除后为null。
    securityLevel:
      $ref: '#/SecurityLevel'
    status:
      $ref: '#/EnabledStatus'
    allowedModules:
      type: array
      uniqueItems: true
      items:
        $ref: '#/AllowedModule'
    authVersion:
      type: integer
      minimum: 0
    rowVersion:
      type: integer
      minimum: 0
    lastLoginAt:
      allOf:
        - $ref: '#/UtcDateTime'
      nullable: true
    lastLoginIp:
      type: string
      nullable: true
    uiTheme:
      type: string
      enum: [blue, red, green]
      description: 界面主题偏好（契约1.20，账号级漫游）；存量与缺省为blue。
    permCategoryEdit:
      type: boolean
      description: 分类编辑管理位；值取自生效角色（显式角色活跃且启用时优先，否则回退默认角色），内置admin恒为true。
    permOrgEdit:
      type: boolean
      description: 机构编辑管理位；值取自生效角色。
    permUserEdit:
      type: boolean
      description: 用户编辑管理位；值取自生效角色。
    managedOrgId:
      type: string
      nullable: true
      description: 管理范围锚点；值取自生效角色，为机构ID、"SELF"（跟随用户自身所在部门，落库哨兵0）或null（全局），内置admin恒为null。

LoginRequest:
  type: object
  additionalProperties: false
  required: [username, password, keepSignedIn]
  properties:
    username:
      type: string
      minLength: 1
    password:
      type: string
      format: password
      minLength: 1
      writeOnly: true
    keepSignedIn:
      type: boolean

LoginData:
  type: object
  additionalProperties: false
  required: [accessToken, tokenType, expiresIn, user]
  properties:
    accessToken:
      type: string
    tokenType:
      type: string
      enum: [Bearer]
    expiresIn:
      type: integer
      enum: [7200, 604800]
    user:
      $ref: '#/UserSummary'

LoginResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code:
      type: string
      enum: [OK]
    message:
      type: string
      enum: [success]
    data:
      $ref: '#/LoginData'
    requestId:
      type: string
      format: uuid

UserResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code:
      type: string
      enum: [OK]
    message:
      type: string
      enum: [success]
    data:
      $ref: '#/UserSummary'
    requestId:
      type: string
      format: uuid

OrganizationNode:
  type: object
  additionalProperties: false
  required: [id, parentId, orgCode, orgName, orgPath, sortNo, status, rowVersion, children]
  properties:
    id:
      $ref: '#/StringId'
    parentId:
      allOf:
        - $ref: '#/StringId'
      nullable: true
    orgCode:
      type: string
    orgName:
      type: string
    orgPath:
      type: string
    sortNo:
      type: integer
    status:
      $ref: '#/EnabledStatus'
    rowVersion:
      type: integer
      minimum: 0
    children:
      type: array
      items:
        $ref: '#/OrganizationNode'

OrganizationTreeResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code:
      type: string
      enum: [OK]
    message:
      type: string
      enum: [success]
    data:
      type: array
      items:
        $ref: '#/OrganizationNode'
    requestId:
      type: string
      format: uuid

UserPage:
  type: object
  additionalProperties: false
  required: [items, page, pageSize, total, totalPages]
  properties:
    items:
      type: array
      items:
        $ref: '#/UserSummary'
    page:
      type: integer
      minimum: 1
    pageSize:
      type: integer
      minimum: 1
      maximum: 100
    total:
      type: integer
      minimum: 0
    totalPages:
      type: integer
      minimum: 0

UserPageResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code:
      type: string
      enum: [OK]
    message:
      type: string
      enum: [success]
    data:
      $ref: '#/UserPage'
    requestId:
      type: string
      format: uuid

EmptySuccessResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code:
      type: string
      enum: [OK]
    message:
      type: string
      enum: [success]
    data:
      type: object
      additionalProperties: false
    requestId:
      type: string
      format: uuid

CategoryNode:
  type: object
  additionalProperties: false
  required:
    - id
    - categoryCode
    - categoryName
    - categoryType
    - parentId
    - categoryPath
    - sortNo
    - documentCount
    - rowVersion
    - children
  properties:
    id:
      $ref: '#/StringId'
    categoryCode:
      type: string
      maxLength: 64
    categoryName:
      type: string
      maxLength: 128
    categoryType:
      $ref: '#/CategoryType'
    parentId:
      allOf:
        - $ref: '#/StringId'
      nullable: true
    categoryPath:
      type: string
      maxLength: 1000
    sortNo:
      type: integer
    documentCount:
      type: integer
      minimum: 0
      description: 该分类完整有效子树内所有有效MAIN数量（不按当前用户密级/权限过滤，所有登录用户口径一致）。
    rowVersion:
      type: integer
      minimum: 0
    children:
      type: array
      items:
        $ref: '#/CategoryNode'

CreateCategoryRequest:
  type: object
  additionalProperties: false
  required: [categoryCode, categoryName, categoryType, parentId, sortNo]
  properties:
    categoryCode:
      type: string
      minLength: 1
      maxLength: 64
    categoryName:
      type: string
      minLength: 1
      maxLength: 128
    categoryType:
      $ref: '#/CategoryType'
    parentId:
      allOf:
        - $ref: '#/StringId'
      nullable: true
    sortNo:
      type: integer

UpdateCategoryRequest:
  type: object
  additionalProperties: false
  required: [categoryName, categoryType, parentId, sortNo, rowVersion]
  properties:
    categoryName:
      type: string
      minLength: 1
      maxLength: 128
    categoryType:
      $ref: '#/CategoryType'
    parentId:
      allOf:
        - $ref: '#/StringId'
      nullable: true
    sortNo:
      type: integer
    rowVersion:
      type: integer
      minimum: 0

CategoryTreeResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code:
      type: string
      enum: [OK]
    message:
      type: string
      enum: [success]
    data:
      type: array
      items:
        $ref: '#/CategoryNode'
    requestId:
      type: string
      format: uuid

CategoryResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code:
      type: string
      enum: [OK]
    message:
      type: string
      enum: [success]
    data:
      $ref: '#/CategoryNode'
    requestId:
      type: string
      format: uuid

DeleteCategoryData:
  type: object
  additionalProperties: false
  required: [id, deleted]
  properties:
    id:
      $ref: '#/StringId'
    deleted:
      type: boolean
      enum: [true]

DeleteCategoryResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code:
      type: string
      enum: [OK]
    message:
      type: string
      enum: [success]
    data:
      $ref: '#/DeleteCategoryData'
    requestId:
      type: string
      format: uuid

PermissionSummary:
  type: object
  additionalProperties: false
  required: [borrowerCount, inheritedFromMainPlan]
  properties:
    borrowerCount:
      type: integer
      minimum: 0
      description: 生效（canView且未到期）借阅人数
    inheritedFromMainPlan:
      type: boolean

DocumentSummary:
  type: object
  required:
    - id
    - documentName
    - summary
    - documentType
    - status
    - securityLevel
    - borrowSummary
    - categoryId
    - categoryName
    - categoryPath
    - parentDocumentId
    - rootDocumentId
    - attachmentType
    - fileExtension
    - tags
    - childCount
    - attachmentCount
    - viewCount
    - downloadCount
    - createdByName
    - createdAt
    - updatedAt
    - rowVersion
    - allowedActions
    - hasPassword
    - passwordProtectedActions
    - viewLocked
  properties:
    id:
      $ref: '#/StringId'
    documentName:
      type: string
    summary:
      type: string
      nullable: true
    description:
      type: string
      nullable: true
      description: 详细说明：管理员在"查看"对话框维护，供普通用户阅读；不参与全文检索。
    documentType:
      $ref: '#/DocumentType'
    status:
      $ref: '#/DocumentStatus'
    securityLevel:
      $ref: '#/SecurityLevel'
    borrowSummary:
      type: string
      description: 生效借阅人姓名以"、"连接；未配置时为"未配置"；无查看权限的列表行返回"-"
    categoryId:
      allOf:
        - $ref: '#/StringId'
      nullable: true
    categoryName:
      type: string
      nullable: true
    categoryPath:
      type: string
      nullable: true
    parentDocumentId:
      allOf:
        - $ref: '#/StringId'
      nullable: true
    rootDocumentId:
      allOf:
        - $ref: '#/StringId'
      nullable: true
    attachmentType:
      allOf:
        - $ref: '#/AttachmentType'
      nullable: true
    fileExtension:
      type: string
    tags:
      type: array
      items:
        type: string
    childCount:
      type: integer
      minimum: 0
    attachmentCount:
      type: integer
      minimum: 0
    viewCount:
      type: integer
      minimum: 0
    downloadCount:
      type: integer
      minimum: 0
    createdByName:
      type: string
      nullable: true
    createdAt:
      $ref: '#/UtcDateTime'
    updatedAt:
      $ref: '#/UtcDateTime'
    rowVersion:
      type: integer
      minimum: 0
    allowedActions:
      type: array
      uniqueItems: true
      items:
        $ref: '#/AllowedAction'
    hasPassword:
      type: boolean
      description: 主案是否设置密码锁；仅MAIN可设，其余类型恒false。
    passwordProtectedActions:
      type: array
      uniqueItems: true
      items:
        $ref: '#/DocumentPasswordAction'
      description: 密码锁勾选保护的操作码集合；未设密恒为空数组。
    viewLocked:
      type: boolean
      description: 当前用户查看该文档正文是否需要密码；viewLocked时contentSnippet不返回。
    mountedPlanCount:
      type: integer
      minimum: 0
      description: 仅共享附件响应返回。

DocumentDetail:
  allOf:
    - $ref: '#/DocumentSummary'
    - type: object
      required:
        - originalFileName
        - mimeType
        - fileSize
        - fileHash
        - permissionSummary
        - viewPasswordVerified
        - contentText
      properties:
        originalFileName:
          type: string
        mimeType:
          type: string
          nullable: true
        fileSize:
          type: integer
          minimum: 0
        fileHash:
          type: string
          pattern: '^[0-9a-fA-F]{64}$'
        permissionSummary:
          $ref: '#/PermissionSummary'
        viewPasswordVerified:
          type: boolean
          description: 查看是否已通过密码验证（未锁定恒true）。
        contentText:
          type: string
          nullable: true
          description: 提取的正文文本；viewLocked且请求头密码未验证通过时为null。
        contentExtractStatus:
          type: string
          enum: [SUCCESS, EMPTY, UNSUPPORTED, FAILED]
          description: 正文提取状态。仅管理员详情响应返回。
        contentExtractError:
          type: string
          nullable: true
          description: 提取失败的脱敏原因（异常类型+首行信息，不含绝对路径）。仅管理员详情响应返回；非FAILED时为null。
        contentExtractedAt:
          type: string
          format: date-time
          nullable: true
          description: 最近一次正文提取时间（UTC）。仅管理员详情响应返回。

AttachmentBindingSummary:
  allOf:
    - $ref: '#/DocumentSummary'
    - type: object
      required: [bindingId, bindingSortNo, mountedPlanCount]
      properties:
        bindingId:
          $ref: '#/StringId'
        bindingSortNo:
          type: integer
        mountedPlanCount:
          type: integer
          minimum: 0

DocumentPage:
  type: object
  additionalProperties: false
  required: [items, page, pageSize, total, totalPages]
  properties:
    items:
      type: array
      items:
        $ref: '#/DocumentSummary'
    page:
      type: integer
      minimum: 1
    pageSize:
      type: integer
      minimum: 1
      maximum: 100
    total:
      type: integer
      minimum: 0
    totalPages:
      type: integer
      minimum: 0

AttachmentBindingPage:
  type: object
  additionalProperties: false
  required: [items, page, pageSize, total, totalPages]
  properties:
    items:
      type: array
      items:
        $ref: '#/AttachmentBindingSummary'
    page:
      type: integer
      minimum: 1
    pageSize:
      type: integer
      minimum: 1
      maximum: 100
    total:
      type: integer
      minimum: 0
    totalPages:
      type: integer
      minimum: 0

MainPlanBrief:
  type: object
  additionalProperties: false
  required: [id, documentName, categoryName, securityLevel]
  properties:
    id:
      $ref: '#/StringId'
    documentName:
      type: string
    categoryName:
      type: string
      nullable: true
    securityLevel:
      $ref: '#/SecurityLevel'

MainPlanBriefCollection:
  type: object
  additionalProperties: false
  required: [items, total]
  properties:
    items:
      type: array
      items:
        $ref: '#/MainPlanBrief'
    total:
      type: integer
      minimum: 0

DocumentPageResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code:
      type: string
      enum: [OK]
    message:
      type: string
      enum: [success]
    data:
      $ref: '#/DocumentPage'
    requestId:
      type: string
      format: uuid

DocumentDetailResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code:
      type: string
      enum: [OK]
    message:
      type: string
      enum: [success]
    data:
      $ref: '#/DocumentDetail'
    requestId:
      type: string
      format: uuid

AttachmentBindingPageResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code:
      type: string
      enum: [OK]
    message:
      type: string
      enum: [success]
    data:
      $ref: '#/AttachmentBindingPage'
    requestId:
      type: string
      format: uuid

MainPlanBriefCollectionResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code:
      type: string
      enum: [OK]
    message:
      type: string
      enum: [success]
    data:
      $ref: '#/MainPlanBriefCollection'
    requestId:
      type: string
      format: uuid

MainDocumentCreateMetadata:
  type: object
  additionalProperties: false
  required: [documentName, documentType, summary, categoryId, securityLevel, tags]
  properties:
    documentName: {type: string, minLength: 1, maxLength: 255}
    documentType: {type: string, enum: [MAIN]}
    summary: {type: string, nullable: true}
    categoryId: {$ref: '#/StringId'}
    securityLevel: {$ref: '#/SecurityLevel'}
    overwriteDocumentId:
      allOf: [{$ref: '#/StringId'}]
      description: 仅在用户确认覆盖同名主案后提交，并必须与rowVersion同时出现。
    rowVersion:
      type: integer
      minimum: 0
      description: 被覆盖文档的当前版本；仅与overwriteDocumentId同时提交。
    tags:
      type: array
      maxItems: 50
      items: {type: string, minLength: 1, maxLength: 64}
    password:
      type: string
      minLength: 1
      maxLength: 128
      description: 可选；仅新增MAIN时允许，与protectedActions必须同时出现；覆盖上传（overwriteDocumentId）时禁止携带。
    protectedActions:
      type: array
      uniqueItems: true
      items: {$ref: '#/DocumentPasswordAction'}
      description: 可选；密码保护的操作码集合，与password必须同时出现。

SubPlanCreateMetadata:
  type: object
  additionalProperties: false
  required: [documentName, documentType, summary, parentDocumentId, securityLevel, tags]
  properties:
    documentName: {type: string, minLength: 1, maxLength: 255}
    documentType: {type: string, enum: [SUB_PLAN]}
    summary: {type: string, nullable: true}
    parentDocumentId: {$ref: '#/StringId'}
    securityLevel: {$ref: '#/SecurityLevel'}
    overwriteDocumentId:
      allOf: [{$ref: '#/StringId'}]
      description: 仅在用户确认覆盖同一主案下同名子案后提交，并必须与rowVersion同时出现。
    rowVersion:
      type: integer
      minimum: 0
      description: 被覆盖文档的当前版本；仅与overwriteDocumentId同时提交。
    tags:
      type: array
      maxItems: 50
      items: {type: string, minLength: 1, maxLength: 64}

DocumentCreateMetadata:
  oneOf:
    - $ref: '#/MainDocumentCreateMetadata'
    - $ref: '#/SubPlanCreateMetadata'
  discriminator:
    propertyName: documentType

AttachmentCreateMetadata:
  type: object
  additionalProperties: false
  required: [documentName, attachmentType, summary, tags]
  properties:
    documentName: {type: string, minLength: 1, maxLength: 255}
    attachmentType: {$ref: '#/AttachmentType'}
    summary: {type: string, nullable: true}
    tags:
      type: array
      maxItems: 50
      items: {type: string, minLength: 1, maxLength: 64}

MainDocumentUpdateRequest:
  type: object
  additionalProperties: false
  required: [documentName, summary, categoryId, securityLevel, tags, rowVersion]
  properties:
    documentName: {type: string, minLength: 1, maxLength: 255}
    summary: {type: string, nullable: true}
    categoryId: {$ref: '#/StringId'}
    securityLevel: {$ref: '#/SecurityLevel'}
    tags:
      type: array
      maxItems: 50
      items: {type: string, minLength: 1, maxLength: 64}
    rowVersion: {type: integer, minimum: 0}
    organizationId:
      allOf:
        - $ref: '#/StringId'
      description: 目标归属部门；缺省沿用现有归属，调整到其他部门仅ADMIN。

SubPlanUpdateRequest:
  type: object
  additionalProperties: false
  required: [documentName, summary, securityLevel, tags, rowVersion]
  properties:
    documentName: {type: string, minLength: 1, maxLength: 255}
    summary: {type: string, nullable: true}
    securityLevel: {$ref: '#/SecurityLevel'}
    tags:
      type: array
      maxItems: 50
      items: {type: string, minLength: 1, maxLength: 64}
    rowVersion: {type: integer, minimum: 0}
    organizationId:
      allOf:
        - $ref: '#/StringId'
      description: 目标归属部门；缺省沿用现有归属，调整到其他部门仅ADMIN。

UpdateDocumentRequest:
  oneOf:
    - $ref: '#/MainDocumentUpdateRequest'
    - $ref: '#/SubPlanUpdateRequest'

UpdateDocumentDescriptionRequest:
  type: object
  additionalProperties: false
  required: [description]
  properties:
    description: {type: string, nullable: true, maxLength: 20000}

DocumentPasswordAction:
  type: string
  description: 主案密码锁可保护的操作码（与权限矩阵7操作对齐）。
  enum:
    - VIEW
    - DOWNLOAD
    - EDIT
    - DELETE
    - CONFIG_PERMISSION
    - BIND_ATTACHMENT
    - UNBIND_ATTACHMENT

UpdateDocumentPasswordRequest:
  type: object
  additionalProperties: false
  required: [rowVersion]
  properties:
    rowVersion: {type: integer, minimum: 0, description: 主案当前版本，乐观锁。}
    oldPassword:
      type: string
      maxLength: 128
      description: 已设密时修改/清除必须提供且正确；未设密时禁止提供。
    password:
      type: string
      minLength: 1
      maxLength: 128
      description: 新密码；缺省或空表示清除密码锁，此时不得携带protectedActions。
    protectedActions:
      type: array
      uniqueItems: true
      items: {$ref: '#/DocumentPasswordAction'}
      description: 设置/修改密码时的保护操作集合；与password必须同时出现。

DocumentPasswordSummary:
  type: object
  additionalProperties: false
  required: [id, hasPassword, protectedActions, rowVersion]
  properties:
    id: {$ref: '#/StringId'}
    hasPassword: {type: boolean}
    protectedActions:
      type: array
      uniqueItems: true
      items: {$ref: '#/DocumentPasswordAction'}
    rowVersion: {type: integer, minimum: 0}

DocumentPasswordResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code:
      type: string
      enum: [OK]
    message:
      type: string
      enum: [success]
    data:
      $ref: '#/DocumentPasswordSummary'
    requestId:
      type: string
      format: uuid

UpdateAttachmentRequest:
  type: object
  additionalProperties: false
  required: [documentName, attachmentType, summary, tags, rowVersion]
  properties:
    documentName: {type: string, minLength: 1, maxLength: 255}
    attachmentType: {$ref: '#/AttachmentType'}
    summary: {type: string, nullable: true}
    tags:
      type: array
      maxItems: 50
      items: {type: string, minLength: 1, maxLength: 64}
    rowVersion: {type: integer, minimum: 0}
    organizationId:
      allOf:
        - $ref: '#/StringId'
      description: 目标归属部门；缺省沿用现有归属，调整到其他部门仅ADMIN。

DeleteDocumentData:
  type: object
  additionalProperties: false
  required: [id, deleted]
  properties:
    id: {$ref: '#/StringId'}
    deleted: {type: boolean, enum: [true]}

DeleteDocumentResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code: {type: string, enum: [OK]}
    message: {type: string, enum: [success]}
    data: {$ref: '#/DeleteDocumentData'}
    requestId: {type: string, format: uuid}

BatchImportMultipart:
  type: object
  additionalProperties: false
  required: [files, items]
  properties:
    files:
      type: array
      minItems: 1
      items: {type: string, format: binary}
      description: 重复files字段，顺序与items数组严格对应。
    items:
      type: string
      description: 文档或附件metadata对象数组的JSON字符串。

BatchImportItem:
  type: object
  additionalProperties: false
  required: [index, originalFileName, success]
  properties:
    index: {type: integer, minimum: 0}
    originalFileName: {type: string}
    success: {type: boolean}
    document: {$ref: '#/DocumentDetail'}
    errorCode: {type: string}
    errorMessage: {type: string}

BatchImportData:
  type: object
  additionalProperties: false
  required: [total, successCount, failureCount, items]
  properties:
    total: {type: integer, minimum: 0}
    successCount: {type: integer, minimum: 0}
    failureCount: {type: integer, minimum: 0}
    items:
      type: array
      items: {$ref: '#/BatchImportItem'}

BatchImportResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code: {type: string, enum: [OK]}
    message: {type: string, enum: [success]}
    data: {$ref: '#/BatchImportData'}
    requestId: {type: string, format: uuid}

BindAttachmentsRequest:
  type: object
  additionalProperties: false
  required: [attachmentIds, mainPlanRowVersion]
  properties:
    attachmentIds:
      type: array
      minItems: 1
      items: {$ref: '#/StringId'}
    mainPlanRowVersion:
      type: integer
      minimum: 0

BindAttachmentsData:
  type: object
  additionalProperties: false
  required: [createdCount, existingCount, attachmentCount, mainPlanRowVersion]
  properties:
    createdCount: {type: integer, minimum: 0}
    existingCount: {type: integer, minimum: 0}
    attachmentCount: {type: integer, minimum: 0}
    mainPlanRowVersion: {type: integer, minimum: 0}

BindAttachmentsResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code: {type: string, enum: [OK]}
    message: {type: string, enum: [success]}
    data: {$ref: '#/BindAttachmentsData'}
    requestId: {type: string, format: uuid}

UnbindAttachmentData:
  type: object
  additionalProperties: false
  required: [attachmentCount, mainPlanRowVersion]
  properties:
    attachmentCount: {type: integer, minimum: 0}
    mainPlanRowVersion: {type: integer, minimum: 0}

UnbindAttachmentResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code: {type: string, enum: [OK]}
    message: {type: string, enum: [success]}
    data: {$ref: '#/UnbindAttachmentData'}
    requestId: {type: string, format: uuid}

ReorderDocumentsRequest:
  type: object
  additionalProperties: false
  required: [orderedIds]
  properties:
    orderedIds:
      type: array
      minItems: 2
      items: {$ref: '#/StringId'}

ReorderDocumentsData:
  type: object
  additionalProperties: false
  required: [reorderedCount]
  properties:
    reorderedCount: {type: integer, minimum: 0}

ReorderDocumentsResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code: {type: string, enum: [OK]}
    message: {type: string, enum: [success]}
    data: {$ref: '#/ReorderDocumentsData'}
    requestId: {type: string, format: uuid}

ReorderAttachmentsRequest:
  type: object
  additionalProperties: false
  required: [orderedBindingIds, mainPlanRowVersion]
  properties:
    orderedBindingIds:
      type: array
      minItems: 2
      items: {$ref: '#/StringId'}
    mainPlanRowVersion:
      type: integer
      minimum: 0

ReorderAttachmentsData:
  type: object
  additionalProperties: false
  required: [reorderedCount, mainPlanRowVersion]
  properties:
    reorderedCount: {type: integer, minimum: 0}
    mainPlanRowVersion: {type: integer, minimum: 0}

ReorderAttachmentsResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code: {type: string, enum: [OK]}
    message: {type: string, enum: [success]}
    data: {$ref: '#/ReorderAttachmentsData'}
    requestId: {type: string, format: uuid}

ReorderCategoriesRequest:
  type: object
  additionalProperties: false
  required: [parentId, orderedIds]
  properties:
    parentId:
      oneOf:
        - $ref: '#/StringId'
        - type: 'null'
    orderedIds:
      type: array
      minItems: 2
      items: {$ref: '#/StringId'}

ReorderCategoriesData:
  type: object
  additionalProperties: false
  required: [reorderedCount]
  properties:
    reorderedCount: {type: integer, minimum: 0}

ReorderCategoriesResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code: {type: string, enum: [OK]}
    message: {type: string, enum: [success]}
    data: {$ref: '#/ReorderCategoriesData'}
    requestId: {type: string, format: uuid}

PermissionEntry:
  type: object
  additionalProperties: false
  required:
    - id
    - subjectId
    - subjectName
    - canView
    - canDownload
    - expiresAt
    - voucherFileName
    - voucherFileSize
    - voucherUploadedAt
  properties:
    id: {$ref: '#/StringId'}
    subjectId: {$ref: '#/StringId'}
    subjectName: {type: string}
    canView: {type: boolean}
    canDownload: {type: boolean}
    expiresAt: {$ref: '#/UtcDateTime'}
    voucherFileName: {type: string, nullable: true}
    voucherFileSize: {type: integer, minimum: 1, nullable: true}
    voucherUploadedAt:
      allOf:
        - $ref: '#/UtcDateTime'
      nullable: true

SavePermissionEntry:
  type: object
  additionalProperties: false
  required:
    - subjectId
    - canView
    - canDownload
    - expiresAt
  properties:
    subjectId: {$ref: '#/StringId'}
    canView: {type: boolean}
    canDownload: {type: boolean}
    expiresAt: {$ref: '#/UtcDateTime'}

SavePermissionsRequest:
  type: object
  additionalProperties: false
  required: [documentRowVersion, entries]
  properties:
    documentRowVersion: {type: integer, minimum: 0}
    entries:
      type: array
      items: {$ref: '#/SavePermissionEntry'}
      description: 借阅授权全集（非增量补丁）；仅用户主体，expiresAt必须晚于当前时间且不超过当前时间+7天（服务端含60秒容差）；保存不触碰审批单凭证。

PermissionDetail:
  type: object
  additionalProperties: false
  required:
    - documentId
    - sourceDocumentId
    - inherited
    - documentRowVersion
    - entries
  properties:
    documentId: {$ref: '#/StringId'}
    sourceDocumentId: {$ref: '#/StringId'}
    inherited: {type: boolean}
    documentRowVersion: {type: integer, minimum: 0}
    entries:
      type: array
      items: {$ref: '#/PermissionEntry'}
      description: 按subjectId升序返回全部未删除授权（含已到期条目，由前端标记）。

PermissionVoucherResult:
  type: object
  additionalProperties: false
  required: [documentId, entryId, voucherFileName, voucherFileSize, voucherUploadedAt]
  properties:
    documentId: {$ref: '#/StringId'}
    entryId: {$ref: '#/StringId'}
    voucherFileName: {type: string}
    voucherFileSize: {type: integer, minimum: 1}
    voucherUploadedAt: {$ref: '#/UtcDateTime'}

PermissionVoucherResultResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code: {type: string, enum: [OK]}
    message: {type: string, enum: [success]}
    data: {$ref: '#/PermissionVoucherResult'}
    requestId: {type: string, format: uuid}

PermissionVoucherDeleteResult:
  type: object
  additionalProperties: false
  required: [documentId, entryId]
  properties:
    documentId: {$ref: '#/StringId'}
    entryId: {$ref: '#/StringId'}

PermissionVoucherDeleteResultResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code: {type: string, enum: [OK]}
    message: {type: string, enum: [success]}
    data: {$ref: '#/PermissionVoucherDeleteResult'}
    requestId: {type: string, format: uuid}

PermissionDetailResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code: {type: string, enum: [OK]}
    message: {type: string, enum: [success]}
    data: {$ref: '#/PermissionDetail'}
    requestId: {type: string, format: uuid}

AuditGranularity:
  type: string
  enum: [DAY, WEEK, MONTH]

AuditLogSummary:
  type: object
  additionalProperties: false
  required:
    - id
    - username
    - realName
    - organizationName
    - actionType
    - targetType
    - targetId
    - targetName
    - operationResult
    - failureReason
    - clientIp
    - requestId
    - createdAt
  properties:
    id: {$ref: '#/StringId'}
    username: {type: string, nullable: true}
    realName: {type: string, nullable: true}
    organizationName: {type: string, nullable: true}
    actionType: {$ref: '#/AuditAction'}
    targetType:
      allOf: [{$ref: '#/AuditTarget'}]
      nullable: true
    targetId:
      allOf: [{$ref: '#/StringId'}]
      nullable: true
    targetName: {type: string, nullable: true}
    operationResult: {$ref: '#/AuditResult'}
    failureReason: {type: string, nullable: true}
    clientIp: {type: string, nullable: true}
    requestId: {type: string, nullable: true}
    createdAt: {$ref: '#/UtcDateTime'}

AuditLogPage:
  type: object
  additionalProperties: false
  required: [items, page, pageSize, total, totalPages]
  properties:
    items: {type: array, items: {$ref: '#/AuditLogSummary'}}
    page: {type: integer, minimum: 1}
    pageSize: {type: integer, minimum: 1, maximum: 100}
    total: {type: integer, minimum: 0}
    totalPages: {type: integer, minimum: 0}

AuditLogPageResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code: {type: string, enum: [OK]}
    message: {type: string, enum: [success]}
    data: {$ref: '#/AuditLogPage'}
    requestId: {type: string, format: uuid}

DocumentStatistics:
  type: object
  additionalProperties: false
  required: [planDocumentCount, mainPlanCount, subPlanCount, attachmentCount, todayViewerCount]
  properties:
    planDocumentCount: {type: integer, minimum: 0}
    mainPlanCount: {type: integer, minimum: 0}
    subPlanCount: {type: integer, minimum: 0}
    attachmentCount: {type: integer, minimum: 0}
    todayViewerCount: {type: integer, minimum: 0}

DocumentStatisticsResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code: {type: string, enum: [OK]}
    message: {type: string, enum: [success]}
    data: {$ref: '#/DocumentStatistics'}
    requestId: {type: string, format: uuid}

AuditTrendItem:
  type: object
  additionalProperties: false
  required: [period, operationCount]
  properties:
    period: {type: string}
    operationCount: {type: integer, minimum: 0}

AuditTrendData:
  type: object
  additionalProperties: false
  required: [items]
  properties:
    items: {type: array, items: {$ref: '#/AuditTrendItem'}}

AuditTrendResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code: {type: string, enum: [OK]}
    message: {type: string, enum: [success]}
    data: {$ref: '#/AuditTrendData'}
    requestId: {type: string, format: uuid}

AuditActionStatisticsItem:
  type: object
  additionalProperties: false
  required: [actionType, count]
  properties:
    actionType: {$ref: '#/AuditAction'}
    count: {type: integer, minimum: 0}

AuditActionStatisticsData:
  type: object
  additionalProperties: false
  required: [items]
  properties:
    items: {type: array, items: {$ref: '#/AuditActionStatisticsItem'}}

AuditActionStatisticsResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code: {type: string, enum: [OK]}
    message: {type: string, enum: [success]}
    data: {$ref: '#/AuditActionStatisticsData'}
    requestId: {type: string, format: uuid}

AuditUserStatisticsItem:
  type: object
  additionalProperties: false
  required: [userId, realName, organizationName, operationCount]
  properties:
    userId: {$ref: '#/StringId'}
    realName: {type: string, nullable: true}
    organizationName: {type: string, nullable: true}
    operationCount: {type: integer, minimum: 0}

AuditUserStatisticsData:
  type: object
  additionalProperties: false
  required: [items]
  properties:
    items: {type: array, items: {$ref: '#/AuditUserStatisticsItem'}}

AuditUserStatisticsResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code: {type: string, enum: [OK]}
    message: {type: string, enum: [success]}
    data: {$ref: '#/AuditUserStatisticsData'}
    requestId: {type: string, format: uuid}

DeletedBySnapshot:
  type: object
  additionalProperties: false
  required: [userId, username, realName, organizationName]
  properties:
    userId:
      allOf:
        - $ref: '#/StringId'
      nullable: true
    username: {type: string, nullable: true}
    realName: {type: string, nullable: true}
    organizationName: {type: string, nullable: true}

RecycleBinDocumentSummary:
  type: object
  additionalProperties: false
  required:
    - id
    - documentName
    - documentType
    - originalFileName
    - categoryId
    - categoryName
    - parentDocumentId
    - securityLevel
    - documentStatus
    - deletedAt
    - updatedBy
    - updatedByName
    - deletedBy
    - rowVersion
  properties:
    id: {$ref: '#/StringId'}
    documentName: {type: string}
    documentType: {$ref: '#/DocumentType'}
    originalFileName: {type: string}
    categoryId:
      allOf:
        - $ref: '#/StringId'
      nullable: true
    categoryName: {type: string, nullable: true}
    parentDocumentId:
      allOf:
        - $ref: '#/StringId'
      nullable: true
    securityLevel: {$ref: '#/SecurityLevel'}
    documentStatus: {$ref: '#/DocumentStatus'}
    deletedAt: {$ref: '#/UtcDateTime'}
    updatedBy:
      allOf:
        - $ref: '#/StringId'
      nullable: true
    updatedByName: {type: string, nullable: true}
    deletedBy:
      allOf:
        - $ref: '#/DeletedBySnapshot'
      nullable: true
    rowVersion: {type: integer, minimum: 0}

RecycleBinDocumentPage:
  type: object
  additionalProperties: false
  required: [items, page, pageSize, total, totalPages]
  properties:
    items:
      type: array
      items: {$ref: '#/RecycleBinDocumentSummary'}
    page: {type: integer, minimum: 1}
    pageSize: {type: integer, minimum: 1, maximum: 100}
    total: {type: integer, minimum: 0}
    totalPages: {type: integer, minimum: 0}

RecycleBinDocumentPageResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code: {type: string, enum: [OK]}
    message: {type: string, enum: [success]}
    data: {$ref: '#/RecycleBinDocumentPage'}
    requestId: {type: string, format: uuid}

RestoreDocumentRequest:
  type: object
  additionalProperties: false
  required: [rowVersion]
  properties:
    rowVersion: {type: integer, minimum: 0}

RestoredDocument:
  allOf:
    - $ref: '#/DocumentSummary'
    - type: object
      required: [originalFileName, mimeType, fileSize, permissionSummary]
      properties:
        originalFileName: {type: string}
        mimeType: {type: string, nullable: true}
        fileSize: {type: integer, minimum: 0}
        permissionSummary: {$ref: '#/PermissionSummary'}
        mountedPlanCount: {type: integer, minimum: 0}

RestoreDocumentResult:
  type: object
  additionalProperties: false
  required:
    - document
    - restoredPermissionCount
    - skippedPermissionCount
    - restoredBindingCount
    - skippedBindingCount
  properties:
    document: {$ref: '#/RestoredDocument'}
    restoredPermissionCount: {type: integer, minimum: 0}
    skippedPermissionCount: {type: integer, minimum: 0}
    restoredBindingCount: {type: integer, minimum: 0}
    skippedBindingCount: {type: integer, minimum: 0}

RestoreDocumentResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code: {type: string, enum: [OK]}
    message: {type: string, enum: [success]}
    data: {$ref: '#/RestoreDocumentResult'}
    requestId: {type: string, format: uuid}

DictionaryOption:
  type: object
  additionalProperties: false
  required: [code, label, sortNo]
  properties:
    code: {type: string, minLength: 1}
    label: {type: string, minLength: 1}
    sortNo: {type: integer, minimum: 0}

DictionaryOptionList:
  type: array
  items: {$ref: '#/DictionaryOption'}

UiDictionaryGroups:
  type: object
  additionalProperties: false
  required:
    - roleCodes
    - allowedModules
    - documentTypes
    - documentStatuses
    - securityLevels
    - attachmentTypes
    - deptScopes
    - allowedActions
    - categoryTypes
    - enabledStatuses
    - auditResults
    - auditActions
    - auditTargets
  properties:
    roleCodes: {$ref: '#/DictionaryOptionList'}
    allowedModules: {$ref: '#/DictionaryOptionList'}
    documentTypes: {$ref: '#/DictionaryOptionList'}
    documentStatuses: {$ref: '#/DictionaryOptionList'}
    securityLevels: {$ref: '#/DictionaryOptionList'}
    attachmentTypes: {$ref: '#/DictionaryOptionList'}
    deptScopes: {$ref: '#/DictionaryOptionList'}
    allowedActions: {$ref: '#/DictionaryOptionList'}
    categoryTypes: {$ref: '#/DictionaryOptionList'}
    enabledStatuses: {$ref: '#/DictionaryOptionList'}
    auditResults: {$ref: '#/DictionaryOptionList'}
    auditActions: {$ref: '#/DictionaryOptionList'}
    auditTargets: {$ref: '#/DictionaryOptionList'}

UiDictionaries:
  type: object
  additionalProperties: false
  required: [version, locale, dictionaries]
  properties:
    version:
      type: string
      pattern: '^[0-9]{4}\.[0-9]+$'
      example: '2026.1'
    locale:
      type: string
      example: zh-CN
    dictionaries: {$ref: '#/UiDictionaryGroups'}

UiDictionariesResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code: {type: string, enum: [OK]}
    message: {type: string, enum: [success]}
    data: {$ref: '#/UiDictionaries'}
    requestId: {type: string, format: uuid}

CreateOrganizationRequest:
  type: object
  additionalProperties: false
  required: [orgCode, orgName, parentId, sortNo, status]
  properties:
    orgCode: {type: string, minLength: 1, maxLength: 64}
    orgName: {type: string, minLength: 1, maxLength: 128}
    parentId:
      allOf: [{$ref: '#/StringId'}]
      nullable: true
    sortNo: {type: integer}
    status: {$ref: '#/EnabledStatus'}

UpdateOrganizationRequest:
  type: object
  additionalProperties: false
  required: [orgName, parentId, sortNo, status, rowVersion]
  properties:
    orgName: {type: string, minLength: 1, maxLength: 128}
    parentId:
      allOf: [{$ref: '#/StringId'}]
      nullable: true
    sortNo: {type: integer}
    status: {$ref: '#/EnabledStatus'}
    rowVersion: {type: integer, minimum: 0}

OrganizationResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code: {type: string, enum: [OK]}
    message: {type: string, enum: [success]}
    data:
      allOf: [{$ref: '#/OrganizationNode'}]
      description: 写操作响应中children固定为空数组。
    requestId: {type: string, format: uuid}

DeleteOrganizationData:
  type: object
  additionalProperties: false
  required: [id, deleted]
  properties:
    id: {$ref: '#/StringId'}
    deleted: {type: boolean, enum: [true]}

DeleteOrganizationResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code: {type: string, enum: [OK]}
    message: {type: string, enum: [success]}
    data: {$ref: '#/DeleteOrganizationData'}
    requestId: {type: string, format: uuid}

CreateUserRequest:
  type: object
  additionalProperties: false
  required: [username, realName, initialPassword, organizationId, roleCode, roleId, securityLevel, status]
  properties:
    username: {type: string, minLength: 1, maxLength: 64}
    realName: {type: string, minLength: 1, maxLength: 64}
    initialPassword: {type: string, format: password, minLength: 8, maxLength: 64, writeOnly: true}
    organizationId:
      allOf: [{$ref: '#/StringId'}]
      nullable: true
    roleCode: {$ref: '#/RoleCode'}
    roleId:
      allOf: [{$ref: '#/StringId'}]
      nullable: true
    securityLevel: {$ref: '#/SecurityLevel'}
    status: {$ref: '#/EnabledStatus'}

UpdateUiThemeRequest:
  type: object
  additionalProperties: false
  required: [uiTheme]
  properties:
    uiTheme: {type: string, enum: [blue, red, green]}

UpdateUserRequest:
  type: object
  additionalProperties: false
  required: [realName, organizationId, roleCode, roleId, securityLevel, status, rowVersion]
  properties:
    realName: {type: string, minLength: 1, maxLength: 64}
    organizationId:
      allOf: [{$ref: '#/StringId'}]
      nullable: true
    roleCode: {$ref: '#/RoleCode'}
    roleId:
      allOf: [{$ref: '#/StringId'}]
      nullable: true
    securityLevel: {$ref: '#/SecurityLevel'}
    status: {$ref: '#/EnabledStatus'}
    rowVersion: {type: integer, minimum: 0}

DeleteUserData:
  type: object
  additionalProperties: false
  required: [id, deleted]
  properties:
    id: {$ref: '#/StringId'}
    deleted: {type: boolean, enum: [true]}

DeleteUserResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code: {type: string, enum: [OK]}
    message: {type: string, enum: [success]}
    data: {$ref: '#/DeleteUserData'}
    requestId: {type: string, format: uuid}

ResetUserPasswordRequest:
  type: object
  additionalProperties: false
  required: [newPassword, rowVersion]
  properties:
    newPassword: {type: string, format: password, minLength: 8, maxLength: 64, writeOnly: true}
    rowVersion: {type: integer, minimum: 0}

ResetPasswordData:
  type: object
  additionalProperties: false
  required: [id, reset, authVersion]
  properties:
    id: {$ref: '#/StringId'}
    reset: {type: boolean, enum: [true]}
    authVersion: {type: integer, minimum: 0}

ResetPasswordResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code: {type: string, enum: [OK]}
    message: {type: string, enum: [success]}
    data: {$ref: '#/ResetPasswordData'}
    requestId: {type: string, format: uuid}

DocumentTagCollection:
  type: object
  additionalProperties: false
  required: [items, total]
  properties:
    items:
      type: array
      items: {type: string}
      description: 当前用户可见的主案标签，按Unicode升序。
    total: {type: integer, minimum: 0}

DocumentTagsResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code: {type: string, enum: [OK]}
    message: {type: string, enum: [success]}
    data: {$ref: '#/DocumentTagCollection'}
    requestId: {type: string, format: uuid}

DeptScope:
  type: string
  description: 权限矩阵部门范围：所属部门方案/其他部门方案（其他部门含所属部门子树外全部部门与无归属文档）。
  enum: [OWN, OTHER]

RoleSummary:
  type: object
  additionalProperties: false
  required: [id, roleName, sortNo, status, remark, isDefault, manageCategoryEdit, manageOrgEdit, manageUserEdit, managedOrgId, memberCount, rowVersion]
  properties:
    id: {$ref: '#/StringId'}
    roleName: {type: string, maxLength: 64}
    sortNo: {type: integer, minimum: 0, maximum: 999999}
    status: {$ref: '#/EnabledStatus'}
    remark:
      type: string
      nullable: true
      maxLength: 255
    isDefault: {type: boolean}
    manageCategoryEdit: {type: boolean, description: 分类编辑管理位（仅对ADMIN类别用户生效）}
    manageOrgEdit: {type: boolean, description: 机构编辑管理位（仅对ADMIN类别用户生效）}
    manageUserEdit: {type: boolean, description: 用户编辑管理位（仅对ADMIN类别用户生效）}
    managedOrgId:
      type: string
      nullable: true
      description: 管理范围锚点；机构ID、"SELF"（跟随用户自身所在部门，落库哨兵0）或null（全局）。
    memberCount: {type: integer, minimum: 0}
    rowVersion: {type: integer, minimum: 0}

RolePage:
  type: object
  additionalProperties: false
  required: [items, page, pageSize, total, totalPages]
  properties:
    items:
      type: array
      items:
        $ref: '#/RoleSummary'
    page:
      type: integer
      minimum: 1
    pageSize:
      type: integer
      minimum: 1
      maximum: 100
    total:
      type: integer
      minimum: 0
    totalPages:
      type: integer
      minimum: 0

RolePageResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code: {type: string, enum: [OK]}
    message: {type: string, enum: [success]}
    data: {$ref: '#/RolePage'}
    requestId: {type: string, format: uuid}

CreateRoleRequest:
  type: object
  additionalProperties: false
  required: [roleName, sortNo, status, remark, isDefault, manageCategoryEdit, manageOrgEdit, manageUserEdit, managedOrgId]
  properties:
    roleName: {type: string, minLength: 1, maxLength: 64}
    sortNo: {type: integer, minimum: 0, maximum: 999999}
    status: {$ref: '#/EnabledStatus'}
    remark:
      type: string
      nullable: true
      maxLength: 255
    isDefault: {type: boolean}
    manageCategoryEdit: {type: boolean}
    manageOrgEdit: {type: boolean}
    manageUserEdit: {type: boolean}
    managedOrgId:
      type: string
      nullable: true
      description: 管理范围锚点；机构ID、"SELF"（跟随用户自身所在部门，落库哨兵0）或null/空串（全局），机构ID须指向未删除机构。

UpdateRoleRequest:
  type: object
  additionalProperties: false
  required: [roleName, sortNo, status, remark, isDefault, manageCategoryEdit, manageOrgEdit, manageUserEdit, managedOrgId, rowVersion]
  properties:
    roleName: {type: string, minLength: 1, maxLength: 64}
    sortNo: {type: integer, minimum: 0, maximum: 999999}
    status: {$ref: '#/EnabledStatus'}
    remark:
      type: string
      nullable: true
      maxLength: 255
    isDefault: {type: boolean}
    manageCategoryEdit: {type: boolean}
    manageOrgEdit: {type: boolean}
    manageUserEdit: {type: boolean}
    managedOrgId:
      type: string
      nullable: true
      description: 管理范围锚点；机构ID、"SELF"（跟随用户自身所在部门，落库哨兵0）或null/空串（全局），机构ID须指向未删除机构。
    rowVersion: {type: integer, minimum: 0}

RoleResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code: {type: string, enum: [OK]}
    message: {type: string, enum: [success]}
    data: {$ref: '#/RoleSummary'}
    requestId: {type: string, format: uuid}

DeleteRoleData:
  type: object
  additionalProperties: false
  required: [id, deleted]
  properties:
    id: {$ref: '#/StringId'}
    deleted: {type: boolean, enum: [true]}

DeleteRoleResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code: {type: string, enum: [OK]}
    message: {type: string, enum: [success]}
    data: {$ref: '#/DeleteRoleData'}
    requestId: {type: string, format: uuid}

RolePermissionRow:
  type: object
  additionalProperties: false
  required: [securityLevel, deptScope, canView, canDownload, canEdit, canDelete, canConfigPermission, canBindAttachment, canUnbindAttachment]
  properties:
    securityLevel: {$ref: '#/SecurityLevel'}
    deptScope: {$ref: '#/DeptScope'}
    canView: {type: boolean}
    canDownload: {type: boolean}
    canEdit: {type: boolean}
    canDelete: {type: boolean}
    canConfigPermission: {type: boolean}
    canBindAttachment: {type: boolean}
    canUnbindAttachment: {type: boolean}

RoleMatrixListResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code: {type: string, enum: [OK]}
    message: {type: string, enum: [success]}
    data:
      type: array
      minItems: 15
      maxItems: 15
      items:
        $ref: '#/RolePermissionRow'
    requestId: {type: string, format: uuid}

UpdateRolePermissionsRequest:
  type: object
  additionalProperties: false
  required: [matrix, rowVersion]
  properties:
    matrix:
      type: array
      minItems: 15
      maxItems: 15
      items:
        $ref: '#/RolePermissionRow'
    rowVersion: {type: integer, minimum: 0}

RolePermissionsData:
  type: object
  additionalProperties: false
  required: [id, matrix, rowVersion]
  properties:
    id: {$ref: '#/StringId'}
    matrix:
      type: array
      minItems: 15
      maxItems: 15
      items:
        $ref: '#/RolePermissionRow'
    rowVersion: {type: integer, minimum: 0}

RolePermissionsResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code: {type: string, enum: [OK]}
    message: {type: string, enum: [success]}
    data: {$ref: '#/RolePermissionsData'}
    requestId: {type: string, format: uuid}

RoleUsersData:
  type: object
  additionalProperties: false
  required: [id, userIds]
  properties:
    id: {$ref: '#/StringId'}
    userIds:
      type: array
      items: {$ref: '#/StringId'}
      uniqueItems: true
    rowVersion: {type: integer, minimum: 0}

RoleUsersResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code: {type: string, enum: [OK]}
    message: {type: string, enum: [success]}
    data: {$ref: '#/RoleUsersData'}
    requestId: {type: string, format: uuid}

UpdateRoleUsersRequest:
  type: object
  additionalProperties: false
  required: [userIds, rowVersion]
  properties:
    userIds:
      type: array
      items: {$ref: '#/StringId'}
      uniqueItems: true
    rowVersion: {type: integer, minimum: 0}

DocumentRelationPreset:
  type: object
  additionalProperties: false
  required: [code, label, sortNo]
  properties:
    code: {type: string, minLength: 1, description: 预置类型稳定编码（仅用于前端下拉匹配，不落库）}
    label: {type: string, minLength: 1, description: 预置关系文本（保存时直接写入relation_type）}
    sortNo: {type: integer, minimum: 0}

DocumentMoveRequest:
  type: object
  additionalProperties: false
  description: targetPosition与target二选一（非法组合返回400）；主案可携带scopeCategoryId（分类子树语义），配套方案携带返回400。
  properties:
    targetPosition: {type: integer, minimum: 1}
    target: {type: string, enum: [TOP, BOTTOM]}
    scopeCategoryId: {$ref: '#/StringId'}

DocumentMoveResult:
  type: object
  additionalProperties: false
  required: [position, total]
  properties:
    position: {type: integer, minimum: 1}
    total: {type: integer, minimum: 0}

DocumentMoveResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code: {type: string, enum: [OK]}
    message: {type: string, enum: [success]}
    data: {$ref: '#/DocumentMoveResult'}
    requestId: {type: string, format: uuid}

AttachmentMoveRequest:
  type: object
  additionalProperties: false
  required: [mainPlanRowVersion]
  description: targetPosition与target二选一（非法组合返回400）；scopeAttachmentType限定页签类型范围。
  properties:
    mainPlanRowVersion: {type: integer, minimum: 0}
    targetPosition: {type: integer, minimum: 1}
    target: {type: string, enum: [TOP, BOTTOM]}
    scopeAttachmentType: {$ref: '#/AttachmentType'}

AttachmentMoveResult:
  type: object
  additionalProperties: false
  required: [position, total, mainPlanRowVersion]
  properties:
    position: {type: integer, minimum: 1}
    total: {type: integer, minimum: 0}
    mainPlanRowVersion: {type: integer, minimum: 0}

AttachmentMoveResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code: {type: string, enum: [OK]}
    message: {type: string, enum: [success]}
    data: {$ref: '#/AttachmentMoveResult'}
    requestId: {type: string, format: uuid}

DocumentRelationPresetsResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code: {type: string, enum: [OK]}
    message: {type: string, enum: [success]}
    data:
      type: object
      additionalProperties: false
      required: [presets]
      properties:
        presets:
          type: array
          items: {$ref: '#/DocumentRelationPreset'}
    requestId: {type: string, format: uuid}

DocumentRelationItem:
  type: object
  additionalProperties: false
  required: [relatedDocumentId, relatedDocumentName, relationType]
  properties:
    relatedDocumentId: {$ref: '#/StringId'}
    relatedDocumentName: {type: string, minLength: 1}
    relationType: {type: string, minLength: 1, maxLength: 64, description: 关系文本（预置label或用户自定义）}

DocumentRelationsResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code: {type: string, enum: [OK]}
    message: {type: string, enum: [success]}
    data:
      type: object
      additionalProperties: false
      required: [items]
      properties:
        items:
          type: array
          items: {$ref: '#/DocumentRelationItem'}
    requestId: {type: string, format: uuid}

UpdateDocumentRelationsRequest:
  type: object
  additionalProperties: false
  required: [relations, rowVersion]
  properties:
    relations:
      type: array
      maxItems: 50
      items:
        type: object
        additionalProperties: false
        required: [relatedDocumentId, relationType]
        properties:
          relatedDocumentId: {$ref: '#/StringId'}
          relationType: {type: string, minLength: 1, maxLength: 64}
      uniqueItems: true
    rowVersion: {type: integer, minimum: 0}

DocumentRelationsSaveResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code: {type: string, enum: [OK]}
    message: {type: string, enum: [success]}
    data:
      type: object
      additionalProperties: false
      required: [relations, rowVersion]
      properties:
        relations:
          type: array
          items: {$ref: '#/DocumentRelationItem'}
        rowVersion: {type: integer, minimum: 0}
    requestId: {type: string, format: uuid}

IpEntrySummary:
  type: object
  additionalProperties: false
  required: [id, ipValue, remark, rowVersion]
  properties:
    id: {$ref: '#/StringId'}
    ipValue:
      type: string
      minLength: 1
      maxLength: 64
      description: 规范化后的精确IP或CIDR网段文本（IPv6为压缩形式，网段主机位为0）。
    remark:
      type: string
      maxLength: 128
    rowVersion: {type: integer, minimum: 0}

IpEntryPage:
  type: object
  additionalProperties: false
  required: [items, page, pageSize, total, totalPages]
  properties:
    items:
      type: array
      items:
        $ref: '#/IpEntrySummary'
    page:
      type: integer
      minimum: 1
    pageSize:
      type: integer
      minimum: 1
      maximum: 100
    total:
      type: integer
      minimum: 0
    totalPages:
      type: integer
      minimum: 0

IpEntryPageResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code: {type: string, enum: [OK]}
    message: {type: string, enum: [success]}
    data: {$ref: '#/IpEntryPage'}
    requestId: {type: string, format: uuid}

CreateIpEntryRequest:
  type: object
  additionalProperties: false
  required: [ipValue, remark]
  properties:
    ipValue: {type: string, minLength: 1, maxLength: 64}
    remark: {type: string, maxLength: 128}

UpdateIpEntryRequest:
  type: object
  additionalProperties: false
  required: [ipValue, remark, rowVersion]
  properties:
    ipValue: {type: string, minLength: 1, maxLength: 64}
    remark: {type: string, maxLength: 128}
    rowVersion: {type: integer, minimum: 0}

IpEntryResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code: {type: string, enum: [OK]}
    message: {type: string, enum: [success]}
    data: {$ref: '#/IpEntrySummary'}
    requestId: {type: string, format: uuid}

DeleteIpEntryData:
  type: object
  additionalProperties: false
  required: [id, deleted]
  properties:
    id: {$ref: '#/StringId'}
    deleted: {type: boolean, enum: [true]}

DeleteIpEntryResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code: {type: string, enum: [OK]}
    message: {type: string, enum: [success]}
    data: {$ref: '#/DeleteIpEntryData'}
    requestId: {type: string, format: uuid}

OrgIpAssignmentListData:
  type: object
  additionalProperties: false
  required: [ipEntryIds]
  properties:
    ipEntryIds:
      type: array
      items: {$ref: '#/StringId'}
      uniqueItems: true

OrgIpAssignmentListResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code: {type: string, enum: [OK]}
    message: {type: string, enum: [success]}
    data: {$ref: '#/OrgIpAssignmentListData'}
    requestId: {type: string, format: uuid}

UpdateOrgIpAssignmentsRequest:
  type: object
  additionalProperties: false
  required: [ipEntryIds, rowVersion]
  properties:
    ipEntryIds:
      type: array
      items: {$ref: '#/StringId'}
      uniqueItems: true
    rowVersion: {type: integer, minimum: 0}

OrgIpAssignmentsData:
  type: object
  additionalProperties: false
  required: [id, ipEntryIds, rowVersion]
  properties:
    id: {$ref: '#/StringId'}
    ipEntryIds:
      type: array
      items: {$ref: '#/StringId'}
      uniqueItems: true
    rowVersion: {type: integer, minimum: 0}

OrgIpAssignmentsResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code: {type: string, enum: [OK]}
    message: {type: string, enum: [success]}
    data: {$ref: '#/OrgIpAssignmentsData'}
    requestId: {type: string, format: uuid}