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

backend/alembic/versions/20260709_01_add_audit_access_context.py

@@ -0,0 +1,46 @@
+"""add access context to audit logs
+
+Revision ID: 20260709_01
+Revises: 20260630_02
+Create Date: 2026-07-09 10:00:00.000000
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+
+revision: str = "20260709_01"
+down_revision: Union[str, None] = "20260630_02"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column("audit_logs", sa.Column("client_ip", sa.String(45), nullable=True))
+    op.add_column("audit_logs", sa.Column("user_agent", sa.String(500), nullable=True))
+    op.add_column("audit_logs", sa.Column("client_type", sa.String(16), nullable=True))
+    op.add_column("audit_logs", sa.Column("client_version", sa.String(32), nullable=True))
+    op.add_column("audit_logs", sa.Column("client_platform", sa.String(16), nullable=True))
+    op.add_column("audit_logs", sa.Column("build_channel", sa.String(16), nullable=True))
+    op.add_column("audit_logs", sa.Column("build_commit", sa.String(64), nullable=True))
+    op.create_index("ix_audit_logs_operator_created", "audit_logs", ["operator_id", "created_at"])
+    op.create_index("ix_audit_logs_client_ip_created", "audit_logs", ["client_ip", "created_at"])
+    op.create_index("ix_audit_logs_client_source_created", "audit_logs", ["client_type", "created_at"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_audit_logs_client_source_created", table_name="audit_logs")
+    op.drop_index("ix_audit_logs_client_ip_created", table_name="audit_logs")
+    op.drop_index("ix_audit_logs_operator_created", table_name="audit_logs")
+    for column in (
+        "build_commit",
+        "build_channel",
+        "client_platform",
+        "client_version",
+        "client_type",
+        "user_agent",
+        "client_ip",
+    ):
+        op.drop_column("audit_logs", column)

backend/alembic/versions/20260709_02_add_permission_access_context.py

@@ -0,0 +1,42 @@
+"""add access context to permission access logs
+
+Revision ID: 20260709_02
+Revises: 20260709_01
+Create Date: 2026-07-09 15:45:00.000000
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+
+revision: str = "20260709_02"
+down_revision: Union[str, None] = "20260709_01"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column("permission_access_logs", sa.Column("user_agent", sa.String(500), nullable=True))
+    op.add_column("permission_access_logs", sa.Column("client_type", sa.String(16), nullable=True))
+    op.add_column("permission_access_logs", sa.Column("client_version", sa.String(32), nullable=True))
+    op.add_column("permission_access_logs", sa.Column("client_platform", sa.String(16), nullable=True))
+    op.add_column("permission_access_logs", sa.Column("build_channel", sa.String(16), nullable=True))
+    op.add_column("permission_access_logs", sa.Column("build_commit", sa.String(64), nullable=True))
+    op.create_index("ix_perm_log_ip_created", "permission_access_logs", ["ip_address", "created_at"])
+    op.create_index("ix_perm_log_client_source_created", "permission_access_logs", ["client_type", "created_at"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_perm_log_client_source_created", table_name="permission_access_logs")
+    op.drop_index("ix_perm_log_ip_created", table_name="permission_access_logs")
+    for column in (
+        "build_commit",
+        "build_channel",
+        "client_platform",
+        "client_version",
+        "client_type",
+        "user_agent",
+    ):
+        op.drop_column("permission_access_logs", column)

backend/alembic/versions/20260709_03_add_permission_access_request_headers.py

@@ -0,0 +1,35 @@
+"""add request headers to permission access logs
+
+Revision ID: 20260709_03
+Revises: 20260709_02
+Create Date: 2026-07-09 16:58:00.000000
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+
+revision: str = "20260709_03"
+down_revision: Union[str, None] = "20260709_02"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+REQUEST_HEADERS_TYPE = sa.JSON().with_variant(
+    postgresql.JSONB(astext_type=sa.Text()),
+    "postgresql",
+)
+
+
+def upgrade() -> None:
+    op.add_column(
+        "permission_access_logs",
+        sa.Column("request_headers", REQUEST_HEADERS_TYPE, nullable=True),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("permission_access_logs", "request_headers")

backend/alembic/versions/20260709_04_add_security_access_request_headers.py

@@ -0,0 +1,35 @@
+"""add request headers to security access logs
+
+Revision ID: 20260709_04
+Revises: 20260709_03
+Create Date: 2026-07-09 17:30:00.000000
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+
+revision: str = "20260709_04"
+down_revision: Union[str, None] = "20260709_03"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+REQUEST_HEADERS_TYPE = sa.JSON().with_variant(
+    postgresql.JSONB(astext_type=sa.Text()),
+    "postgresql",
+)
+
+
+def upgrade() -> None:
+    op.add_column(
+        "security_access_logs",
+        sa.Column("request_headers", REQUEST_HEADERS_TYPE, nullable=True),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("security_access_logs", "request_headers")

backend/alembic/versions/20260709_05_add_request_snapshots_to_access_logs.py

@@ -0,0 +1,40 @@
+"""add request snapshots to access logs
+
+Revision ID: 20260709_05
+Revises: 20260709_04
+Create Date: 2026-07-09 18:00:00.000000
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+
+revision: str = "20260709_05"
+down_revision: Union[str, None] = "20260709_04"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+REQUEST_SNAPSHOT_TYPE = sa.JSON().with_variant(
+    postgresql.JSONB(astext_type=sa.Text()),
+    "postgresql",
+)
+
+
+def upgrade() -> None:
+    op.add_column(
+        "permission_access_logs",
+        sa.Column("request_snapshot", REQUEST_SNAPSHOT_TYPE, nullable=True),
+    )
+    op.add_column(
+        "security_access_logs",
+        sa.Column("request_snapshot", REQUEST_SNAPSHOT_TYPE, nullable=True),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("security_access_logs", "request_snapshot")
+    op.drop_column("permission_access_logs", "request_snapshot")

backend/alembic/versions/20260710_01_add_monitoring_event_identity.py

@@ -0,0 +1,67 @@
+"""add monitoring event identity and persisted security classification
+
+Revision ID: 20260710_01
+Revises: 20260709_05
+Create Date: 2026-07-10 09:30:00.000000
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+
+revision: str = "20260710_01"
+down_revision: Union[str, None] = "20260709_05"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column("permission_access_logs", sa.Column("request_id", sa.String(36), nullable=True))
+    op.add_column("security_access_logs", sa.Column("request_id", sa.String(36), nullable=True))
+    op.add_column("security_access_logs", sa.Column("category", sa.String(30), nullable=True))
+    op.add_column("security_access_logs", sa.Column("severity", sa.String(16), nullable=True))
+
+    op.create_index("ix_perm_log_request_id", "permission_access_logs", ["request_id"])
+    op.create_index("ix_security_log_request_id", "security_access_logs", ["request_id"])
+    op.create_index("ix_security_log_category_created", "security_access_logs", ["category", "created_at"])
+    op.create_index("ix_security_log_severity_created", "security_access_logs", ["severity", "created_at"])
+
+    op.execute(
+        """
+        UPDATE security_access_logs
+        SET category = CASE
+                WHEN lower(path) LIKE '%/.env%' OR lower(path) LIKE '%.git%'
+                    OR lower(path) LIKE '%backup%' OR lower(path) LIKE '%config.php%'
+                    OR lower(path) LIKE '%wp-config%' OR lower(path) LIKE '%database.yml%'
+                    THEN 'PROBE'
+                WHEN status_code >= 500 THEN 'SERVER_ERROR'
+                WHEN auth_status = 'INVALID_TOKEN' THEN 'INVALID_TOKEN'
+                WHEN auth_status = 'ANONYMOUS' AND status_code IN (401, 403) THEN 'ANONYMOUS_API'
+                WHEN status_code = 404 THEN 'NOT_FOUND_NOISE'
+                ELSE 'OTHER'
+            END,
+            severity = CASE
+                WHEN lower(path) LIKE '%/.env%' OR lower(path) LIKE '%.git%'
+                    OR lower(path) LIKE '%backup%' OR lower(path) LIKE '%config.php%'
+                    OR lower(path) LIKE '%wp-config%' OR lower(path) LIKE '%database.yml%'
+                    THEN 'CRITICAL'
+                WHEN status_code >= 500 THEN 'HIGH'
+                WHEN auth_status = 'INVALID_TOKEN' THEN 'MEDIUM'
+                WHEN auth_status = 'ANONYMOUS' AND status_code IN (401, 403) THEN 'MEDIUM'
+                ELSE 'LOW'
+            END
+        """
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("ix_security_log_severity_created", table_name="security_access_logs")
+    op.drop_index("ix_security_log_category_created", table_name="security_access_logs")
+    op.drop_index("ix_security_log_request_id", table_name="security_access_logs")
+    op.drop_index("ix_perm_log_request_id", table_name="permission_access_logs")
+    op.drop_column("security_access_logs", "severity")
+    op.drop_column("security_access_logs", "category")
+    op.drop_column("security_access_logs", "request_id")
+    op.drop_column("permission_access_logs", "request_id")

backend/alembic/versions/20260710_02_add_source_location_snapshots.py

@@ -0,0 +1,93 @@
+"""add source location hourly snapshots
+
+Revision ID: 20260710_02
+Revises: 20260710_01
+Create Date: 2026-07-10 15:30:00.000000
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+
+revision: str = "20260710_02"
+down_revision: Union[str, None] = "20260710_01"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "source_location_snapshots",
+        sa.Column("id", sa.Uuid(), nullable=False),
+        sa.Column("bucket_time", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("ip_hash", sa.String(length=64), nullable=False),
+        sa.Column("user_hash", sa.String(length=64), nullable=False, server_default=""),
+        sa.Column("country", sa.String(length=100), nullable=False, server_default=""),
+        sa.Column("country_code", sa.String(length=16), nullable=False, server_default=""),
+        sa.Column("province", sa.String(length=100), nullable=False, server_default=""),
+        sa.Column("region_code", sa.String(length=24), nullable=False, server_default=""),
+        sa.Column("city", sa.String(length=100), nullable=False, server_default=""),
+        sa.Column("isp", sa.String(length=160), nullable=False, server_default=""),
+        sa.Column("location", sa.String(length=320), nullable=False, server_default=""),
+        sa.Column("longitude", sa.Float(), nullable=True),
+        sa.Column("latitude", sa.Float(), nullable=True),
+        sa.Column("accuracy_level", sa.String(length=16), nullable=False, server_default="unknown"),
+        sa.Column("allowed_count", sa.Integer(), nullable=False, server_default="0"),
+        sa.Column("denied_count", sa.Integer(), nullable=False, server_default="0"),
+        sa.Column("security_event_count", sa.Integer(), nullable=False, server_default="0"),
+        sa.Column("high_risk_count", sa.Integer(), nullable=False, server_default="0"),
+        sa.Column("auth_failure_count", sa.Integer(), nullable=False, server_default="0"),
+        sa.Column("first_seen_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("last_seen_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint("bucket_time", "ip_hash", "user_hash", name="uq_source_location_bucket_identity"),
+    )
+    op.create_index("ix_source_location_bucket", "source_location_snapshots", ["bucket_time"])
+    op.create_index(
+        "ix_source_location_country_bucket",
+        "source_location_snapshots",
+        ["country_code", "bucket_time"],
+    )
+    op.create_index(
+        "ix_source_location_risk_bucket",
+        "source_location_snapshots",
+        ["high_risk_count", "bucket_time"],
+    )
+
+    op.execute(
+        """
+        UPDATE security_access_logs
+        SET category = CASE
+                WHEN lower(path) LIKE '%/.env%' OR lower(path) LIKE '%.git%'
+                    OR lower(path) LIKE '%backup%' OR lower(path) LIKE '%config.php%'
+                    OR lower(path) LIKE '%wp-config%' OR lower(path) LIKE '%database.yml%'
+                    THEN 'PROBE'
+                WHEN status_code >= 500 THEN 'SERVER_ERROR'
+                WHEN auth_status = 'INVALID_TOKEN' THEN 'INVALID_TOKEN'
+                WHEN auth_status = 'ANONYMOUS' AND status_code IN (401, 403) THEN 'ANONYMOUS_API'
+                WHEN status_code = 404 THEN 'NOT_FOUND_NOISE'
+                ELSE 'OTHER'
+            END,
+            severity = CASE
+                WHEN lower(path) LIKE '%/.env%' OR lower(path) LIKE '%.git%'
+                    OR lower(path) LIKE '%backup%' OR lower(path) LIKE '%config.php%'
+                    OR lower(path) LIKE '%wp-config%' OR lower(path) LIKE '%database.yml%'
+                    THEN 'CRITICAL'
+                WHEN status_code >= 500 THEN 'HIGH'
+                WHEN auth_status = 'INVALID_TOKEN' THEN 'MEDIUM'
+                WHEN auth_status = 'ANONYMOUS' AND status_code IN (401, 403) THEN 'MEDIUM'
+                ELSE 'LOW'
+            END
+        WHERE category = 'ABNORMAL_IP'
+        """
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("ix_source_location_risk_bucket", table_name="source_location_snapshots")
+    op.drop_index("ix_source_location_country_bucket", table_name="source_location_snapshots")
+    op.drop_index("ix_source_location_bucket", table_name="source_location_snapshots")
+    op.drop_table("source_location_snapshots")

backend/alembic/versions/20260710_03_remove_private_source_snapshot_coordinates.py

@@ -0,0 +1,30 @@
+"""Remove deployment-specific coordinates from private source snapshots.
+
+Revision ID: 20260710_03
+Revises: 20260710_02
+"""
+
+from alembic import op
+
+
+revision = "20260710_03"
+down_revision = "20260710_02"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.execute(
+        """
+        UPDATE source_location_snapshots
+        SET longitude = NULL,
+            latitude = NULL
+        WHERE accuracy_level = 'private'
+        """
+    )
+
+
+def downgrade() -> None:
+    # The previous coordinates were a hardcoded deployment assumption and
+    # cannot be restored without reintroducing incorrect data.
+    pass

backend/alembic/versions/20260710_04_add_user_login_sessions.py

@@ -0,0 +1,40 @@
+"""Add user login session activity records.
+
+Revision ID: 20260710_04
+Revises: 20260710_03
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+
+revision = "20260710_04"
+down_revision = "20260710_03"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "user_login_sessions",
+        sa.Column("id", sa.Uuid(), nullable=False),
+        sa.Column("user_id", sa.Uuid(), nullable=False),
+        sa.Column("client_type", sa.String(length=16), nullable=False, server_default="web"),
+        sa.Column("client_platform", sa.String(length=32), nullable=True),
+        sa.Column("client_version", sa.String(length=64), nullable=True),
+        sa.Column("client_source", sa.String(length=32), nullable=True),
+        sa.Column("login_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.text("CURRENT_TIMESTAMP")),
+        sa.Column("last_seen_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.text("CURRENT_TIMESTAMP")),
+        sa.Column("ended_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("end_reason", sa.String(length=32), nullable=True),
+        sa.ForeignKeyConstraint(["user_id"], ["users.id"], ondelete="CASCADE"),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index("ix_user_login_sessions_user_login", "user_login_sessions", ["user_id", "login_at"])
+    op.create_index("ix_user_login_sessions_last_seen", "user_login_sessions", ["last_seen_at"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_user_login_sessions_last_seen", table_name="user_login_sessions")
+    op.drop_index("ix_user_login_sessions_user_login", table_name="user_login_sessions")
+    op.drop_table("user_login_sessions")

backend/alembic/versions/20260713_01_add_login_session_ip.py

@@ -0,0 +1,25 @@
+"""Add the server-observed login IP to user login sessions.
+
+Revision ID: 20260713_01
+Revises: 20260710_04
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+
+revision = "20260713_01"
+down_revision = "20260710_04"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "user_login_sessions",
+        sa.Column("login_ip", sa.String(length=45), nullable=True),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("user_login_sessions", "login_ip")

backend/alembic/versions/20260713_02_add_document_version_original_filename.py

@@ -0,0 +1,25 @@
+"""Store original filenames for document versions.
+
+Revision ID: 20260713_02
+Revises: 20260713_01
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+
+revision = "20260713_02"
+down_revision = "20260713_01"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "document_versions",
+        sa.Column("original_filename", sa.String(length=255), nullable=True),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("document_versions", "original_filename")

backend/alembic/versions/20260714_01_add_collaboration_module.py

@@ -0,0 +1,136 @@
+"""Add the independent shared-library collaboration module.
+
+Revision ID: 20260714_01
+Revises: 20260713_02
+"""
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+
+revision = "20260714_01"
+down_revision = "20260713_02"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    uuid_type = postgresql.UUID(as_uuid=True)
+    op.create_table(
+        "collaboration_folders",
+        sa.Column("id", uuid_type, primary_key=True),
+        sa.Column("study_id", uuid_type, sa.ForeignKey("studies.id"), nullable=False),
+        sa.Column("parent_id", uuid_type, sa.ForeignKey("collaboration_folders.id", ondelete="SET NULL")),
+        sa.Column("name", sa.String(120), nullable=False),
+        sa.Column("sort_order", sa.Integer(), nullable=False, server_default="0"),
+        sa.Column("created_by", uuid_type, sa.ForeignKey("users.id"), nullable=False),
+        sa.Column("deleted_at", sa.DateTime(timezone=True)),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.func.now()),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.func.now()),
+    )
+    op.create_index("ix_collaboration_folders_study_parent", "collaboration_folders", ["study_id", "parent_id"])
+
+    op.create_table(
+        "collaboration_files",
+        sa.Column("id", uuid_type, primary_key=True),
+        sa.Column("study_id", uuid_type, sa.ForeignKey("studies.id"), nullable=False),
+        sa.Column("folder_id", uuid_type, sa.ForeignKey("collaboration_folders.id", ondelete="SET NULL")),
+        sa.Column("title", sa.String(255), nullable=False),
+        sa.Column("file_type", sa.String(16), nullable=False),
+        sa.Column("extension", sa.String(16), nullable=False),
+        sa.Column("status", sa.String(20), nullable=False, server_default="ACTIVE"),
+        sa.Column("owner_id", uuid_type, sa.ForeignKey("users.id"), nullable=False),
+        sa.Column("current_revision_id", uuid_type),
+        sa.Column("generation", sa.Integer(), nullable=False, server_default="1"),
+        sa.Column("deleted_at", sa.DateTime(timezone=True)),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.func.now()),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.func.now()),
+    )
+    op.create_index("ix_collaboration_files_study_folder", "collaboration_files", ["study_id", "folder_id"])
+    op.create_index("ix_collaboration_files_study_status", "collaboration_files", ["study_id", "status"])
+
+    op.create_table(
+        "collaboration_members",
+        sa.Column("id", uuid_type, primary_key=True),
+        sa.Column("file_id", uuid_type, sa.ForeignKey("collaboration_files.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("user_id", uuid_type, sa.ForeignKey("users.id"), nullable=False),
+        sa.Column("role", sa.String(16), nullable=False),
+        sa.Column("invited_by", uuid_type, sa.ForeignKey("users.id"), nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.func.now()),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.func.now()),
+        sa.UniqueConstraint("file_id", "user_id", name="uq_collaboration_member_file_user"),
+    )
+    op.create_index("ix_collaboration_members_user", "collaboration_members", ["user_id"])
+
+    op.create_table(
+        "collaboration_revisions",
+        sa.Column("id", uuid_type, primary_key=True),
+        sa.Column("file_id", uuid_type, sa.ForeignKey("collaboration_files.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("revision_no", sa.Integer(), nullable=False),
+        sa.Column("parent_revision_id", uuid_type, sa.ForeignKey("collaboration_revisions.id", ondelete="SET NULL")),
+        sa.Column("file_uri", sa.String(500), nullable=False),
+        sa.Column("original_filename", sa.String(255), nullable=False),
+        sa.Column("file_hash", sa.String(128), nullable=False),
+        sa.Column("file_size", sa.BigInteger(), nullable=False),
+        sa.Column("mime_type", sa.String(100), nullable=False),
+        sa.Column("source", sa.String(24), nullable=False),
+        sa.Column("change_summary", sa.Text()),
+        sa.Column("created_by", uuid_type, sa.ForeignKey("users.id")),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.func.now()),
+        sa.UniqueConstraint("file_id", "revision_no", name="uq_collaboration_revision_file_no"),
+    )
+    op.create_index("ix_collaboration_revisions_file_created", "collaboration_revisions", ["file_id", "created_at"])
+    op.create_foreign_key(
+        "fk_collaboration_files_current_revision",
+        "collaboration_files",
+        "collaboration_revisions",
+        ["current_revision_id"],
+        ["id"],
+        ondelete="SET NULL",
+    )
+
+    op.create_table(
+        "collaboration_sessions",
+        sa.Column("id", uuid_type, primary_key=True),
+        sa.Column("file_id", uuid_type, sa.ForeignKey("collaboration_files.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("base_revision_id", uuid_type, sa.ForeignKey("collaboration_revisions.id"), nullable=False),
+        sa.Column("document_key", sa.String(128), nullable=False),
+        sa.Column("generation", sa.Integer(), nullable=False),
+        sa.Column("status", sa.String(20), nullable=False, server_default="ACTIVE"),
+        sa.Column("started_by", uuid_type, sa.ForeignKey("users.id"), nullable=False),
+        sa.Column("active_users", sa.Text()),
+        sa.Column("last_callback_at", sa.DateTime(timezone=True)),
+        sa.Column("closed_at", sa.DateTime(timezone=True)),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.func.now()),
+        sa.UniqueConstraint("document_key", name="uq_collaboration_session_document_key"),
+    )
+    op.create_index("ix_collaboration_sessions_file_status", "collaboration_sessions", ["file_id", "status"])
+
+    op.create_table(
+        "collaboration_callback_receipts",
+        sa.Column("id", uuid_type, primary_key=True),
+        sa.Column("session_id", uuid_type, sa.ForeignKey("collaboration_sessions.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("fingerprint", sa.String(128), nullable=False),
+        sa.Column("callback_status", sa.Integer(), nullable=False),
+        sa.Column("result", sa.String(24), nullable=False),
+        sa.Column("revision_id", uuid_type, sa.ForeignKey("collaboration_revisions.id", ondelete="SET NULL")),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.func.now()),
+        sa.UniqueConstraint("session_id", "fingerprint", name="uq_collaboration_callback_session_fingerprint"),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("collaboration_callback_receipts")
+    op.drop_index("ix_collaboration_sessions_file_status", table_name="collaboration_sessions")
+    op.drop_table("collaboration_sessions")
+    op.drop_constraint("fk_collaboration_files_current_revision", "collaboration_files", type_="foreignkey")
+    op.drop_index("ix_collaboration_revisions_file_created", table_name="collaboration_revisions")
+    op.drop_table("collaboration_revisions")
+    op.drop_index("ix_collaboration_members_user", table_name="collaboration_members")
+    op.drop_table("collaboration_members")
+    op.drop_index("ix_collaboration_files_study_status", table_name="collaboration_files")
+    op.drop_index("ix_collaboration_files_study_folder", table_name="collaboration_files")
+    op.drop_table("collaboration_files")
+    op.drop_index("ix_collaboration_folders_study_parent", table_name="collaboration_folders")
+    op.drop_table("collaboration_folders")

backend/alembic/versions/20260715_01_add_collaboration_share_links.py

@@ -0,0 +1,53 @@
+"""Add protected public links for collaboration files.
+
+Revision ID: 20260715_01
+Revises: 20260714_01
+"""
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+
+revision = "20260715_01"
+down_revision = "20260714_01"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    uuid_type = postgresql.UUID(as_uuid=True)
+    op.create_table(
+        "collaboration_share_links",
+        sa.Column("id", uuid_type, primary_key=True),
+        sa.Column(
+            "file_id",
+            uuid_type,
+            sa.ForeignKey("collaboration_files.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column("enabled", sa.Boolean(), nullable=False, server_default=sa.false()),
+        sa.Column("access_mode", sa.String(12), nullable=False, server_default="VIEW"),
+        sa.Column("expiry_policy", sa.String(16), nullable=False, server_default="SEVEN_DAYS"),
+        sa.Column("expires_at", sa.DateTime(timezone=True)),
+        sa.Column("password_hash", sa.String(255)),
+        sa.Column("token_version", sa.Integer(), nullable=False, server_default="1"),
+        sa.Column("failed_attempts", sa.Integer(), nullable=False, server_default="0"),
+        sa.Column("last_failed_at", sa.DateTime(timezone=True)),
+        sa.Column("locked_until", sa.DateTime(timezone=True)),
+        sa.Column("created_by", uuid_type, sa.ForeignKey("users.id"), nullable=False),
+        sa.Column("updated_by", uuid_type, sa.ForeignKey("users.id"), nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.func.now()),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.func.now()),
+        sa.UniqueConstraint("file_id", name="uq_collaboration_share_link_file"),
+    )
+    op.create_index(
+        "ix_collaboration_share_links_enabled_expiry",
+        "collaboration_share_links",
+        ["enabled", "expires_at"],
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("ix_collaboration_share_links_enabled_expiry", table_name="collaboration_share_links")
+    op.drop_table("collaboration_share_links")

backend/alembic/versions/20260715_02_add_collaboration_share_export_permission.py

@@ -0,0 +1,25 @@
+"""Add effective export controls to collaboration share links.
+
+Revision ID: 20260715_02
+Revises: 20260715_01
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+
+revision = "20260715_02"
+down_revision = "20260715_01"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "collaboration_share_links",
+        sa.Column("allow_export", sa.Boolean(), nullable=False, server_default=sa.false()),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("collaboration_share_links", "allow_export")

backend/alembic/versions/20260715_03_add_collaboration_revision_deletion.py

@@ -0,0 +1,43 @@
+"""Add soft deletion metadata to collaboration revisions.
+
+Revision ID: 20260715_03
+Revises: 20260715_02
+"""
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+
+revision = "20260715_03"
+down_revision = "20260715_02"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "collaboration_revisions",
+        sa.Column("deleted_by", postgresql.UUID(as_uuid=True), nullable=True),
+    )
+    op.add_column(
+        "collaboration_revisions",
+        sa.Column("deleted_at", sa.DateTime(timezone=True), nullable=True),
+    )
+    op.create_foreign_key(
+        "fk_collaboration_revision_deleted_by",
+        "collaboration_revisions",
+        "users",
+        ["deleted_by"],
+        ["id"],
+    )
+
+
+def downgrade() -> None:
+    op.drop_constraint(
+        "fk_collaboration_revision_deleted_by",
+        "collaboration_revisions",
+        type_="foreignkey",
+    )
+    op.drop_column("collaboration_revisions", "deleted_at")
+    op.drop_column("collaboration_revisions", "deleted_by")

backend/alembic/versions/20260715_04_add_collaboration_file_export_policy.py

@@ -0,0 +1,35 @@
+"""Move collaboration export control to the file.
+
+Revision ID: 20260715_04
+Revises: 20260715_03
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+
+revision = "20260715_04"
+down_revision = "20260715_03"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "collaboration_files",
+        sa.Column("allow_export", sa.Boolean(), nullable=False, server_default=sa.false()),
+    )
+    # Preserve links that already granted export: after consolidation the same
+    # setting applies to authenticated collaborators and anonymous visitors.
+    op.execute(
+        """
+        UPDATE collaboration_files AS file
+        SET allow_export = true
+        FROM collaboration_share_links AS link
+        WHERE link.file_id = file.id AND link.allow_export = true
+        """
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("collaboration_files", "allow_export")

backend/alembic/versions/20260715_05_remove_share_link_export_permission.py

@@ -0,0 +1,33 @@
+"""Remove the redundant share-link export permission.
+
+Revision ID: 20260715_05
+Revises: 20260715_04
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+
+revision = "20260715_05"
+down_revision = "20260715_04"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.drop_column("collaboration_share_links", "allow_export")
+
+
+def downgrade() -> None:
+    op.add_column(
+        "collaboration_share_links",
+        sa.Column("allow_export", sa.Boolean(), nullable=False, server_default=sa.false()),
+    )
+    op.execute(
+        """
+        UPDATE collaboration_share_links AS link
+        SET allow_export = file.allow_export
+        FROM collaboration_files AS file
+        WHERE file.id = link.file_id
+        """
+    )

backend/alembic/versions/20260715_06_add_collaboration_access_controls.py

@@ -0,0 +1,66 @@
+"""Add collaboration edit requests and ownership controls.
+
+Revision ID: 20260715_06
+Revises: 20260715_05
+"""
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+
+revision = "20260715_06"
+down_revision = "20260715_05"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "collaboration_files",
+        sa.Column("allow_edit_request", sa.Boolean(), nullable=False, server_default=sa.false()),
+    )
+    op.add_column(
+        "collaboration_files",
+        sa.Column("allow_sheet_structure_edit", sa.Boolean(), nullable=False, server_default=sa.true()),
+    )
+    op.add_column(
+        "collaboration_files",
+        sa.Column("sheet_structure_protection_backup", sa.Text(), nullable=True),
+    )
+    op.create_table(
+        "collaboration_edit_requests",
+        sa.Column("id", postgresql.UUID(as_uuid=True), nullable=False),
+        sa.Column("file_id", postgresql.UUID(as_uuid=True), nullable=False),
+        sa.Column("requester_id", postgresql.UUID(as_uuid=True), nullable=False),
+        sa.Column("status", sa.String(length=16), nullable=False, server_default="PENDING"),
+        sa.Column("resolved_by", postgresql.UUID(as_uuid=True), nullable=True),
+        sa.Column("resolved_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.func.now()),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.func.now()),
+        sa.ForeignKeyConstraint(["file_id"], ["collaboration_files.id"], ondelete="CASCADE"),
+        sa.ForeignKeyConstraint(["requester_id"], ["users.id"]),
+        sa.ForeignKeyConstraint(["resolved_by"], ["users.id"]),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(
+        "ix_collaboration_edit_requests_file_status",
+        "collaboration_edit_requests",
+        ["file_id", "status"],
+    )
+    op.create_index(
+        "uq_collaboration_edit_requests_pending_user",
+        "collaboration_edit_requests",
+        ["file_id", "requester_id"],
+        unique=True,
+        postgresql_where=sa.text("status = 'PENDING'"),
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("uq_collaboration_edit_requests_pending_user", table_name="collaboration_edit_requests")
+    op.drop_index("ix_collaboration_edit_requests_file_status", table_name="collaboration_edit_requests")
+    op.drop_table("collaboration_edit_requests")
+    op.drop_column("collaboration_files", "sheet_structure_protection_backup")
+    op.drop_column("collaboration_files", "allow_sheet_structure_edit")
+    op.drop_column("collaboration_files", "allow_edit_request")

backend/alembic/versions/20260716_01_add_generic_notifications.py

@@ -0,0 +1,53 @@
+"""Add recipient-scoped generic notifications.
+
+Revision ID: 20260716_01
+Revises: 20260715_06
+"""
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+
+revision = "20260716_01"
+down_revision = "20260715_06"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "notifications",
+        sa.Column("id", postgresql.UUID(as_uuid=True), nullable=False),
+        sa.Column("study_id", postgresql.UUID(as_uuid=True), nullable=False),
+        sa.Column("recipient_id", postgresql.UUID(as_uuid=True), nullable=False),
+        sa.Column("category", sa.String(length=64), nullable=False),
+        sa.Column("priority", sa.String(length=16), nullable=False, server_default="NORMAL"),
+        sa.Column("title", sa.String(length=180), nullable=False),
+        sa.Column("message", sa.String(length=500), nullable=False),
+        sa.Column("action_path", sa.Text(), nullable=True),
+        sa.Column("source_type", sa.String(length=64), nullable=False),
+        sa.Column("source_id", sa.String(length=100), nullable=False),
+        sa.Column("source_version", sa.String(length=100), nullable=True),
+        sa.Column("dedupe_key", sa.String(length=255), nullable=False),
+        sa.Column("read_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("resolved_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.func.now()),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.func.now()),
+        sa.ForeignKeyConstraint(["recipient_id"], ["users.id"], ondelete="CASCADE"),
+        sa.ForeignKeyConstraint(["study_id"], ["studies.id"], ondelete="CASCADE"),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint("recipient_id", "dedupe_key", name="uq_notifications_recipient_dedupe"),
+    )
+    op.create_index(
+        "ix_notifications_recipient_study_state",
+        "notifications",
+        ["recipient_id", "study_id", "resolved_at", "read_at", "created_at"],
+    )
+    op.create_index("ix_notifications_source", "notifications", ["source_type", "source_id"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_notifications_source", table_name="notifications")
+    op.drop_index("ix_notifications_recipient_study_state", table_name="notifications")
+    op.drop_table("notifications")

backend/alembic/versions/20260716_02_backfill_pending_edit_request_notifications.py

@@ -0,0 +1,75 @@
+"""Backfill notifications for pending collaboration edit requests.
+
+Revision ID: 20260716_02
+Revises: 20260716_01
+"""
+
+from alembic import op
+
+
+revision = "20260716_02"
+down_revision = "20260716_01"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.execute("""
+        INSERT INTO notifications (
+            id,
+            study_id,
+            recipient_id,
+            category,
+            priority,
+            title,
+            message,
+            action_path,
+            source_type,
+            source_id,
+            dedupe_key,
+            created_at,
+            updated_at
+        )
+        SELECT
+            gen_random_uuid(),
+            collaboration_files.study_id,
+            study_members.user_id,
+            'COLLABORATION_EDIT_REQUEST',
+            'NORMAL',
+            '新的编辑权限申请',
+            concat(
+                coalesce(nullif(users.full_name, ''), users.email, '项目成员'),
+                ' 申请编辑“',
+                collaboration_files.title,
+                '”'
+            ),
+            concat('/knowledge/collaboration?editRequestFile=', collaboration_files.id::text),
+            'COLLABORATION_EDIT_REQUEST',
+            collaboration_edit_requests.id::text,
+            concat('collaboration-edit-request:', collaboration_edit_requests.id::text),
+            collaboration_edit_requests.created_at,
+            collaboration_edit_requests.updated_at
+        FROM collaboration_edit_requests
+        JOIN collaboration_files
+          ON collaboration_files.id = collaboration_edit_requests.file_id
+        JOIN users
+          ON users.id = collaboration_edit_requests.requester_id
+        JOIN study_members
+          ON study_members.study_id = collaboration_files.study_id
+         AND study_members.is_active IS TRUE
+        LEFT JOIN collaboration_members
+          ON collaboration_members.file_id = collaboration_files.id
+         AND collaboration_members.user_id = study_members.user_id
+        WHERE collaboration_edit_requests.status = 'PENDING'
+          AND collaboration_files.deleted_at IS NULL
+          AND (
+              study_members.user_id = collaboration_files.owner_id
+              OR collaboration_members.role = 'MANAGER'
+          )
+        ON CONFLICT (recipient_id, dedupe_key) DO NOTHING
+    """)
+
+
+def downgrade() -> None:
+    # 这是业务通知数据迁移；降级时保留已读/未读状态，避免删除升级后新产生的同源通知。
+    pass

backend/alembic/versions/20260716_03_backfill_pending_edit_request_owners.py

@@ -0,0 +1,65 @@
+"""Backfill pending edit request notifications for file owners.
+
+Revision ID: 20260716_03
+Revises: 20260716_02
+"""
+
+from alembic import op
+
+
+revision = "20260716_03"
+down_revision = "20260716_02"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.execute("""
+        INSERT INTO notifications (
+            id,
+            study_id,
+            recipient_id,
+            category,
+            priority,
+            title,
+            message,
+            action_path,
+            source_type,
+            source_id,
+            dedupe_key,
+            created_at,
+            updated_at
+        )
+        SELECT
+            gen_random_uuid(),
+            collaboration_files.study_id,
+            collaboration_files.owner_id,
+            'COLLABORATION_EDIT_REQUEST',
+            'NORMAL',
+            '新的编辑权限申请',
+            concat(
+                coalesce(nullif(users.full_name, ''), users.email, '项目成员'),
+                ' 申请编辑“',
+                collaboration_files.title,
+                '”'
+            ),
+            concat('/knowledge/collaboration?editRequestFile=', collaboration_files.id::text),
+            'COLLABORATION_EDIT_REQUEST',
+            collaboration_edit_requests.id::text,
+            concat('collaboration-edit-request:', collaboration_edit_requests.id::text),
+            collaboration_edit_requests.created_at,
+            collaboration_edit_requests.updated_at
+        FROM collaboration_edit_requests
+        JOIN collaboration_files
+          ON collaboration_files.id = collaboration_edit_requests.file_id
+        JOIN users
+          ON users.id = collaboration_edit_requests.requester_id
+        WHERE collaboration_edit_requests.status = 'PENDING'
+          AND collaboration_files.deleted_at IS NULL
+        ON CONFLICT (recipient_id, dedupe_key) DO NOTHING
+    """)
+
+
+def downgrade() -> None:
+    # 与上一数据迁移一致，降级时保留已产生的业务通知状态。
+    pass

backend/alembic/versions/20260716_04_remove_shared_library_audits.py

@@ -0,0 +1,35 @@
+"""Remove shared-library and passive Office preview audit noise.
+
+Revision ID: 20260716_04
+Revises: 20260716_03
+"""
+
+from alembic import op
+
+
+revision = "20260716_04"
+down_revision = "20260716_03"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.execute("""
+        DELETE FROM audit_logs
+        WHERE action = 'OFFICE_PREVIEW_OPEN'
+           OR lower(entity_type) IN (
+               'faq_category',
+               'faq_item',
+               'faq_reply',
+               'faq_replies',
+               'precaution',
+               'knowledge_note',
+               'knowledge_notes',
+               'collaboration_file'
+           )
+    """)
+
+
+def downgrade() -> None:
+    # 被清理的是明确排除出审计范围的共享库和被动预览记录，无法也不应伪造恢复。
+    pass

backend/alembic/versions/20260716_05_expand_generic_notifications.py

@@ -0,0 +1,63 @@
+"""Expand generic notifications and route desktop delivery through them.
+
+Revision ID: 20260716_05
+Revises: 20260716_04
+"""
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+
+revision = "20260716_05"
+down_revision = "20260716_04"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "notifications",
+        sa.Column("requires_action", sa.Boolean(), nullable=False, server_default=sa.true()),
+    )
+    op.add_column(
+        "notifications",
+        sa.Column("due_at", sa.DateTime(timezone=True), nullable=True),
+    )
+    op.alter_column("desktop_notification_deliveries", "distribution_id", nullable=True)
+    op.add_column(
+        "desktop_notification_deliveries",
+        sa.Column("notification_id", postgresql.UUID(as_uuid=True), nullable=True),
+    )
+    op.create_foreign_key(
+        "fk_desktop_notification_deliveries_notification",
+        "desktop_notification_deliveries",
+        "notifications",
+        ["notification_id"],
+        ["id"],
+        ondelete="CASCADE",
+    )
+    op.create_unique_constraint(
+        "uq_desktop_notification_user_notification",
+        "desktop_notification_deliveries",
+        ["user_id", "notification_id"],
+    )
+
+
+def downgrade() -> None:
+    op.drop_constraint(
+        "uq_desktop_notification_user_notification",
+        "desktop_notification_deliveries",
+        type_="unique",
+    )
+    op.drop_constraint(
+        "fk_desktop_notification_deliveries_notification",
+        "desktop_notification_deliveries",
+        type_="foreignkey",
+    )
+    op.drop_column("desktop_notification_deliveries", "notification_id")
+    # Legacy rows always have a distribution id; rows created by the generic delivery path do not.
+    op.execute("DELETE FROM desktop_notification_deliveries WHERE distribution_id IS NULL")
+    op.alter_column("desktop_notification_deliveries", "distribution_id", nullable=False)
+    op.drop_column("notifications", "due_at")
+    op.drop_column("notifications", "requires_action")