document-management/backend/dms/common/errors.py

"""DMS业务异常。"""

from __future__ import annotations

from typing import Any


class DmsError(Exception):
    code = "INTERNAL_ERROR"
    status_code = 500
    default_message = "服务器内部错误"

    def __init__(
        self,
        message: str | None = None,
        *,
        details: Any = None,
        code: str | None = None,
    ) -> None:
        super().__init__(message or self.default_message)
        self.message = message or self.default_message
        self.details = details
        self.code = code or self.code


class InvalidArgumentError(DmsError):
    code = "INVALID_ARGUMENT"
    status_code = 400
    default_message = "请求参数错误"


class InvalidCaptchaError(InvalidArgumentError):
    """登录图片验证码缺失/错误/过期（安全需求4），不泄露具体原因。"""

    code = "INVALID_CAPTCHA"
    default_message = "验证码错误或已过期"


class AuthenticationError(DmsError):
    code = "TOKEN_INVALID"
    status_code = 401
    default_message = "未认证或登录凭证无效"


class InvalidCredentialsError(AuthenticationError):
    code = "INVALID_CREDENTIALS"
    default_message = "用户名或密码错误"


class TokenExpiredError(AuthenticationError):
    code = "TOKEN_EXPIRED"
    default_message = "登录凭证已过期"


class UserDisabledError(AuthenticationError):
    code = "USER_DISABLED"
    default_message = "用户已被禁用"


class AuthVersionMismatchError(AuthenticationError):
    code = "AUTH_VERSION_MISMATCH"
    default_message = "登录状态已失效，请重新登录"


class AccountLockedError(AuthenticationError):
    """连续密码错误触发临时锁定（策略见 services/login_lockout.py）。"""

    code = "ACCOUNT_LOCKED"
    default_message = "失败次数过多，账号已临时锁定，请15分钟后重试"


class PortalTokenInvalidError(AuthenticationError):
    code = "PORTAL_TOKEN_INVALID"
    default_message = "门户跳转凭证无效或已过期"


class PortalTicketInvalidError(AuthenticationError):
    code = "PORTAL_TICKET_INVALID"
    default_message = "设置密码凭证无效或已过期，请从门户重新跳转"


class ForbiddenError(DmsError):
    code = "FORBIDDEN"
    status_code = 403
    default_message = "无权限执行此操作"


class SecurityLevelForbiddenError(ForbiddenError):
    code = "SECURITY_LEVEL_FORBIDDEN"
    default_message = "用户密级不足，无法查看该文档"


class DocumentViewForbiddenError(ForbiddenError):
    code = "DOCUMENT_VIEW_FORBIDDEN"
    default_message = "无权查看该文档"


class DocumentDownloadForbiddenError(ForbiddenError):
    code = "DOCUMENT_DOWNLOAD_FORBIDDEN"
    default_message = "无权下载该文档"


class DocumentActionForbiddenError(ForbiddenError):
    """写路径按文档权限（矩阵/ACL）拒绝：区别于密级不足与查看/下载拒绝。"""

    code = "DOCUMENT_ACTION_FORBIDDEN"
    default_message = "无权对该文档执行此操作"


class ResourceNotFoundError(DmsError):
    code = "RESOURCE_NOT_FOUND"
    status_code = 404
    default_message = "请求的资源不存在"


class ConflictError(DmsError):
    code = "DATA_VERSION_CONFLICT"
    status_code = 409
    default_message = "数据冲突"


class CategoryInUseError(ConflictError):
    code = "CATEGORY_IN_USE"
    default_message = "分类仍被子分类或方案文档占用"


class CategoryNotLeafError(ConflictError):
    code = "CATEGORY_NOT_LEAF"
    default_message = "只有有效叶子分类可以直接存放主案"


class CategoryFlatModeConflictError(ConflictError):
    code = "CATEGORY_FLAT_MODE_CONFLICT"
    default_message = "该一级分类下已存在子方案或配套资料挂载，请先解绑后再切换为扁平模式"


class MainPlanNotFoundError(ResourceNotFoundError):
    code = "MAIN_PLAN_NOT_FOUND"
    default_message = "主案不存在"


class FileNotFoundError(ResourceNotFoundError):
    code = "FILE_NOT_FOUND"
    default_message = "文档文件不存在"


class PreviewUnavailableError(DmsError):
    code = "PREVIEW_UNAVAILABLE"
    status_code = 415
    default_message = "当前文件类型不支持在线预览"


class PreviewConverterUnavailableError(DmsError):
    code = "PREVIEW_CONVERTER_UNAVAILABLE"
    status_code = 503
    default_message = "预览转换器未配置或不可用"


class PreviewConversionTimeoutError(DmsError):
    code = "PREVIEW_CONVERSION_TIMEOUT"
    status_code = 504
    default_message = "文档转换超时，请稍后重试"


class PreviewConversionFailedError(DmsError):
    code = "PREVIEW_CONVERSION_FAILED"
    status_code = 502
    default_message = "文档转换为PDF失败"


class BatchManifestMismatchError(InvalidArgumentError):
    code = "BATCH_MANIFEST_MISMATCH"
    default_message = "批量文件数量与元数据数量不一致"


class MainPlanHasChildrenError(ConflictError):
    code = "MAIN_PLAN_HAS_CHILDREN"
    default_message = "主案仍存在有效子方案"


class DocumentNameConflictError(ConflictError):
    code = "DOCUMENT_NAME_CONFLICT"
    default_message = "同一范围内已存在同名方案"


class AttachmentInUseError(ConflictError):
    code = "ATTACHMENT_IN_USE"
    default_message = "共享附件仍被主案挂载"


class AttachmentHasNoAclError(InvalidArgumentError):
    code = "ATTACHMENT_HAS_NO_ACL"
    default_message = "共享附件不配置访问权限"


class SubPlanPermissionInheritedError(ConflictError):
    code = "SUB_PLAN_PERMISSION_INHERITED"
    default_message = "子方案动态继承主案权限，不能独立配置"


class DuplicatePermissionSubjectError(InvalidArgumentError):
    code = "DUPLICATE_PERMISSION_SUBJECT"
    default_message = "权限主体不能重复"


class UnsupportedFileTypeError(DmsError):
    code = "UNSUPPORTED_FILE_TYPE"
    status_code = 415
    default_message = "不支持的文件类型"


class PayloadTooLargeError(DmsError):
    code = "PAYLOAD_TOO_LARGE"
    status_code = 413
    default_message = "请求内容过大"


class InternalError(DmsError):
    code = "INTERNAL_ERROR"
    status_code = 500
    default_message = "服务器内部错误"


class DocumentNotDeletedError(ConflictError):
    code = "DOCUMENT_NOT_DELETED"
    default_message = "文档当前不在回收站中"


class FileIntegrityMismatchError(ConflictError):
    code = "FILE_INTEGRITY_MISMATCH"
    default_message = "文档文件完整性校验失败"


class FilePathInvalidError(InternalError):
    code = "FILE_PATH_INVALID"
    default_message = "文档存储路径异常"


class RestoreFileChangedError(ConflictError):
    code = "RESTORE_FILE_CHANGED"
    default_message = "校验期间文件发生变化"


class RestoreCategoryInvalidError(ConflictError):
    code = "RESTORE_CATEGORY_INVALID"
    default_message = "原方案分类无效，无法恢复"


class RestoreParentInvalidError(ConflictError):
    code = "RESTORE_PARENT_INVALID"
    default_message = "原所属主案无效，无法恢复"


class RestoreRelationConflictError(ConflictError):
    code = "RESTORE_RELATION_CONFLICT"
    default_message = "历史权限或挂载关系与当前有效关系冲突"


class DocumentNotInMoveScopeError(ConflictError):
    """跨页移动时文档不在请求指定的可见范围内（分类或附件类型不符）。"""

    code = "DOCUMENT_NOT_IN_MOVE_SCOPE"
    default_message = "方案不在当前调整范围内"


class OrganizationInUseError(ConflictError):
    code = "ORGANIZATION_IN_USE"
    default_message = "机构仍存在下级机构或挂载用户"


class UserSelfProtectionError(ForbiddenError):
    code = "USER_SELF_PROTECTION"
    default_message = "不能对本账号执行该操作"


class RoleInUseError(ConflictError):
    code = "ROLE_IN_USE"
    default_message = "角色仍有关联用户，无法删除"


class DocumentPasswordRequiredError(ForbiddenError):
    code = "DOCUMENT_PASSWORD_REQUIRED"
    default_message = "该方案已设置密码保护，请输入密码后重试"


class DocumentPasswordInvalidError(ForbiddenError):
    code = "DOCUMENT_PASSWORD_INVALID"
    default_message = "方案密码错误"


class LoginIpForbiddenError(ForbiddenError):
    code = "LOGIN_IP_FORBIDDEN"
    default_message = "当前IP不在该部门允许的登录IP范围内"


class ReauthRequiredError(ForbiddenError):
    """敏感操作缺少或未通过二次认证（重输登录密码）。"""

    code = "REAUTH_REQUIRED"
    default_message = "敏感操作需要二次认证，请重新输入登录密码"


class BackupRunningError(ConflictError):
    """已有备份任务运行中（引擎单任务互斥）。"""

    code = "BACKUP_RUNNING"
    default_message = "已有备份任务正在运行，请等待完成后再试"


class BackupConfigInvalidError(DmsError):
    code = "BACKUP_CONFIG_INVALID"
    status_code = 400
    default_message = "备份配置无效"


class BackupTargetUnavailableError(DmsError):
    """备份目标不可达或不可写（网络/权限/路径问题）。"""

    code = "BACKUP_TARGET_UNAVAILABLE"
    status_code = 503
    default_message = "备份目标不可达或不可写"


class BackupToolMissingError(DmsError):
    """rsync 等外部工具缺失或不可执行。"""

    code = "BACKUP_TOOL_MISSING"
    status_code = 503
    default_message = "备份所需外部工具不可用"


class BackupFailedError(DmsError):
    code = "BACKUP_FAILED"
    status_code = 500
    default_message = "备份执行失败，请查看服务端日志"


class BackupNotFoundError(ResourceNotFoundError):
    code = "BACKUP_NOT_FOUND"
    default_message = "指定的备份不存在"


class MetricUnavailableError(DmsError):
    """资源监控采集能力不可用（psutil 缺失或采样器未启动）。"""

    code = "METRIC_UNAVAILABLE"
    status_code = 503
    default_message = "资源监控采集能力不可用"