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
    - BACKUP_CREATE

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

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
        - BACKUP_RUNNING
        - BACKUP_TARGET_UNAVAILABLE
        - BACKUP_TOOL_MISSING
        - BACKUP_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
    - permSystemManage
    - permAuditLog
    - permRoleEdit
    - permUpload
    - 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: 用户编辑管理位；值取自生效角色。
    permSystemManage:
      type: boolean
      description: 系统管理管理位（契约1.23）；值取自生效角色，内置admin恒为true。
    permAuditLog:
      type: boolean
      description: 日志审计管理位（契约1.23）；值取自生效角色，内置admin恒为true。
    permRoleEdit:
      type: boolean
      description: 角色编辑管理位（契约1.25）；值取自生效角色，内置admin恒为true。
    permUpload:
      type: boolean
      description: 上传位（契约1.31）；生效角色方案权限矩阵任一 OWN 行 canUpload 为 true 即为 true，内置admin恒为true；上传/批量导入接口按此判定。
    managedOrgId:
      type: string
      nullable: true
      description: 用户级管理范围（契约1.30）；为机构ID（固定锚点）、"SELF"（跟随该用户所在机构，落库哨兵0）或null（全局），内置admin恒为null。实际生效范围以生效角色锚点为准，角色锚点为"SELF"（跟随用户设置）时才回落本设置。

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
    captchaId:
      type: string
      description: 图片验证码标识（安全需求4）；DMS_CAPTCHA_ENABLED开启时必填（五键），关闭时不得携带（三键）
    captchaCode:
      type: string
      description: 图片验证码字符（安全需求4，忽略大小写）；开关开启时必填

LoginData:
  type: object
  additionalProperties: false
  required: [accessToken, tokenType, expiresIn, idleLogoutMinutes, user]
  properties:
    accessToken:
      type: string
    tokenType:
      type: string
      enum: [Bearer]
    expiresIn:
      type: integer
      description: 访问令牌有效期秒数；keepSignedIn=false取环境变量DMS_JWT_EXPIRES_SECONDS（缺省3600），keepSignedIn=true固定604800。
    idleLogoutMinutes:
      type: integer
      minimum: 0
      description: 页面空闲自动登出分钟数（契约1.29）；取环境变量DMS_IDLE_LOGOUT_MINUTES（缺省5），0表示关闭。
    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}

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

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

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

ReorderResultResponse:
  type: object
  additionalProperties: false
  required: [code, message, data, requestId]
  properties:
    code: {type: string, enum: [OK]}
    message: {type: string, enum: [success]}
    data: {$ref: '#/ReorderResultData'}
    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'}
    managedOrgId:
      type: string
      nullable: true
      description: 用户级管理范围（契约1.30，可选）；null=全局、机构ID=固定锚点（须指向未删除机构）。省略或"SELF"时跟随该用户所在机构（落库哨兵0）。

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'}
    managedOrgId:
      type: string
      nullable: true
      description: 用户级管理范围（契约1.30，可选）；null=全局、机构ID=固定锚点（须指向未删除机构）、"SELF"=跟随该用户所在机构（落库哨兵0）。省略时保持原值不变。
    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, manageSystemManage, manageAuditLog, manageRoleEdit, 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类别用户生效）}
    manageSystemManage: {type: boolean, description: 系统管理管理位（契约1.23，仅对ADMIN类别用户生效）}
    manageAuditLog: {type: boolean, description: 日志审计管理位（契约1.23，仅对ADMIN类别用户生效）}
    manageRoleEdit: {type: boolean, description: 角色编辑管理位（契约1.25，仅对ADMIN类别用户生效，全局生效不受锚点约束）}
    managedOrgId:
      type: string
      nullable: true
      description: 管理范围锚点（契约1.30）；机构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, manageSystemManage, manageAuditLog, manageRoleEdit, 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}
    manageSystemManage: {type: boolean}
    manageAuditLog: {type: boolean}
    manageRoleEdit: {type: boolean}
    managedOrgId:
      type: string
      nullable: true
      description: 管理范围锚点（契约1.30）；机构ID、"SELF"（跟随用户的管理范围设置，落库哨兵0）或null/空串（全局），机构ID须指向未删除机构。

UpdateRoleRequest:
  type: object
  additionalProperties: false
  required: [roleName, sortNo, status, remark, isDefault, manageCategoryEdit, manageOrgEdit, manageUserEdit, manageSystemManage, manageAuditLog, manageRoleEdit, 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}
    manageSystemManage: {type: boolean}
    manageAuditLog: {type: boolean}
    manageRoleEdit: {type: boolean}
    managedOrgId:
      type: string
      nullable: true
      description: 管理范围锚点（契约1.30）；机构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, canUpload, canDownload, canEdit, canDelete, canConfigPermission, canBindAttachment, canUnbindAttachment]
  properties:
    securityLevel: {$ref: '#/SecurityLevel'}
    deptScope: {$ref: '#/DeptScope'}
    canView: {type: boolean}
    canUpload:
      type: boolean
      description: 上传位（契约1.31）；仅 OWN 行有意义，OTHER 行恒为 false，服务端提交校验拒收 OTHER 行为 true 的载荷。
    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网段或IP范围文本（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}

BackupTargetMode:
  type: string
  enum: [LOCAL, RSYNC]
  description: 备份目标模式：LOCAL 本机目录（开发/单机），RSYNC rsync守护进程异机传输。

BackupTypeCode:
  type: string
  enum: [FULL, INCREMENTAL]

BackupTrigger:
  type: string
  enum: [MANUAL, SCHEDULE]

BackupPhase:
  type: string
  description: 备份任务阶段；null表示从未运行过任何任务。
  enum: [SCANNING, EXPORTING_DB, COPYING, PUSHING, CLEANING, SUCCESS, FAILED]

BackupConfigView:
  type: object
  additionalProperties: false
  required: [target_mode, local_path, rsync_url, schedule_enabled, schedule_time, full_interval_days, retain_full_count, rsync_password_set]
  properties:
    target_mode: {$ref: '#/BackupTargetMode'}
    local_path: {type: string, maxLength: 1024, description: LOCAL模式的备份根目录；未配置为空串。}
    rsync_url: {type: string, maxLength: 1024, description: RSYNC模式目标地址 rsync://user@host:873/module/；未配置为空串。}
    schedule_enabled: {type: boolean, description: 定时备份开关。}
    schedule_time: {type: string, pattern: '^([01][0-9]|2[0-3]):[0-5][0-9]$', description: 每日触发时刻（HH:MM，业务时区）。}
    full_interval_days: {type: integer, minimum: 1, maximum: 365, description: 定时任务距最近全量超过该天数时自动升级为全量。}
    retain_full_count: {type: integer, minimum: 1, maximum: 100, description: 保留的完整备份链数量；超出部分从最旧链开始清理。}
    rsync_password_set: {type: boolean, description: rsync密码是否已设置；密码永不回显明文。}

UpdateBackupConfigRequest:
  type: object
  additionalProperties: false
  required: [target_mode, local_path, rsync_url, rsync_password, schedule_enabled, schedule_time, full_interval_days, retain_full_count]
  properties:
    target_mode: {$ref: '#/BackupTargetMode'}
    local_path: {type: string, nullable: true, maxLength: 1024}
    rsync_url: {type: string, nullable: true, maxLength: 1024}
    rsync_password:
      type: string
      nullable: true
      maxLength: 256
      writeOnly: true
      description: rsync密码；null或空串表示保持已存密码不变（回显永不回明文）。
    schedule_enabled: {type: boolean}
    schedule_time: {type: string, pattern: '^([01][0-9]|2[0-3]):[0-5][0-9]$'}
    full_interval_days: {type: integer, minimum: 1, maximum: 365}
    retain_full_count: {type: integer, minimum: 1, maximum: 100}

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

BackupJobStartRequest:
  type: object
  additionalProperties: false
  required: [type]
  properties:
    type:
      allOf: [{$ref: '#/BackupTypeCode'}]
      description: INCREMENTAL无可用全量链时服务端自动升级为FULL。

BackupProgress:
  type: object
  additionalProperties: false
  required: [backupId, type, trigger, phase, bytesTotal, bytesCopied, filesTotal, filesCopied, pushPercent, error, startedAt, finishedAt]
  properties:
    backupId:
      type: string
      nullable: true
      description: 备份ID，形如 dms-bak-yyyyMMdd-HHmmss-F/-I；从未运行时为null。
    type:
      allOf: [{$ref: '#/BackupTypeCode'}]
      nullable: true
    trigger:
      allOf: [{$ref: '#/BackupTrigger'}]
      nullable: true
    phase:
      allOf: [{$ref: '#/BackupPhase'}]
      nullable: true
    bytesTotal: {type: integer, minimum: 0, description: 待传输字节总量（扫描/拷贝阶段累计）。}
    bytesCopied: {type: integer, minimum: 0}
    filesTotal: {type: integer, minimum: 0}
    filesCopied: {type: integer, minimum: 0}
    pushPercent:
      type: integer
      minimum: 0
      maximum: 100
      nullable: true
      description: rsync整体推送进度百分比；仅RSYNC模式PUSHING阶段有值。
    error:
      type: string
      nullable: true
      description: 失败原因；仅FAILED阶段非null。
    startedAt:
      type: string
      nullable: true
      description: 开始时间（业务时区本地时间，yyyy-MM-dd HH:mm:ss，非UTC）。
    finishedAt:
      type: string
      nullable: true
      description: 结束时间（业务时区本地时间，yyyy-MM-dd HH:mm:ss，非UTC）。

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

BackupCurrentJob:
  allOf:
    - $ref: '#/BackupProgress'
    - type: object
      required: [running]
      properties:
        running: {type: boolean, description: 当前是否有备份任务在执行。}

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

BackupCancelData:
  type: object
  additionalProperties: false
  required: [canceled]
  properties:
    canceled: {type: boolean, description: 请求取消时是否存在运行中的任务。}

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

BackupHistoryEntry:
  type: object
  additionalProperties: false
  required: [id, type, parent, started_at, finished_at, database_file, database_size, transferred_files, transferred_bytes, storage_file_count, storage_total_bytes]
  properties:
    id: {type: string, description: 备份ID dms-bak-yyyyMMdd-HHmmss-F（全量）/-I（增量）。}
    type: {$ref: '#/BackupTypeCode'}
    parent:
      type: string
      nullable: true
      description: 增量备份的前驱备份ID；全量为null。
    started_at: {type: string, description: 开始时间（业务时区本地时间，yyyy-MM-dd HH:mm:ss）。}
    finished_at: {type: string, description: 结束时间（业务时区本地时间，yyyy-MM-dd HH:mm:ss）。}
    database_file: {type: string, description: 数据库导出文件在备份包内的相对路径。}
    database_size: {type: integer, minimum: 0, description: 数据库导出文件字节数。}
    transferred_files: {type: integer, minimum: 0, description: 本次实际传输的存储文件数（全量为全部，增量为差异）。}
    transferred_bytes: {type: integer, minimum: 0}
    storage_file_count: {type: integer, minimum: 0, description: 合并清单中的存储文件总数（链尾累计口径）。}
    storage_total_bytes: {type: integer, minimum: 0}

BackupHistoryData:
  type: object
  additionalProperties: false
  required: [entries]
  properties:
    entries:
      type: array
      items: {$ref: '#/BackupHistoryEntry'}
      description: 按备份ID升序（即时间升序）排列。

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

SystemCpuSnapshot:
  type: object
  additionalProperties: false
  required: [percent, coreCount, loadAvgOneMinute]
  properties:
    percent: {type: number, minimum: 0, maximum: 100, description: CPU 总占用百分比（0.3 秒采样窗口）。}
    coreCount: {type: integer, minimum: 0, description: 逻辑核数。}
    loadAvgOneMinute:
      type: number
      nullable: true
      description: 1 分钟平均负载（仅 POSIX，Windows 为 null）。

SystemMemorySnapshot:
  type: object
  additionalProperties: false
  required: [totalBytes, usedBytes, availableBytes, usedPercent]
  properties:
    totalBytes: {type: integer, minimum: 0}
    usedBytes: {type: integer, minimum: 0}
    availableBytes: {type: integer, minimum: 0}
    usedPercent: {type: number, minimum: 0, maximum: 100}

SystemSwapSnapshot:
  type: object
  additionalProperties: false
  required: [totalBytes, usedBytes, usedPercent]
  properties:
    totalBytes: {type: integer, minimum: 0}
    usedBytes: {type: integer, minimum: 0}
    usedPercent: {type: number, minimum: 0, maximum: 100}

SystemDiskSnapshot:
  type: object
  additionalProperties: false
  required: [device, mountpoint, fstype, totalBytes, usedBytes, freeBytes, usedPercent]
  properties:
    device: {type: string, description: 设备名。}
    mountpoint: {type: string, description: 挂载点。}
    fstype: {type: string, description: 文件系统类型。}
    totalBytes: {type: integer, minimum: 0}
    usedBytes: {type: integer, minimum: 0}
    freeBytes: {type: integer, minimum: 0}
    usedPercent: {type: number, minimum: 0, maximum: 100}

SystemMetricsCurrentData:
  type: object
  additionalProperties: false
  required: [cpu, memory, swap, disks, bootAt]
  properties:
    cpu: {$ref: '#/SystemCpuSnapshot'}
    memory: {$ref: '#/SystemMemorySnapshot'}
    swap: {$ref: '#/SystemSwapSnapshot'}
    disks:
      type: array
      items: {$ref: '#/SystemDiskSnapshot'}
      description: 物理磁盘分区占用（不可读分区跳过）。
    bootAt: {type: string, description: 开机时间（UTC，毫秒精度 Z 结尾）。}

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

SystemMetricHistoryEntry:
  type: object
  additionalProperties: false
  required: [sampledAt, cpuPercent, memUsedBytes, memTotalBytes]
  properties:
    sampledAt: {type: string, description: 采样时间（UTC，毫秒精度 Z 结尾）。}
    cpuPercent:
      type: number
      nullable: true
      description: CPU 百分比（采集失败为 null）。
    memUsedBytes: {type: integer, minimum: 0}
    memTotalBytes: {type: integer, minimum: 0}

SystemMetricHistoryData:
  type: object
  additionalProperties: false
  required: [hours, entries]
  properties:
    hours: {type: integer, minimum: 1, description: 查询窗口小时数。}
    entries:
      type: array
      items: {$ref: '#/SystemMetricHistoryEntry'}
      description: 按时间升序排列。

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

SystemProcessData:
  type: object
  additionalProperties: false
  required: [pid, cpuPercent, memoryRssBytes, memoryVmsBytes, threadCount, startedAt, uptimeSeconds, pythonVersion]
  properties:
    pid: {type: integer, minimum: 1}
    cpuPercent: {type: number, description: 进程 CPU 占用（按核数归一后的百分比）。}
    memoryRssBytes: {type: integer, minimum: 0, description: 常驻内存。}
    memoryVmsBytes: {type: integer, minimum: 0, description: 虚拟内存。}
    threadCount: {type: integer, minimum: 1}
    startedAt: {type: string, description: 进程启动时间（UTC，毫秒精度 Z 结尾）。}
    uptimeSeconds: {type: integer, minimum: 0}
    pythonVersion: {type: string, description: 运行时版本（Java 版返回 JDK 版本）。}

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

SystemStorageUsageEntry:
  type: object
  additionalProperties: false
  required: [directory, totalBytes, fileCount]
  properties:
    directory: {type: string, description: 存储子目录名（original/preview/extracted/temporary/quarantine/recycle/voucher）。}
    totalBytes: {type: integer, minimum: 0}
    fileCount: {type: integer, minimum: 0}

SystemStorageUsageData:
  type: object
  additionalProperties: false
  required: [entries]
  properties:
    entries:
      type: array
      items: {$ref: '#/SystemStorageUsageEntry'}

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

SystemConverterData:
  type: object
  additionalProperties: false
  required: [available, executable, maxConcurrency, inFlight, successCount, failureCount, previewEnabled, timeoutSeconds]
  properties:
    available: {type: boolean, description: 转换器是否可用。}
    executable: {type: string, description: LibreOffice 可执行文件路径。}
    maxConcurrency: {type: integer, minimum: 1, description: 并发上限。}
    inFlight: {type: integer, minimum: 0, description: 进行中的转换数。}
    successCount: {type: integer, minimum: 0, description: 累计成功转换数（进程生命周期内）。}
    failureCount: {type: integer, minimum: 0, description: 累计失败转换数（进程生命周期内）。}
    previewEnabled: {type: boolean, description: 预览转换功能是否启用。}
    timeoutSeconds: {type: integer, minimum: 1, description: 单次转换超时秒数。}

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

SystemHealthItem:
  type: object
  additionalProperties: false
  required: [item, ok, detail]
  properties:
    item:
      type: string
      enum: [DATABASE, STORAGE_WRITABLE, LIBREOFFICE, BACKUP_TARGET, STORAGE_ENCRYPTION]
    ok: {type: boolean}
    detail: {type: string, description: 失败原因或补充说明（成功为空/说明文字）。}

SystemHealthData:
  type: object
  additionalProperties: false
  required: [items]
  properties:
    items:
      type: array
      items: {$ref: '#/SystemHealthItem'}

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

SystemInfoData:
  type: object
  additionalProperties: false
  required: [contractVersion, backendKind, runtimeVersion, operatingSystem, hostname, machineArch, databaseType, startedAt, uptimeSeconds, workingDirectory, storageRoot, backupConfigPath, envFilePath, logFilePath, monitoringEnabled]
  properties:
    contractVersion: {type: string, description: 接口契约版本（如 1.26.0）。}
    backendKind: {type: string, enum: [PYTHON, JAVA], description: 后端实现类型。}
    runtimeVersion: {type: string, description: 运行时版本（Python/JDK）。}
    operatingSystem: {type: string}
    hostname: {type: string}
    machineArch: {type: string, description: 体系结构（x86_64/aarch64 等）。}
    databaseType: {type: string, description: 数据库类型描述（DM (达梦)/MySQL 等）。}
    startedAt: {type: string, description: 进程启动时间（UTC；psutil 缺失为空串）。}
    uptimeSeconds: {type: integer, minimum: 0}
    workingDirectory: {type: string}
    storageRoot: {type: string}
    backupConfigPath: {type: string}
    envFilePath: {type: string}
    logFilePath: {type: string, description: 运行日志文件路径（未启用为空串）。}
    monitoringEnabled: {type: boolean, description: 监控信息展示开关（DMS_SYSTEM_MONITOR_ENABLED，缺省 false）；false 时前端隐藏系统管理页维护操作之上的监控区块。}

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

SystemRuntimeConfigEntry:
  type: object
  additionalProperties: false
  required: [category, key, value, unit]
  properties:
    category: {type: string, description: 分类（认证/存储/上传/业务/转换/安全）。}
    key: {type: string, description: 参数显示名。}
    value:
      description: 参数值（密钥类仅显示 已配置/未配置，永不回明文）。
    unit: {type: string, description: 单位（无单位为空串）。}

SystemRuntimeConfigData:
  type: object
  additionalProperties: false
  required: [entries]
  properties:
    entries:
      type: array
      items: {$ref: '#/SystemRuntimeConfigEntry'}

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

SystemLogsData:
  type: object
  additionalProperties: false
  required: [file, lines, truncated]
  properties:
    file: {type: string, description: 日志文件路径（未启用为空串）。}
    lines:
      type: array
      items: {type: string}
      description: 尾部日志行（级别过滤后截尾）。
    truncated: {type: boolean, description: 是否经过截断。}
    error:
      type: string
      description: 读取失败原因（成功时无此字段）。

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

SystemPreviewCacheClearData:
  type: object
  additionalProperties: false
  required: [removedFiles, removedBytes]
  properties:
    removedFiles: {type: integer, minimum: 0, description: 删除的预览文件数。}
    removedBytes: {type: integer, minimum: 0, description: 释放的字节数。}

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

SystemForceOfflineData:
  type: object
  additionalProperties: false
  required: [userId, username, authVersion]
  properties:
    userId: {type: string, description: 目标用户ID（字符串形式）。}
    username: {type: string}
    authVersion: {type: integer, minimum: 1, description: 目标用户当前 auth_version（已 +1）。}

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

BackupTestTargetData:
  type: object
  additionalProperties: false
  required: [ok]
  properties:
    ok: {type: boolean, description: 目标是否可写。}
    target:
      type: string
      description: 目标描述（成功时返回）。
    error:
      type: string
      description: 失败原因（失败时返回）。

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