release(main): 同步 dev 最新候选改动

backend/app/schemas/collaboration.py

@@ -0,0 +1,285 @@
+import uuid
+from datetime import datetime
+from typing import Literal, Optional
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+
+CollaborationFileType = Literal["word", "cell", "slide"]
+CollaborationMemberRole = Literal["EDITOR", "MANAGER"]
+CollaborationFileStatus = Literal["ACTIVE", "ARCHIVED", "DELETED"]
+CollaborationShareAccessMode = Literal["VIEW", "EDIT"]
+CollaborationShareExpiryPolicy = Literal["ONE_DAY", "SEVEN_DAYS", "THIRTY_DAYS", "PERMANENT"]
+CollaborationEditRequestStatus = Literal["PENDING", "APPROVED", "REJECTED"]
+
+
+class CollaborationFolderCreate(BaseModel):
+    name: str = Field(min_length=1, max_length=120)
+    parent_id: Optional[uuid.UUID] = None
+    sort_order: int = 0
+
+    @field_validator("name")
+    @classmethod
+    def normalize_name(cls, value: str) -> str:
+        value = value.strip()
+        if not value:
+            raise ValueError("文件夹名称不能为空")
+        return value
+
+
+class CollaborationFolderUpdate(BaseModel):
+    name: Optional[str] = Field(default=None, min_length=1, max_length=120)
+    parent_id: Optional[uuid.UUID] = None
+    sort_order: Optional[int] = None
+
+
+class CollaborationFolderRead(BaseModel):
+    id: uuid.UUID
+    study_id: uuid.UUID
+    parent_id: Optional[uuid.UUID]
+    name: str
+    sort_order: int
+    created_by: uuid.UUID
+    deleted_at: Optional[datetime]
+    created_at: datetime
+    updated_at: datetime
+
+    model_config = ConfigDict(from_attributes=True)
+
+
+class CollaborationFileCreate(BaseModel):
+    title: str = Field(min_length=1, max_length=240)
+    file_type: CollaborationFileType
+    folder_id: Optional[uuid.UUID] = None
+
+
+class CollaborationFileUpdate(BaseModel):
+    title: Optional[str] = Field(default=None, min_length=1, max_length=240)
+    folder_id: Optional[uuid.UUID] = None
+    status: Optional[Literal["ACTIVE", "ARCHIVED"]] = None
+    allow_export: Optional[bool] = None
+    allow_edit_request: Optional[bool] = None
+    allow_sheet_structure_edit: Optional[bool] = None
+
+
+class CollaborationRevisionRead(BaseModel):
+    id: uuid.UUID
+    file_id: uuid.UUID
+    revision_no: int
+    parent_revision_id: Optional[uuid.UUID]
+    original_filename: str
+    file_hash: str
+    file_size: int
+    mime_type: str
+    source: str
+    change_summary: Optional[str]
+    created_by: Optional[uuid.UUID]
+    created_by_name: Optional[str] = None
+    created_by_avatar_url: Optional[str] = None
+    created_at: datetime
+
+    model_config = ConfigDict(from_attributes=True)
+
+
+class CollaborationRevisionUpdate(BaseModel):
+    change_summary: str = Field(min_length=1, max_length=240)
+
+    @field_validator("change_summary")
+    @classmethod
+    def normalize_change_summary(cls, value: str) -> str:
+        value = value.strip()
+        if not value:
+            raise ValueError("版本名称不能为空")
+        return value
+
+
+class CollaborationRevisionCopyRequest(BaseModel):
+    title: str = Field(min_length=1, max_length=240)
+    folder_id: Optional[uuid.UUID] = None
+
+    @field_validator("title")
+    @classmethod
+    def normalize_title(cls, value: str) -> str:
+        value = value.strip()
+        if not value:
+            raise ValueError("文件名不能为空")
+        return value
+
+
+class CollaborationFileCollaboratorRead(BaseModel):
+    user_id: uuid.UUID
+    full_name: str
+    role: CollaborationMemberRole
+    avatar_url: Optional[str] = None
+
+
+class CollaborationFileRead(BaseModel):
+    id: uuid.UUID
+    study_id: uuid.UUID
+    folder_id: Optional[uuid.UUID]
+    title: str
+    file_type: CollaborationFileType
+    extension: str
+    status: CollaborationFileStatus
+    owner_id: uuid.UUID
+    current_revision_id: Optional[uuid.UUID]
+    generation: int
+    allow_export: bool = False
+    allow_edit_request: bool = False
+    allow_sheet_structure_edit: bool = True
+    deleted_at: Optional[datetime]
+    created_at: datetime
+    updated_at: datetime
+    owner_name: Optional[str] = None
+    folder_name: Optional[str] = None
+    current_revision_no: Optional[int] = None
+    current_revision_file_size: Optional[int] = None
+    current_revision_mime_type: Optional[str] = None
+    current_revision_created_at: Optional[datetime] = None
+    collaboration_role: Optional[CollaborationMemberRole] = None
+    collaborators: list[CollaborationFileCollaboratorRead] = Field(default_factory=list)
+    can_edit: bool = False
+    can_manage: bool = False
+    can_export: bool = False
+    can_request_edit: bool = False
+    edit_request_status: Optional[CollaborationEditRequestStatus] = None
+    can_transfer_ownership: bool = False
+
+    model_config = ConfigDict(from_attributes=True)
+
+
+class CollaborationMemberUpsert(BaseModel):
+    user_id: uuid.UUID
+    role: CollaborationMemberRole
+
+
+class CollaborationMemberRead(BaseModel):
+    id: uuid.UUID
+    file_id: uuid.UUID
+    user_id: uuid.UUID
+    role: CollaborationMemberRole
+    invited_by: uuid.UUID
+    full_name: str
+    email: str
+    created_at: datetime
+
+
+class CollaborationEditRequestRead(BaseModel):
+    id: uuid.UUID
+    file_id: uuid.UUID
+    requester_id: uuid.UUID
+    requester_name: str
+    requester_email: str
+    status: CollaborationEditRequestStatus
+    resolved_by: Optional[uuid.UUID]
+    resolved_at: Optional[datetime]
+    created_at: datetime
+
+
+class CollaborationEditRequestResolve(BaseModel):
+    status: Literal["APPROVED", "REJECTED"]
+
+
+class CollaborationOwnershipTransferRequest(BaseModel):
+    new_owner_id: uuid.UUID
+
+
+class CollaborationShareLinkUpdate(BaseModel):
+    enabled: bool
+    access_mode: CollaborationShareAccessMode = "VIEW"
+    expiry_policy: CollaborationShareExpiryPolicy = "SEVEN_DAYS"
+    password_mode: Literal["KEEP", "SET", "CLEAR"] = "KEEP"
+    password: Optional[str] = Field(default=None, min_length=4, max_length=64)
+
+    @model_validator(mode="after")
+    def validate_password_change(self):
+        if self.password_mode == "SET" and not self.password:
+            raise ValueError("设置链接密码时必须提供密码")
+        if self.password_mode != "SET" and self.password is not None:
+            raise ValueError("仅在设置链接密码时允许提交密码")
+        return self
+
+
+class CollaborationShareLinkRead(BaseModel):
+    id: uuid.UUID
+    file_id: uuid.UUID
+    enabled: bool
+    access_mode: CollaborationShareAccessMode
+    expiry_policy: CollaborationShareExpiryPolicy
+    expires_at: Optional[datetime]
+    has_password: bool
+    share_path: str = "/collaboration/share"
+    share_token: Optional[str] = None
+    created_at: datetime
+    updated_at: datetime
+
+
+class CollaborationPublicShareMetadata(BaseModel):
+    file_name: str
+    file_type: CollaborationFileType
+    access_mode: Literal["view", "edit"]
+    allow_export: bool
+    requires_password: bool
+    expires_at: Optional[datetime]
+
+
+class CollaborationSharePasswordRequest(BaseModel):
+    password: str = Field(min_length=1, max_length=64)
+
+
+class CollaborationShareAccessGrant(BaseModel):
+    access_token: str
+    expires_at: datetime
+
+
+class CollaborationPublicEditorConfigRequest(BaseModel):
+    access_token: Optional[str] = Field(default=None, max_length=2048)
+    client_id: str = Field(min_length=8, max_length=64, pattern=r"^[A-Za-z0-9_-]+$")
+    display_name: str = Field(default="链接访客", min_length=1, max_length=40)
+
+    @field_validator("display_name")
+    @classmethod
+    def normalize_display_name(cls, value: str) -> str:
+        return value.strip() or "链接访客"
+
+
+class CollaborationCandidateRead(BaseModel):
+    user_id: uuid.UUID
+    full_name: str
+    email: str
+    role_in_study: str
+    can_be_editor: bool
+    can_be_manager: bool
+
+
+class CollaborationEditorConfigRead(BaseModel):
+    file_id: uuid.UUID
+    file_name: str
+    access_mode: Literal["view", "edit"]
+    can_save_as: bool = False
+    can_download: bool = False
+    can_request_edit: bool = False
+    host_path: str = "/onlyoffice-host.html"
+    expires_at: datetime
+    config: dict
+
+
+class CollaborationExportRecord(BaseModel):
+    file_type: str = Field(min_length=1, max_length=16, pattern=r"^[a-z0-9]+$")
+
+
+class CollaborationCallbackPayload(BaseModel):
+    key: str
+    status: int
+    url: Optional[str] = None
+    changesurl: Optional[str] = None
+    filetype: Optional[str] = None
+    forcesavetype: Optional[int] = None
+    userdata: Optional[str] = None
+    users: list[str] = Field(default_factory=list)
+    actions: list[dict] = Field(default_factory=list)
+    history: Optional[dict] = None
+
+
+class CollaborationRestoreRequest(BaseModel):
+    change_summary: Optional[str] = Field(default=None, max_length=500)