feat(collaboration): 完善在线文档协作与通知闭环

- 新增协作文件夹、文件、不可变修订、成员、会话、回调回执、编辑申请与分享链接数据模型。

- 补齐新建、导入、复制、下载、回收站、恢复、成员授权、所有权转让及文件级权限接口。

- 接入 ONLYOFFICE 共同编辑、历史版本预览与恢复、修订另存副本、导出下载审计和幂等回调保存。

- 增加编辑权限申请、审批通知、项目提醒聚合、通知 Feed、已读处理及历史待办数据回填。

- 支持公开分享的查看或编辑模式、有效期、密码哈希、失败锁定、短时访问凭证与固定分享地址。

- 增加协作者导出、申请编辑、工作表结构保护和所有权管理策略，并纳入项目接口权限矩阵。

- 新增协作文件库、编辑工作区、公开分享页、下载与另存为对话框，以及导航、路由和权限入口。

- 统一网页端与桌面端通知布局，增加沉浸式工作区和浏览器、Tauri 双端全屏能力。

- 扩展运行时文件下载适配、Tauri 环境识别和原生全屏命令，继续保持业务代码运行时边界。

- 加固 ONLYOFFICE 消息桥的同源下载、签名地址隔离和保存为能力校验，并更新桌面发布检查。

- 增加连续数据库迁移、50MB 上传限制、OnlyOffice 中文文案与开发启动路由校验。

- 补充协作、通知、权限、路由、运行时、布局和 OnlyOffice 相关测试及模块说明文档。

frontend/src/views/OfficePreviewWorkspace.test.ts

@@ -12,6 +12,8 @@ describe("OfficePreviewWorkspace contract", () => {
     expect(source).not.toContain("downloadDocumentVersion");
     expect(source).not.toContain("downloadAttachment");
     expect(source).not.toContain("<iframe");
+    expect(source).toContain('route.name === "OfficeCollaborationRevisionPreview"');
+    expect(source).toContain("fetchCollaborationRevisionOnlyOfficeConfig");
   });
 
   it("destroys signed configuration on deactivation, server changes, and unmount", () => {

frontend/src/views/OfficePreviewWorkspace.vue

@@ -39,7 +39,11 @@ import { computed, inject, onActivated, onBeforeUnmount, onDeactivated, onMounte
 import { useRoute, useRouter } from "vue-router";
 import { Loading } from "@element-plus/icons-vue";
 import OnlyOfficeViewer from "../components/OnlyOfficeViewer.vue";
-import { fetchAttachmentOnlyOfficeConfig, fetchVersionOnlyOfficeConfig } from "../api/onlyoffice";
+import {
+  fetchAttachmentOnlyOfficeConfig,
+  fetchCollaborationRevisionOnlyOfficeConfig,
+  fetchVersionOnlyOfficeConfig,
+} from "../api/onlyoffice";
 import { useStudyStore } from "../store/study";
 import type { OnlyOfficePreviewConfig, OnlyOfficeResourceType } from "../types/onlyoffice";
 import { DESKTOP_SERVER_URL_CHANGED_EVENT, ONLYOFFICE_HOST_PATH } from "../runtime";
@@ -61,10 +65,13 @@ const requestSequence = ref(0);
 const viewerSequence = ref(0);
 let mounted = false;
 
-const resourceType = computed<OnlyOfficeResourceType>(() =>
-  route.name === "OfficeAttachmentPreview" ? "attachment" : "version",
-);
+const resourceType = computed<OnlyOfficeResourceType>(() => {
+  if (route.name === "OfficeAttachmentPreview") return "attachment";
+  if (route.name === "OfficeCollaborationRevisionPreview") return "collaboration_revision";
+  return "version";
+});
 const resourceId = computed(() => String(route.params.id || ""));
+const collaborationFileId = computed(() => String(route.params.fileId || ""));
 const displayFileName = computed(() => previewConfig.value?.file_name || String(route.meta.title || "Office 文件预览"));
 const viewerKey = computed(() => `${resourceType.value}:${resourceId.value}:${viewerSequence.value}`);
 const backActionLabel = computed(() => workspaceTaskController ? "关闭预览并返回" : "返回");
@@ -104,7 +111,13 @@ const loadConfig = async () => {
   try {
     const response = resourceType.value === "attachment"
       ? await fetchAttachmentOnlyOfficeConfig(resourceId.value)
-      : await fetchVersionOnlyOfficeConfig(resourceId.value);
+      : resourceType.value === "collaboration_revision"
+        ? await fetchCollaborationRevisionOnlyOfficeConfig(
+          study.currentStudy?.id || "",
+          collaborationFileId.value,
+          resourceId.value,
+        )
+        : await fetchVersionOnlyOfficeConfig(resourceId.value);
     if (sequence !== requestSequence.value) return;
     if (response.data.host_path !== ONLYOFFICE_HOST_PATH) {
       throw new Error("Office 预览宿主页配置不合法");

frontend/src/views/knowledge/CollaborationLibrary.test.ts

@@ -0,0 +1,332 @@
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+const source = readFileSync(resolve(__dirname, "./CollaborationLibrary.vue"), "utf8");
+
+describe("CollaborationLibrary UI contract", () => {
+  it("opens the create dialog directly from the primary sidebar action", () => {
+    expect(source).toContain(':icon="Plus" @click="openCreateDialog">新建</el-button>');
+    expect(source).toContain(':icon="Upload" :loading="importing"');
+    expect(source).not.toContain("新建协作文件⌄");
+  });
+
+  it("provides compact document-library views and file type filtering", () => {
+    expect(source).toContain("全部文件");
+    expect(source).toContain("最近更新");
+    expect(source).toContain("与我共享");
+    expect(source).toContain('v-model="fileTypeFilter"');
+    expect(source).toContain("currentViewTitle");
+  });
+
+  it("uses folder ellipsis actions on web and a context menu on desktop", () => {
+    expect(source).toContain('const isDesktop = isTauriRuntime();');
+    expect(source).toContain(":trigger=\"isDesktop ? 'contextmenu' : 'click'\"");
+    expect(source).toContain('v-if="!isDesktop && canManage');
+    expect(source).toContain('class="folder-more"');
+    expect(source).toContain('command="rename"');
+    expect(source).toContain('command="delete"');
+    expect(source).not.toContain('class="folder-actions"');
+  });
+
+  it("renames folders inline and keeps destructive deletion confirmed", () => {
+    expect(source).toContain(':data-folder-rename="folder.id"');
+    expect(source).toContain('@keydown.enter.stop.prevent="submitRenameFolder(folder)"');
+    expect(source).toContain('@keydown.esc.stop.prevent="cancelRenameFolder"');
+    expect(source).toContain('确认删除空文件夹“${folder.name}”');
+  });
+
+  it("renders action dialogs as a single desktop surface", () => {
+    expect(source.match(/class="collaboration-action-dialog(?:\s|\")/g)?.length).toBe(8);
+    expect(source).toContain("body.is-desktop-runtime .collaboration-action-dialog.el-dialog");
+    expect(source).toContain("--el-dialog-padding-primary: 0;");
+    expect(source).toContain("padding: 0 !important;");
+  });
+
+  it("offers the complete file action menu with explicit permission gates", () => {
+    for (const command of ["permissions", "rename", "copy", "move", "info", "history", "download", "trash"]) {
+      expect(source).toContain(`command: "${command}"`);
+    }
+    expect(source).toContain("item.can_export && canCreate.value");
+    expect(source).toContain("if (item.can_export) actions.push");
+    expect(source).toContain('label: "访问与权限"');
+    expect(source).not.toContain('command: "members"');
+    expect(source).not.toContain('command: "share"');
+    expect(source).not.toContain('command="manage"');
+  });
+
+  it("keeps rename and move as separate focused operations", () => {
+    expect(source).toContain('v-model="renameDialogVisible" title="重命名"');
+    expect(source).toContain('v-model="moveDialogVisible" title="移动到"');
+    expect(source).toContain("submitRenameFile");
+    expect(source).toContain("submitMoveFile");
+    expect(source).toContain("const targetFolderId = moveFolderId.value || null;");
+    expect(source).toContain("{ folder_id: targetFolderId }");
+  });
+
+  it("shows file metadata and downloads the current revision without a save picker", () => {
+    expect(source).toContain('v-model="infoDialogVisible" title="文件信息"');
+    expect(source).toContain("current_revision_file_size");
+    expect(source).toContain("current_revision_no");
+    expect(source).not.toContain('<el-table-column label="修订"');
+    expect(source).not.toContain('<el-descriptions-item label="当前版本"');
+    expect(source).not.toContain("R${");
+    expect(source).toContain("downloadCollaborationFile");
+    expect(source).toContain("downloadFileWithFeedback(");
+    expect(source).not.toContain("prepareSaveFile");
+  });
+
+  it("refreshes history immediately after restoring a revision", () => {
+    expect(source).toContain("const restoringRevisionId = ref<string | null>(null)");
+    expect(source).toContain(':loading="restoringRevisionId === row.id"');
+    expect(source).toContain("const { data: restored } = await restoreCollaborationRevision");
+    expect(source).toContain("current_revision_id: restoredForDisplay.id");
+    expect(source).toContain("...revisions.value.filter((item) => item.id !== restoredForDisplay.id)");
+    expect(source).toContain("const [revisionResponse] = await Promise.all([");
+    expect(source).toContain("if (refreshedFile) historyFile.value = refreshedFile");
+  });
+
+  it("loads fresh history on open and follows delayed ONLYOFFICE session callbacks", () => {
+    expect(source).toContain('@closed="closeHistory"');
+    expect(source).toContain("const historyRefreshTimers: number[] = []");
+    expect(source).toContain("scheduleHistoryRefresh();");
+    expect(source).toContain("refreshHistory({ silent: true })");
+    expect(source).toContain("const [revisionResponse, fileResponse] = await Promise.all([");
+    expect(source).toContain("fetchCollaborationFile(requireStudyId(), fileId)");
+    expect(source).toContain("historyFile.value = fileResponse.data");
+    expect(source).toContain("requestSequence !== historyRequestSequence");
+  });
+
+  it("presents version history as a date-grouped file timeline", () => {
+    expect(source).toContain('class="collaboration-action-dialog history-dialog"');
+    expect(source).toContain('width="840px"');
+    expect(source).toContain('modal-class="history-dialog-overlay"');
+    expect(source).toContain("history-file-badge");
+    expect(source).toContain("创建者：{{ historyFile.owner_name");
+    expect(source).toContain('v-model="historyOnlyDescribed"');
+    expect(source).toContain('v-model="historySourceFilter"');
+    expect(source).toContain('v-for="group in historyRevisionGroups"');
+    expect(source).toContain("revision.created_by_name");
+    expect(source).toContain(":src=\"row.created_by_avatar_url || undefined\"");
+    expect(source).toContain("当前版本");
+    expect(source).toContain("版本名称");
+    expect(source).not.toContain("<strong>R{{ row.revision_no }}</strong>");
+    expect(source).toContain("仅显示已命名版本");
+    expect(source).toContain("未命名");
+    expect(source).toContain(">命名</el-button>");
+    expect(source).toContain(">预览</el-button>");
+    expect(source).toContain(">另存为</el-button>");
+    expect(source).toContain("nameRevision(row)");
+    expect(source).toContain("previewRevision(row)");
+    expect(source).toContain("saveRevisionAs(row)");
+    expect(source).toContain('name: "OfficeCollaborationRevisionPreview"');
+    expect(source).toContain('window.open(previewRoute.href, "_blank", "noopener,noreferrer")');
+    expect(source).not.toContain("historyDialogVisible.value = false");
+    expect(source).toContain("copyCollaborationRevision");
+    expect(source).toContain("updateCollaborationRevision");
+    expect(source).toContain('v-model="revisionSaveAsDialogVisible"');
+    expect(source).toContain("<CollaborationSaveAsDialog");
+    expect(source).toContain(':initial-folder-id="revisionSaveAsFolderId"');
+    expect(source).toContain("submitRevisionSaveAs");
+    expect(source).toContain("folder_id: payload.folderId");
+    expect(source).toContain('`${stem}[${revisionSaveAsTimeLabel(revision.created_at)}]${suffix}`');
+    expect(source).toContain("︰${pad(date.getMinutes())}");
+    expect(source).not.toContain('PERMISSION_CHANGE: "权限设置"');
+    expect(source).toContain('command="delete"');
+    expect(source).toContain("删除版本");
+    expect(source).toContain('v-if="historyFile?.can_manage" command="delete"');
+    expect(source).toContain("deleteCollaborationRevision");
+    expect(source).toContain("revision.id === historyFile.value.current_revision_id");
+    expect(source).toContain("height: min(760px, 82vh)");
+    expect(source).toContain("min-height: 48px");
+    expect(source).toContain("body.is-desktop-runtime .history-dialog.el-dialog");
+    expect(source).toContain("margin: 0 auto !important;");
+    expect(source).not.toContain('<el-table :data="revisions"');
+  });
+
+  it("supports inviting several members inside unified access management", () => {
+    expect(source).toContain('v-model="accessDialogVisible"');
+    expect(source).toContain('<strong>{{ accessPanelTitle }}</strong>');
+    expect(source).toContain("openAccessManagement");
+    expect(source).toContain('@click="openMemberInvite"');
+    expect(source).toContain('class="access-section__manage-button"');
+    expect(source).toContain("<span>管理协作者</span>");
+    expect(source).toContain('class="access-member-identity"');
+    expect(source).toContain('class="access-member-role"');
+    expect(source).toContain('class="access-member-owner">所有者</span>');
+    expect(source).not.toContain('<el-table :data="members"');
+    expect(source).toContain('v-model="memberInviteDialogVisible"');
+    expect(source).toContain('title="管理协作者"');
+    expect(source).not.toContain('title="添加协作者"');
+    expect(source).toContain('placeholder="搜索姓名、账号或角色"');
+    expect(source).not.toContain('member-picker-group--recent');
+    expect(source).not.toContain('member-picker-recent-empty');
+    expect(source).not.toContain('最近选择的账号将显示在这里');
+    expect(source).toContain('role="listbox" aria-label="可添加的项目成员"');
+    expect(source).toContain("memberForm.user_ids.includes(candidate.user_id)");
+    expect(source).toContain("toggleMemberCandidate(candidate.user_id)");
+    expect(source).toContain("selectedMemberCandidates.length");
+    expect(source).toContain('aria-label="文件授权角色"');
+    expect(source).toContain('label="可编辑" value="EDITOR"');
+    expect(source).toContain('label="可管理" value="MANAGER"');
+    expect(source).toContain('class="member-picker-selection__footer"');
+    expect(source).toContain("Promise.allSettled(selectedUserIds.map");
+    expect(source).toContain("个账号，${failed.length} 个账号授权失败");
+    expect(source).toContain("closeAccessManagement");
+    expect(source).not.toContain("memberDialogVisible");
+    expect(source).not.toContain("shareDialogVisible");
+  });
+
+  it("opens permission settings as a returnable view in the same dialog", () => {
+    expect(source).toContain('const accessPanel = ref<"overview" | "permissions">("overview")');
+    expect(source).toContain('@click="openPermissionSettings"');
+    expect(source).toContain('aria-label="返回访问与权限"');
+    expect(source).toContain('@click="handleAccessPanelBack"');
+    expect(source).toContain("const handleAccessPanelBack = () =>");
+    expect(source).toContain('v-else-if="accessPanel === \'permissions\'" class="access-section access-section--common"');
+    expect(source).not.toContain("permissionDialogVisible");
+  });
+
+  it("implements edit requests, sheet structure control, and contact ownership transfer", () => {
+    expect(source).toContain("允许申请编辑权限");
+    expect(source).toContain("handleEditRequestPermissionChange");
+    expect(source).toContain("待处理申请");
+    expect(source).toContain("resolveCollaborationEditRequest");
+    expect(source).toContain("notifyProjectNotificationsChanged");
+    expect(source).toContain("route.query.editRequestFile");
+    expect(source).toContain("openEditRequestNotificationTarget");
+    expect(source).toContain('class="access-section__pending-count"');
+    expect(source).toContain('ref="editRequestSectionRef"');
+    expect(source).toContain("editRequestSectionRef.value?.focus");
+    const accountAuthorizationIndex = source.indexOf('class="access-section access-section--members"');
+    const pendingRequestIndex = source.indexOf('class="edit-request-list"');
+    const permissionSettingsIndex = source.indexOf("v-else-if=\"accessPanel === 'permissions'\"");
+    expect(pendingRequestIndex).toBeGreaterThan(accountAuthorizationIndex);
+    expect(pendingRequestIndex).toBeLessThan(permissionSettingsIndex);
+    expect(source).toContain("允许所有协作者添加、删除工作表");
+    expect(source).toContain("handleSheetStructurePermissionChange");
+    expect(source).toContain("转让文档所有权");
+    expect(source).toContain('v-model="transferDialogVisible"');
+    expect(source).toContain('title="请选择新的所有者"');
+    expect(source).toContain('class="ownership-transfer-layout"');
+    expect(source).toContain('role="listbox" aria-label="可转让联系人"');
+    expect(source).toContain('v-for="candidate in transferCandidates"');
+    expect(source).toContain('{{ candidate.role_in_study }}');
+    expect(source).toContain('{{ selectedTransferCandidate.role_in_study }}');
+    expect(source).toContain('currentOwnerCandidate?.role_in_study');
+    expect(source).toContain('class="collaboration-role-tag"');
+    expect(source).toContain('--el-tag-bg-color: color-mix(in srgb, var(--ctms-primary) 13%, var(--ctms-bg-muted))');
+    expect(source).toContain('v-if="selectedTransferCandidate"');
+    expect(source).toContain('description="暂未选择联系人"');
+    expect(source).toContain(':disabled="!selectedTransferCandidate"');
+    expect(source).toContain('>确定</el-button>');
+    expect(source).not.toContain('accessPanel === "transfer"');
+    expect(source).toContain("transferCollaborationOwnership");
+  });
+
+  it("saves permission switches silently while retaining failure feedback", () => {
+    expect(source).not.toContain('ElMessage.success("内容操作权限已更新")');
+    expect(source).not.toContain('ElMessage.success("编辑权限申请设置已更新")');
+    expect(source).not.toContain('ElMessage.success("工作表结构权限已更新")');
+    expect(source).toContain('getApiErrorMessage(error, "内容操作权限保存失败")');
+    expect(source).toContain('getApiErrorMessage(error, "编辑权限申请设置保存失败")');
+    expect(source).toContain('getApiErrorMessage(error, "工作表结构权限保存失败")');
+  });
+
+  it("configures real immutable link sharing with mutable access settings", () => {
+    expect(source).toContain('v-model="accessDialogVisible"');
+    expect(source).toContain("const openAccessManagement = async");
+    expect(source).toContain("accessFile.value.id");
+    expect(source).toContain('v-model="shareForm.enabled"');
+    expect(source).toContain('class="access-setting-status"');
+    expect(source).toContain('class="share-settings-list"');
+    expect(source).toContain('class="share-setting-row share-setting-row--password"');
+    expect(source).toContain('class="share-link-panel"');
+    expect(source).toContain('class="access-setting-navigation"');
+    expect(source).toContain("accessPermissionSummary");
+    expect(source).toContain('v-model="shareForm.access_mode"');
+    expect(source).toContain('v-model="commonExportEnabled"');
+    expect(source).toContain('@change="handleCommonExportChange"');
+    expect(source).toContain("{ allow_export: next }");
+    expect(source).not.toContain("shareForm.allow_export");
+    expect(source).toContain('v-model="shareForm.expiry_policy"');
+    for (const policy of ["ONE_DAY", "SEVEN_DAYS", "THIRTY_DAYS", "PERMANENT"]) {
+      expect(source).toContain(`value="${policy}"`);
+    }
+    expect(source).toContain('v-model="shareForm.password_enabled"');
+    expect(source).toContain("handleCommonExportChange");
+    expect(source).toContain("promptSharePassword");
+    expect(source).toContain('label="可查看" value="VIEW"');
+    expect(source).toContain('label="可编辑" value="EDIT"');
+    expect(source).not.toContain("获得链接的人可编辑");
+    expect(source).not.toContain("获得链接的人可查看");
+    expect(source).toContain("允许编辑者和匿名访问者下载、打印、另存和复制");
+    expect(source).not.toContain("系统内账号登录后按文件角色访问");
+    expect(source).not.toContain("无需 CTMS 账号，通过链接访问文件");
+    expect(source).not.toContain("同时约束账号授权和匿名访问");
+    expect(source).toContain('@change="persistShareSettings()"');
+    expect(source).not.toContain("保存链接设置");
+    expect(source).toContain("fetchCollaborationShareLink");
+    expect(source).toContain("updateCollaborationShareLink");
+    expect(source).not.toContain("regenerateCollaborationShareLink");
+    expect(source).not.toContain("重新生成链接");
+    expect(source).not.toContain("关闭后重新开启仍使用同一地址");
+    expect(source).not.toContain("匿名访问已关闭，之前复制的访问链接无法继续使用");
+    expect(source).not.toContain("share-link-disabled");
+    expect(source).not.toContain("修改后自动保存");
+    expect(source).not.toContain("通过链接邀请外部人员查看或协作编辑");
+    expect(source).not.toContain("邀请项目内成员并分配协作权限");
+    expect(source).toContain("copyShareUrl");
+    expect(source).not.toContain("链接分享暂未开放");
+  });
+
+  it("uses an edge-to-edge compact table with a single row action menu", () => {
+    expect(source).toContain('size="small"');
+    expect(source).toContain('label="操作" width="72"');
+    expect(source).toContain('popper-class="collaboration-row-actions-popper"');
+    expect(source).toContain('@command="handleFileAction($event, row)"');
+    expect(source).toContain(".collaboration-library__main { display: flex; min-width: 0; min-height: 0;");
+    expect(source).toContain("height: 100%;");
+    expect(source).toContain(".collaboration-table-wrap { min-height: 0; flex: 1; overflow: auto;");
+    expect(source).not.toContain('label="操作" width="300"');
+  });
+
+  it("opens the same action definitions from a desktop row context menu", () => {
+    expect(source).toContain('@row-contextmenu="openFileContextMenu"');
+    expect(source).toContain('v-if="isDesktop"');
+    expect(source).toContain('ref="fileContextMenuRef"');
+    expect(source).toContain("fileActions(fileContextMenuRow)");
+    expect(source).toContain("handleFileContextAction");
+    expect(source).toContain("event.preventDefault();");
+  });
+
+  it("keeps the fixed operation column background consistent with the table", () => {
+    expect(source).toContain(".el-table__header-wrapper .el-table-fixed-column--right");
+    expect(source).toContain("background: var(--unified-table-header-bg) !important;");
+    expect(source).not.toContain("background: var(--el-table-header-bg-color) !important;");
+    expect(source).toContain(".el-table__body tr:hover > .el-table-fixed-column--right");
+  });
+
+  it("uses shared theme tokens across the full collaboration canvas", () => {
+    expect(source).toContain("background: var(--ctms-bg-card);");
+    expect(source).toContain("background: var(--ctms-bg-base);");
+    expect(source).toContain("border-right: 1px solid var(--ctms-border-color);");
+    expect(source).toContain(".folder-item.active { color: var(--ctms-primary); background: var(--ctms-primary-light);");
+    expect(source).toContain(".collaboration-table-wrap { min-height: 0; flex: 1; overflow: auto; background: var(--ctms-bg-card);");
+    expect(source).not.toContain("background: #f8fafc;");
+  });
+
+  it("shows collaborators from the file-list response as a compact avatar stack", () => {
+    expect(source).toContain('label="协作者" width="150"');
+    expect(source).toContain("row.collaborators");
+    expect(source).toContain("collaborator-stack");
+    expect(source).toContain("collaboratorTone(collaborator.user_id)");
+  });
+
+  it("refreshes again after returning from an editor so delayed save callbacks update the list", () => {
+    expect(source).toContain("const scheduleRevisionRefresh");
+    expect(source).toContain("[2_500, 12_000]");
+    expect(source).toContain("onActivated(() =>");
+    expect(source).toContain("onDeactivated(clearRevisionRefreshTimers)");
+  });
+});

frontend/src/views/knowledge/CollaborationShareWorkspace.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+const source = readFileSync(resolve(__dirname, "./CollaborationShareWorkspace.vue"), "utf8");
+
+describe("CollaborationShareWorkspace security contract", () => {
+  it("reads the opaque link from the URL fragment and keeps grants in memory", () => {
+    expect(source).toContain("window.location.hash.slice(1)");
+    expect(source).toContain("const accessToken = ref");
+    expect(source).not.toContain("localStorage");
+    expect(source).not.toContain("sessionStorage");
+    expect(source).not.toContain("route.query");
+  });
+
+  it("requires the link password before initializing ONLYOFFICE", () => {
+    expect(source).toContain("verifyPublicCollaborationSharePassword");
+    expect(source).toContain("fetchPublicCollaborationEditorConfig");
+    expect(source).toContain('v-else-if="needsPassword"');
+    expect(source).toContain(':allow-save-as="false"');
+    expect(source).toContain(':allow-download="editorConfig.can_download"');
+    expect(source).toContain(':allow-clipboard="Boolean(metadata?.allow_export)"');
+    expect(source).toContain("response.data.host_path !== ONLYOFFICE_HOST_PATH");
+  });
+
+  it("downloads export-enabled shares to a user-selected local destination", () => {
+    expect(source).toContain('@download="handleDownload"');
+    expect(source).toContain("CollaborationDownloadDialog");
+    expect(source).toContain('@confirm="confirmDownload"');
+    expect(source).toContain("downloadDialogVisible.value = true");
+    expect(source).toContain("const destinationPromise = prepareSaveFile(suggestedName)");
+    expect(source).toContain('kind: "download"');
+  });
+
+  it("shows view or edit access and destroys sensitive state on unmount", () => {
+    expect(source).toContain('metadata.access_mode === "edit"');
+    expect(source).toContain("destroyEditor();");
+    expect(source).toContain('accessToken.value = ""');
+    expect(source).toContain('password.value = ""');
+  });
+});

frontend/src/views/knowledge/CollaborationShareWorkspace.vue

@@ -0,0 +1,368 @@
+<template>
+  <section class="share-workspace">
+    <header class="share-workspace__header">
+      <div class="share-workspace__brand">CTMS 在线协作</div>
+      <div class="share-workspace__title" :title="metadata?.file_name">{{ metadata?.file_name || "共享文件" }}</div>
+      <span v-if="metadata" class="share-workspace__access" :class="`is-${metadata.access_mode}`">
+        {{ metadata.access_mode === "edit" ? "可编辑" : "只读查看" }}
+      </span>
+      <span v-if="metadata?.expires_at" class="share-workspace__expiry">有效期至 {{ displayDateTime(metadata.expires_at) }}</span>
+      <span v-else-if="metadata" class="share-workspace__expiry">永久有效</span>
+      <span class="share-workspace__status" :class="`is-${status}`">{{ statusLabel }}</span>
+    </header>
+
+    <main class="share-workspace__content">
+      <OnlyOfficeViewer
+        v-if="editorConfig && !errorMessage"
+        :key="viewerKey"
+        :config="editorConfig.config"
+        :allow-clipboard="Boolean(metadata?.allow_export)"
+        :allow-save-as="false"
+        :allow-download="editorConfig.can_download"
+        :frame-title="`ONLYOFFICE 共享文件：${metadata?.file_name || ''}`"
+        @ready="status = 'ready'"
+        @warning="handleWarning"
+        @error="handleViewerError"
+        @state-change="handleStateChange"
+        @download="handleDownload"
+        @download-error="handleDownloadError"
+      />
+
+      <div v-else class="share-workspace__state">
+        <el-icon v-if="loading" class="is-loading" :size="30"><Loading /></el-icon>
+        <div v-else-if="needsPassword" class="share-password-card">
+          <div class="share-password-card__icon"><el-icon><Lock /></el-icon></div>
+          <h1>此链接受密码保护</h1>
+          <p>{{ metadata?.file_name }}</p>
+          <el-input
+            v-model="password"
+            type="password"
+            show-password
+            maxlength="64"
+            autocomplete="current-password"
+            placeholder="请输入链接密码"
+            autofocus
+            @keyup.enter="submitPassword"
+          />
+          <el-button type="primary" :loading="verifying" @click="submitPassword">打开文件</el-button>
+          <span v-if="passwordError" class="share-password-card__error">{{ passwordError }}</span>
+        </div>
+        <div v-else-if="errorMessage" class="share-error-card">
+          <h1>无法打开共享文件</h1>
+          <p>{{ errorMessage }}</p>
+          <el-button type="primary" @click="loadShare">重新加载</el-button>
+        </div>
+      </div>
+    </main>
+    <CollaborationDownloadDialog
+      v-model="downloadDialogVisible"
+      :file-name="downloadTitle"
+      :saving="downloading"
+      @confirm="confirmDownload"
+    />
+  </section>
+</template>
+
+<script setup lang="ts">
+import { computed, onBeforeUnmount, onMounted, ref, watch } from "vue";
+import { Loading, Lock } from "@element-plus/icons-vue";
+import { ElMessage } from "element-plus";
+import OnlyOfficeViewer from "../../components/OnlyOfficeViewer.vue";
+import CollaborationDownloadDialog from "../../components/collaboration/CollaborationDownloadDialog.vue";
+import {
+  fetchPublicCollaborationEditorConfig,
+  fetchPublicCollaborationShareMetadata,
+  verifyPublicCollaborationSharePassword,
+} from "../../api/collaboration";
+import { isTauriRuntime, ONLYOFFICE_HOST_PATH, prepareSaveFile } from "../../runtime";
+import { displayDateTime } from "../../utils/display";
+import { getApiErrorMessage } from "../../utils/apiErrorMessage";
+import { saveFileWithFeedback } from "../../utils/fileTaskFeedback";
+import type {
+  CollaborationEditorConfig,
+  CollaborationPublicShareMetadata,
+} from "../../types/collaboration";
+import type { OnlyOfficeSaveAsPayload } from "../../types/onlyoffice";
+
+type ShareStatus = "loading" | "locked" | "ready" | "saving" | "saved" | "warning" | "error";
+
+const metadata = ref<CollaborationPublicShareMetadata | null>(null);
+const editorConfig = ref<CollaborationEditorConfig | null>(null);
+const loading = ref(false);
+const verifying = ref(false);
+const needsPassword = ref(false);
+const password = ref("");
+const passwordError = ref("");
+const errorMessage = ref("");
+const status = ref<ShareStatus>("loading");
+const warningMessage = ref("");
+const accessToken = ref("");
+const requestSequence = ref(0);
+const viewerSequence = ref(0);
+const downloading = ref(false);
+const downloadDialogVisible = ref(false);
+const downloadTitle = ref("");
+const pendingDownload = ref<OnlyOfficeSaveAsPayload | null>(null);
+
+watch(downloadDialogVisible, (visible) => {
+  if (!visible && !downloading.value) {
+    pendingDownload.value = null;
+    downloadTitle.value = "";
+  }
+});
+
+const shareToken = () => {
+  try {
+    return decodeURIComponent(window.location.hash.slice(1).trim());
+  } catch {
+    return "";
+  }
+};
+const clientId = (() => {
+  if (typeof crypto.randomUUID === "function") return crypto.randomUUID();
+  return Array.from(crypto.getRandomValues(new Uint8Array(16)), (value) => value.toString(16).padStart(2, "0")).join("");
+})();
+const viewerKey = computed(() => `${clientId}:${viewerSequence.value}`);
+const statusLabel = computed(() => {
+  if (downloading.value) return "正在下载";
+  if (status.value === "locked") return "等待密码";
+  if (status.value === "ready") return "已连接";
+  if (status.value === "saving") return "正在自动保存";
+  if (status.value === "saved") return "更改已同步";
+  if (status.value === "warning") return warningMessage.value || "协作服务警告";
+  if (status.value === "error") return "加载失败";
+  return "正在加载";
+});
+
+const errorForResponse = async (error: unknown) => {
+  const statusCode = Number((error as any)?.response?.status || 0);
+  if (statusCode === 404) return "链接不存在、已关闭或共享文件已被删除";
+  if (statusCode === 410) return "共享链接已过期，请联系文件所有者重新分享";
+  if (statusCode === 429) return "密码尝试次数过多，请稍后再试";
+  if (statusCode === 503) return "在线协作服务暂时不可用";
+  return getApiErrorMessage(error, "共享文件加载失败");
+};
+
+const destroyEditor = () => {
+  requestSequence.value += 1;
+  editorConfig.value = null;
+  viewerSequence.value += 1;
+  downloading.value = false;
+  downloadDialogVisible.value = false;
+  downloadTitle.value = "";
+  pendingDownload.value = null;
+};
+
+const loadEditor = async (sequence: number) => {
+  const response = await fetchPublicCollaborationEditorConfig(shareToken(), {
+    access_token: accessToken.value || undefined,
+    client_id: clientId,
+    display_name: "链接访客",
+  });
+  if (requestSequence.value !== sequence) return;
+  if (response.data.host_path !== ONLYOFFICE_HOST_PATH) throw new Error("ONLYOFFICE 宿主页配置不合法");
+  editorConfig.value = response.data;
+  viewerSequence.value += 1;
+};
+
+const loadShare = async () => {
+  const token = shareToken();
+  if (!token) {
+    errorMessage.value = "共享链接缺少访问凭证";
+    status.value = "error";
+    return;
+  }
+  destroyEditor();
+  const sequence = requestSequence.value;
+  loading.value = true;
+  errorMessage.value = "";
+  passwordError.value = "";
+  needsPassword.value = false;
+  status.value = "loading";
+  try {
+    const response = await fetchPublicCollaborationShareMetadata(token);
+    if (requestSequence.value !== sequence) return;
+    metadata.value = response.data;
+    needsPassword.value = response.data.requires_password && !accessToken.value;
+    if (needsPassword.value) {
+      status.value = "locked";
+    } else {
+      await loadEditor(sequence);
+    }
+  } catch (error) {
+    if (requestSequence.value !== sequence) return;
+    errorMessage.value = await errorForResponse(error);
+    status.value = "error";
+  } finally {
+    if (requestSequence.value === sequence) loading.value = false;
+  }
+};
+
+const submitPassword = async () => {
+  if (!password.value || verifying.value) {
+    if (!password.value) passwordError.value = "请输入链接密码";
+    return;
+  }
+  verifying.value = true;
+  passwordError.value = "";
+  try {
+    const response = await verifyPublicCollaborationSharePassword(shareToken(), password.value);
+    accessToken.value = response.data.access_token;
+    password.value = "";
+    needsPassword.value = false;
+    status.value = "loading";
+    loading.value = true;
+    const sequence = requestSequence.value;
+    await loadEditor(sequence);
+  } catch (error) {
+    const statusCode = Number((error as any)?.response?.status || 0);
+    passwordError.value = statusCode === 401 ? "链接密码不正确" : await errorForResponse(error);
+    status.value = statusCode === 401 ? "locked" : "error";
+  } finally {
+    verifying.value = false;
+    loading.value = false;
+  }
+};
+
+const eventMessage = (detail: Record<string, unknown>) => {
+  for (const key of ["message", "errorDescription", "warningDescription"] as const) {
+    const value = detail[key];
+    if (typeof value === "string" && value.trim()) return value.trim();
+  }
+  return "";
+};
+const handleWarning = (detail: Record<string, unknown>) => {
+  warningMessage.value = eventMessage(detail) || "协作服务返回警告";
+  status.value = "warning";
+};
+const handleViewerError = (detail: Record<string, unknown>) => {
+  errorMessage.value = eventMessage(detail) || "共享文件加载或转换失败";
+  editorConfig.value = null;
+  status.value = "error";
+};
+const handleStateChange = (changed: boolean) => {
+  status.value = changed ? "saving" : "saved";
+};
+
+const suggestedDownloadName = (payload: OnlyOfficeSaveAsPayload) => {
+  const extension = payload.fileType.toLowerCase();
+  return payload.title.toLowerCase().endsWith(`.${extension}`)
+    ? payload.title
+    : `${payload.title}.${extension}`;
+};
+
+const savePendingDownload = async () => {
+  const payload = pendingDownload.value;
+  if (!payload || downloading.value || !editorConfig.value?.can_download) return;
+  const suggestedName = suggestedDownloadName(payload);
+  // Web 文件选择器必须由确认按钮的用户手势直接触发。
+  const destinationPromise = prepareSaveFile(suggestedName);
+  downloading.value = true;
+  try {
+    const destination = await destinationPromise;
+    if (!destination) {
+      if (!downloadDialogVisible.value) {
+        pendingDownload.value = null;
+        downloadTitle.value = "";
+      }
+      return;
+    }
+    const result = await saveFileWithFeedback(
+      { suggestedName, mimeType: payload.mimeType, data: payload.data },
+      {
+        kind: "download",
+        title: "下载共享文件",
+        pendingDetail: "请选择本机保存位置",
+        completedDetail: "文件已下载到指定位置",
+      },
+      destination,
+    );
+    if (result === "saved") {
+      downloadDialogVisible.value = false;
+      pendingDownload.value = null;
+      downloadTitle.value = "";
+    }
+  } catch (error) {
+    ElMessage.error(await getApiErrorMessage(error, "共享文件下载失败"));
+  } finally {
+    downloading.value = false;
+  }
+};
+
+const confirmDownload = () => {
+  void savePendingDownload();
+};
+
+const handleDownload = (payload: OnlyOfficeSaveAsPayload) => {
+  if (downloading.value || pendingDownload.value || !editorConfig.value?.can_download) return;
+  pendingDownload.value = payload;
+  downloadTitle.value = suggestedDownloadName(payload);
+  if (isTauriRuntime()) {
+    void savePendingDownload();
+    return;
+  }
+  downloadDialogVisible.value = true;
+};
+
+const handleDownloadError = (message: string) => {
+  ElMessage.error(message || "共享文件下载失败");
+};
+
+onMounted(loadShare);
+onBeforeUnmount(() => {
+  destroyEditor();
+  accessToken.value = "";
+  password.value = "";
+});
+</script>
+
+<style scoped>
+.share-workspace {
+  display: grid;
+  grid-template-rows: 48px minmax(0, 1fr);
+  width: 100vw;
+  height: 100vh;
+  height: 100dvh;
+  min-width: 0;
+  min-height: 0;
+  overflow: hidden;
+  color: #273b50;
+  background: #f3f5f8;
+}
+.share-workspace__header {
+  z-index: 1;
+  display: grid;
+  grid-template-columns: auto minmax(120px, 1fr) auto auto auto;
+  align-items: center;
+  gap: 12px;
+  padding: 0 18px;
+  border-bottom: 1px solid #dce3eb;
+  background: #fff;
+}
+.share-workspace__brand { color: #3d617d; font-size: 14px; font-weight: 700; white-space: nowrap; }
+.share-workspace__title { overflow: hidden; font-size: 14px; font-weight: 650; text-overflow: ellipsis; white-space: nowrap; }
+.share-workspace__access { padding: 3px 9px; border-radius: 11px; color: #52667a; background: #eef2f6; font-size: 12px; white-space: nowrap; }
+.share-workspace__access.is-edit { color: #237451; background: #e7f5ee; }
+.share-workspace__expiry,
+.share-workspace__status { color: #738398; font-size: 12px; white-space: nowrap; }
+.share-workspace__status.is-ready,
+.share-workspace__status.is-saved { color: #25845b; }
+.share-workspace__status.is-saving { color: #99651e; }
+.share-workspace__status.is-warning,
+.share-workspace__status.is-error { color: #b65c29; }
+.share-workspace__content { min-width: 0; min-height: 0; overflow: hidden; }
+.share-workspace__state { display: flex; align-items: center; justify-content: center; width: 100%; height: 100%; padding: 24px; }
+.share-password-card,
+.share-error-card { display: flex; width: min(390px, 100%); flex-direction: column; align-items: stretch; gap: 14px; padding: 30px; border: 1px solid #dbe3ec; border-radius: 14px; background: #fff; box-shadow: 0 16px 42px rgba(40, 58, 78, 0.12); text-align: center; }
+.share-password-card__icon { display: grid; width: 46px; height: 46px; place-items: center; align-self: center; border-radius: 50%; color: #3f6f91; background: #eaf2f8; font-size: 22px; }
+.share-password-card h1,
+.share-error-card h1 { margin: 0; color: #26384c; font-size: 19px; }
+.share-password-card p,
+.share-error-card p { margin: 0 0 4px; color: #75859a; font-size: 13px; }
+.share-password-card__error { color: #d14f4f; font-size: 12px; text-align: left; }
+@media (max-width: 720px) {
+  .share-workspace__header { grid-template-columns: minmax(0, 1fr) auto auto; padding: 0 10px; }
+  .share-workspace__brand,
+  .share-workspace__expiry { display: none; }
+}
+</style>

frontend/src/views/knowledge/CollaborationWorkspace.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+const source = readFileSync(resolve(__dirname, "./CollaborationWorkspace.vue"), "utf8");
+const globalStyles = readFileSync(resolve(__dirname, "../../styles/main.css"), "utf8");
+
+describe("CollaborationWorkspace Save As contract", () => {
+  it("separates signed Save As and download capabilities", () => {
+    expect(source).toContain(':allow-save-as="editorConfig.can_save_as"');
+    expect(source).toContain(':allow-download="editorConfig.can_download"');
+    expect(source).toContain(':allow-clipboard="Boolean(editorConfig.can_download)"');
+    expect(source).toContain('@save-as="handleSaveAs"');
+    expect(source).toContain('@download="handleDownload"');
+    expect(source).toContain("!editorConfig.value?.can_save_as");
+    expect(source).toContain("!editorConfig.value?.can_download");
+  });
+
+  it("reuses the workspace picker and imports Save As bytes as a new file", () => {
+    expect(source).toContain("CollaborationSaveAsDialog");
+    expect(source).toContain('@confirm="submitSaveAs"');
+    expect(source).toContain("const form = new FormData()");
+    expect(source).toContain('form.append("folder_id", selection.folderId)');
+    expect(source).toContain("importCollaborationFile(studyId.value, form)");
+  });
+
+  it("asks for a local destination from a user-confirmed web dialog and records the completed download", () => {
+    expect(source).toContain("CollaborationDownloadDialog");
+    expect(source).toContain('@confirm="confirmDownload"');
+    expect(source).toContain("downloadDialogVisible.value = true");
+    expect(source).toContain("const destinationPromise = prepareSaveFile(suggestedName)");
+    expect(source).toContain("saveFileWithFeedback(");
+    expect(source).toContain('kind: "download"');
+    expect(source).toContain("recordCollaborationDownload(studyId.value, fileId.value, extension)");
+  });
+
+  it("submits ONLYOFFICE edit-right requests without granting edit locally", () => {
+    expect(source).toContain('@request-edit-rights="requestEditRights"');
+    expect(source).toContain("createCollaborationEditRequest(studyId.value, fileId.value)");
+    expect(source).toContain('edit_request_status: "PENDING"');
+    expect(source).toContain("编辑权限申请处理中");
+  });
+
+  it("keeps the plain edit-request action visually distinct from solid primary buttons", () => {
+    expect(source).toContain('type="primary"');
+    expect(source).toContain("plain");
+    expect(source).toContain("申请编辑权限");
+    expect(globalStyles).toContain(".el-button--primary:not(.is-plain):not(.is-link):not(.is-text)");
+    expect(globalStyles).not.toMatch(/\.el-button--primary\s*\{[^}]*background-color:/);
+  });
+
+  it("provides an accessible web fullscreen control without duplicating native desktop controls", () => {
+    expect(source).toContain('v-if="showWorkspaceFullscreenControl"');
+    expect(source).toContain("computed(() => webFullscreenAvailable.value && !isTauriRuntime())");
+    expect(source).toContain('class="collaboration-workspace__fullscreen"');
+    expect(source).toContain(':aria-label="webFullscreenLabel"');
+    expect(source).toContain(':aria-pressed="webFullscreenActive"');
+    expect(source).toContain("toggleWebFullscreen");
+    expect(source).toContain("listenWebFullscreenChange(syncWebFullscreenState)");
+    expect(source).toContain("await exitWorkspaceFullscreen()");
+  });
+
+  it("reserves the macOS traffic-light safe area only outside native fullscreen", () => {
+    expect(source).toContain("'is-macos-desktop': isMacDesktop");
+    expect(source).toContain('isTauriRuntime() && getRuntimePlatform() === "macos"');
+    expect(source).toContain(".collaboration-workspace.is-macos-desktop:not(.is-fullscreen) .collaboration-workspace__header");
+    expect(source).toContain("padding-left: 72px;");
+  });
+
+  it("keeps the shared web and desktop document bar compact", () => {
+    expect(source).toContain("grid-template-rows: 36px minmax(0, 1fr);");
+    expect(source).toContain("grid-template-columns: 30px minmax(0, 1fr) auto auto auto auto;");
+    expect(source).toContain("width: 28px;");
+    expect(source).toContain("height: 28px;");
+  });
+
+  it("reduces the fullscreen CTMS header to an opaque auto-hiding control", () => {
+    expect(source).toContain("'is-fullscreen': webFullscreenActive");
+    expect(source).toContain("'is-fullscreen-toolbar-visible': fullscreenToolbarVisible");
+    expect(source).toContain('class="collaboration-workspace__fullscreen-hotzone"');
+    expect(source).toContain('@pointerenter="showFullscreenToolbar"');
+    expect(source).toContain("fullscreenToolbarHideTimer = window.setTimeout");
+    expect(source).toContain("}, 900);");
+    expect(source).toContain('const viewerKey = computed(() => `${fileId.value}:${viewerSequence.value}`);');
+    expect(source).toContain(".collaboration-workspace.is-fullscreen { grid-template-rows: minmax(0, 1fr); }");
+    expect(source).toContain("width: 88px;");
+    expect(source).toContain("transform: translateY(calc(-100% - 12px));");
+    expect(source).toContain(".collaboration-workspace.is-fullscreen .collaboration-workspace__header > :not(.collaboration-workspace__back):not(.collaboration-workspace__fullscreen)");
+    expect(source).toContain(".collaboration-workspace.is-fullscreen .collaboration-workspace__header:has(:focus-visible)");
+    expect(source).toContain("background: #fff;");
+    expect(source).toContain("opacity: 1;");
+    expect(source).toContain(".collaboration-workspace.is-fullscreen .collaboration-workspace__content { grid-row: 1; }");
+  });
+});

frontend/src/views/knowledge/CollaborationWorkspace.vue

@@ -0,0 +1,617 @@
+<template>
+  <section
+    class="collaboration-workspace"
+    :class="{
+      'is-fullscreen': webFullscreenActive,
+      'is-fullscreen-toolbar-visible': fullscreenToolbarVisible,
+      'is-macos-desktop': isMacDesktop,
+    }"
+  >
+    <div
+      v-if="webFullscreenActive"
+      class="collaboration-workspace__fullscreen-hotzone"
+      aria-hidden="true"
+      @pointerenter="showFullscreenToolbar"
+      @pointerleave="scheduleFullscreenToolbarHide"
+    />
+    <header
+      class="collaboration-workspace__header"
+      @pointerenter="cancelFullscreenToolbarHide"
+      @pointerleave="scheduleFullscreenToolbarHide"
+      @focusin="showFullscreenToolbar"
+      @focusout="scheduleFullscreenToolbarHide"
+    >
+      <button class="collaboration-workspace__back" type="button" title="关闭协作文件并返回" @click="goBack">‹</button>
+      <div class="collaboration-workspace__title" :title="fileName">{{ fileName }}</div>
+      <div class="collaboration-workspace__access" :class="`is-${accessMode}`">
+        {{ accessMode === "edit" ? "协作编辑" : "只读查看" }}
+      </div>
+      <div class="collaboration-workspace__status" :class="`is-${status}`">{{ statusLabel }}</div>
+      <el-button
+        v-if="accessMode === 'view' && file?.edit_request_status === 'PENDING'"
+        size="small"
+        disabled
+      >编辑权限申请处理中</el-button>
+      <el-button
+        v-else-if="accessMode === 'view' && (file?.can_request_edit || editorConfig?.can_request_edit)"
+        size="small"
+        type="primary"
+        plain
+        :loading="requestingEdit"
+        @click="requestEditRights"
+      >申请编辑权限</el-button>
+      <el-button v-if="errorMessage" link type="primary" :loading="loading" @click="loadWorkspace">重试</el-button>
+      <el-tooltip v-if="showWorkspaceFullscreenControl" :content="webFullscreenLabel" placement="bottom">
+        <button
+          type="button"
+          class="collaboration-workspace__fullscreen"
+          :aria-label="webFullscreenLabel"
+          :aria-pressed="webFullscreenActive"
+          @click="handleWebFullscreenToggle"
+        >
+          <el-icon><ScaleToOriginal v-if="webFullscreenActive" /><FullScreen v-else /></el-icon>
+        </button>
+      </el-tooltip>
+    </header>
+
+    <main class="collaboration-workspace__content">
+      <OnlyOfficeViewer
+        v-if="editorConfig && !errorMessage"
+        :key="viewerKey"
+        :config="editorConfig.config"
+        :allow-clipboard="Boolean(editorConfig.can_download)"
+        :allow-save-as="editorConfig.can_save_as"
+        :allow-download="editorConfig.can_download"
+        :frame-title="`ONLYOFFICE 在线协作：${fileName}`"
+        @ready="handleReady"
+        @warning="handleWarning"
+        @error="handleError"
+        @state-change="handleStateChange"
+        @save-as="handleSaveAs"
+        @save-as-error="handleSaveAsError"
+        @download="handleDownload"
+        @download-error="handleDownloadError"
+        @request-edit-rights="requestEditRights"
+      />
+      <div v-else class="collaboration-workspace__state">
+        <el-icon v-if="loading" class="is-loading" :size="28"><Loading /></el-icon>
+        <template v-else-if="errorMessage">
+          <strong>无法打开协作文件</strong>
+          <p>{{ errorMessage }}</p>
+          <el-button type="primary" @click="loadWorkspace">重新加载</el-button>
+        </template>
+      </div>
+    </main>
+    <CollaborationSaveAsDialog
+      v-model="saveAsDialogVisible"
+      :study-id="studyId"
+      :initial-title="saveAsTitle"
+      :initial-folder-id="file?.folder_id || null"
+      :saving="savingCopy"
+      :can-create-folder="canCreateWorkspaceFile"
+      @confirm="submitSaveAs"
+    />
+    <CollaborationDownloadDialog
+      v-model="downloadDialogVisible"
+      :file-name="downloadTitle"
+      :saving="downloading"
+      @confirm="confirmDownload"
+    />
+  </section>
+</template>
+
+<script setup lang="ts">
+import { computed, inject, onActivated, onBeforeUnmount, onDeactivated, onMounted, ref, watch } from "vue";
+import { useRoute, useRouter } from "vue-router";
+import { FullScreen, Loading, ScaleToOriginal } from "@element-plus/icons-vue";
+import { ElMessage } from "element-plus";
+import OnlyOfficeViewer from "../../components/OnlyOfficeViewer.vue";
+import CollaborationDownloadDialog from "../../components/collaboration/CollaborationDownloadDialog.vue";
+import CollaborationSaveAsDialog from "../../components/collaboration/CollaborationSaveAsDialog.vue";
+import { workspaceTaskControllerKey } from "../../components/layout/workspaceTaskController";
+import {
+  fetchCollaborationEditorConfig,
+  fetchCollaborationFile,
+  createCollaborationEditRequest,
+  importCollaborationFile,
+  recordCollaborationDownload,
+} from "../../api/collaboration";
+import { useStudyStore } from "../../store/study";
+import {
+  DESKTOP_SERVER_URL_CHANGED_EVENT,
+  getRuntimePlatform,
+  isWebFullscreenActive,
+  isWebFullscreenAvailable,
+  isTauriRuntime,
+  listenWebFullscreenChange,
+  ONLYOFFICE_HOST_PATH,
+  prepareSaveFile,
+  refreshWebFullscreenState,
+  toggleWebFullscreen,
+} from "../../runtime";
+import { getApiErrorMessage } from "../../utils/apiErrorMessage";
+import { saveFileWithFeedback } from "../../utils/fileTaskFeedback";
+import { usePermission } from "../../utils/permission";
+import type { CollaborationEditorConfig, CollaborationFile } from "../../types/collaboration";
+import type { OnlyOfficeSaveAsPayload } from "../../types/onlyoffice";
+
+type WorkspaceStatus = "loading" | "ready" | "saving" | "saved" | "warning" | "error";
+
+const route = useRoute();
+const router = useRouter();
+const study = useStudyStore();
+const workspaceTaskController = inject(workspaceTaskControllerKey, null);
+const { can } = usePermission();
+const file = ref<CollaborationFile | null>(null);
+const editorConfig = ref<CollaborationEditorConfig | null>(null);
+const errorMessage = ref("");
+const warningMessage = ref("");
+const loading = ref(false);
+const status = ref<WorkspaceStatus>("loading");
+const requestSequence = ref(0);
+const viewerSequence = ref(0);
+const savingCopy = ref(false);
+const requestingEdit = ref(false);
+const downloading = ref(false);
+const downloadDialogVisible = ref(false);
+const downloadTitle = ref("");
+const pendingDownload = ref<OnlyOfficeSaveAsPayload | null>(null);
+const saveAsDialogVisible = ref(false);
+const saveAsTitle = ref("");
+const pendingSaveAs = ref<OnlyOfficeSaveAsPayload | null>(null);
+const webFullscreenAvailable = ref(false);
+const webFullscreenActive = ref(false);
+const fullscreenToolbarVisible = ref(false);
+const isMacDesktop = isTauriRuntime() && getRuntimePlatform() === "macos";
+let mounted = false;
+let webFullscreenUnlisten: (() => void) | null = null;
+let fullscreenToolbarHideTimer: number | undefined;
+
+watch(downloadDialogVisible, (visible) => {
+  if (!visible && !downloading.value) {
+    pendingDownload.value = null;
+    downloadTitle.value = "";
+  }
+});
+
+const studyId = computed(() => study.currentStudy?.id || "");
+const fileId = computed(() => String(route.params.fileId || ""));
+const fileName = computed(() => editorConfig.value?.file_name || file.value?.title || "在线协作");
+const accessMode = computed(() => editorConfig.value?.access_mode || (file.value?.can_edit ? "edit" : "view"));
+const viewerKey = computed(() => `${fileId.value}:${viewerSequence.value}`);
+const canCreateWorkspaceFile = computed(() =>
+  ["read", "create", "edit", "manage", "export", "delete"].every((action) =>
+    can(`collaboration.${action}`),
+  ),
+);
+const statusLabel = computed(() => {
+  if (savingCopy.value) return "正在另存为";
+  if (downloading.value) return "正在下载";
+  if (status.value === "ready") return "已连接";
+  if (status.value === "saving") return "正在自动保存";
+  if (status.value === "saved") return "更改已同步";
+  if (status.value === "warning") return warningMessage.value || "协作服务警告";
+  if (status.value === "error") return "加载失败";
+  return "正在加载";
+});
+const showWorkspaceFullscreenControl = computed(() => webFullscreenAvailable.value && !isTauriRuntime());
+const webFullscreenLabel = computed(() => webFullscreenActive.value ? "退出全屏" : "进入全屏");
+
+const cancelFullscreenToolbarHide = () => {
+  if (fullscreenToolbarHideTimer !== undefined) window.clearTimeout(fullscreenToolbarHideTimer);
+  fullscreenToolbarHideTimer = undefined;
+};
+
+const showFullscreenToolbar = () => {
+  if (!webFullscreenActive.value) return;
+  cancelFullscreenToolbarHide();
+  fullscreenToolbarVisible.value = true;
+};
+
+const scheduleFullscreenToolbarHide = () => {
+  if (!webFullscreenActive.value) return;
+  cancelFullscreenToolbarHide();
+  fullscreenToolbarHideTimer = window.setTimeout(() => {
+    fullscreenToolbarVisible.value = false;
+    fullscreenToolbarHideTimer = undefined;
+  }, 900);
+};
+
+const syncWebFullscreenState = () => {
+  webFullscreenAvailable.value = isWebFullscreenAvailable();
+  const active = isWebFullscreenActive();
+  if (active !== webFullscreenActive.value) {
+    cancelFullscreenToolbarHide();
+    fullscreenToolbarVisible.value = false;
+  }
+  webFullscreenActive.value = active;
+};
+
+const handleWebFullscreenToggle = async () => {
+  try {
+    await toggleWebFullscreen();
+  } catch (error) {
+    const message = isTauriRuntime()
+      ? "无法切换桌面全屏，请使用“显示 > 进入全屏”重试"
+      : typeof error === "object" && error !== null && "name" in error && error.name === "NotAllowedError"
+        ? "浏览器未允许进入全屏，请再次点击或检查站点权限"
+        : "无法切换全屏，请使用浏览器菜单重试";
+    ElMessage.warning(message);
+  } finally {
+    syncWebFullscreenState();
+  }
+};
+
+const exitWorkspaceFullscreen = async () => {
+  try {
+    if (!await refreshWebFullscreenState()) return;
+    await toggleWebFullscreen();
+  } catch {
+    // 全屏状态读取或退出失败不应阻止关闭协作页。
+  } finally {
+    syncWebFullscreenState();
+  }
+};
+
+const errorForResponse = async (error: unknown) => {
+  const statusCode = Number((error as any)?.response?.status || 0);
+  const code = String((error as any)?.response?.data?.code || "");
+  if (code === "ONLYOFFICE_DISABLED") return "在线协作服务尚未启用";
+  if (code === "ONLYOFFICE_UNAVAILABLE") return "在线协作服务暂时不可用";
+  if (statusCode === 401) return "登录状态已失效，请重新登录";
+  if (statusCode === 403) return "您没有查看此协作文件的权限";
+  if (statusCode === 404) return "协作文件不存在或已被移入回收站";
+  return getApiErrorMessage(error, "在线协作编辑器加载失败");
+};
+
+const destroyEditor = () => {
+  requestSequence.value += 1;
+  editorConfig.value = null;
+  viewerSequence.value += 1;
+  savingCopy.value = false;
+  downloading.value = false;
+  downloadDialogVisible.value = false;
+  downloadTitle.value = "";
+  pendingDownload.value = null;
+  saveAsDialogVisible.value = false;
+  pendingSaveAs.value = null;
+};
+
+const loadWorkspace = async () => {
+  if (!studyId.value || !fileId.value) return;
+  const sequence = requestSequence.value + 1;
+  requestSequence.value = sequence;
+  destroyEditor();
+  requestSequence.value = sequence;
+  errorMessage.value = "";
+  warningMessage.value = "";
+  loading.value = true;
+  status.value = "loading";
+  try {
+    const [fileResponse, configResponse] = await Promise.all([
+      fetchCollaborationFile(studyId.value, fileId.value),
+      fetchCollaborationEditorConfig(studyId.value, fileId.value),
+    ]);
+    if (requestSequence.value !== sequence) return;
+    if (configResponse.data.host_path !== ONLYOFFICE_HOST_PATH) throw new Error("ONLYOFFICE 宿主页配置不合法");
+    file.value = fileResponse.data;
+    editorConfig.value = configResponse.data;
+    viewerSequence.value += 1;
+    study.setViewContext({ pageTitle: configResponse.data.file_name, objectType: "在线协作" });
+  } catch (error) {
+    if (requestSequence.value !== sequence) return;
+    errorMessage.value = await errorForResponse(error);
+    status.value = "error";
+  } finally {
+    if (requestSequence.value === sequence) loading.value = false;
+  }
+};
+
+const eventMessage = (detail: Record<string, unknown>) => {
+  for (const key of ["message", "errorDescription", "warningDescription"] as const) {
+    const value = detail[key];
+    if (typeof value === "string" && value.trim()) return value.trim();
+  }
+  const code = detail.errorCode ?? detail.warningCode ?? detail.code;
+  return code === undefined ? "" : `错误代码：${String(code)}`;
+};
+
+const handleReady = () => { status.value = "ready"; };
+const handleStateChange = (changed: boolean) => { status.value = changed ? "saving" : "saved"; };
+const handleWarning = (detail: Record<string, unknown>) => {
+  warningMessage.value = eventMessage(detail) || "协作服务返回警告";
+  status.value = "warning";
+};
+const handleError = (detail: Record<string, unknown>) => {
+  errorMessage.value = eventMessage(detail) || "协作文件加载或转换失败";
+  status.value = "error";
+  editorConfig.value = null;
+};
+
+const requestEditRights = async () => {
+  if (requestingEdit.value || accessMode.value === "edit" || file.value?.edit_request_status === "PENDING") return;
+  requestingEdit.value = true;
+  try {
+    await createCollaborationEditRequest(studyId.value, fileId.value);
+    if (file.value) {
+      file.value = { ...file.value, can_request_edit: false, edit_request_status: "PENDING" };
+    }
+    if (editorConfig.value) editorConfig.value = { ...editorConfig.value, can_request_edit: false };
+    ElMessage.success("编辑权限申请已提交");
+  } catch (error) {
+    ElMessage.error(await getApiErrorMessage(error, "编辑权限申请失败"));
+  } finally {
+    requestingEdit.value = false;
+  }
+};
+
+const handleSaveAs = (payload: OnlyOfficeSaveAsPayload) => {
+  if (savingCopy.value || !editorConfig.value?.can_save_as) return;
+  const extension = payload.fileType.toLowerCase();
+  saveAsTitle.value = payload.title.toLowerCase().endsWith(`.${extension}`)
+    ? payload.title
+    : `${payload.title}.${extension}`;
+  pendingSaveAs.value = payload;
+  saveAsDialogVisible.value = true;
+};
+
+const submitSaveAs = async (selection: { title: string; folderId: string | null }) => {
+  const payload = pendingSaveAs.value;
+  if (!payload || savingCopy.value || !editorConfig.value?.can_save_as) return;
+  savingCopy.value = true;
+  try {
+    const extension = payload.fileType.toLowerCase();
+    const targetTitle = selection.title.toLowerCase().endsWith(`.${extension}`)
+      ? selection.title
+      : `${selection.title}.${extension}`;
+    const form = new FormData();
+    form.append("file", new File([payload.data], targetTitle, {
+      type: payload.mimeType || "application/octet-stream",
+      lastModified: Date.now(),
+    }));
+    if (selection.folderId) form.append("folder_id", selection.folderId);
+    const { data } = await importCollaborationFile(studyId.value, form);
+    saveAsDialogVisible.value = false;
+    pendingSaveAs.value = null;
+    ElMessage.success(`已在工作区创建“${data.title}”`);
+  } catch (error) {
+    ElMessage.error(await getApiErrorMessage(error, "协作文件另存为失败"));
+  } finally {
+    savingCopy.value = false;
+  }
+};
+
+const handleSaveAsError = (message: string) => {
+  ElMessage.error(message || "协作文件另存为失败");
+};
+
+const suggestedDownloadName = (payload: OnlyOfficeSaveAsPayload) => {
+  const extension = payload.fileType.toLowerCase();
+  return payload.title.toLowerCase().endsWith(`.${extension}`)
+    ? payload.title
+    : `${payload.title}.${extension}`;
+};
+
+const savePendingDownload = async () => {
+  const payload = pendingDownload.value;
+  if (!payload || downloading.value || !editorConfig.value?.can_download) return;
+  const extension = payload.fileType.toLowerCase();
+  const suggestedName = suggestedDownloadName(payload);
+  // Web 文件选择器必须直接在按钮点击产生的用户手势中调用，不能等到下一轮异步任务。
+  const destinationPromise = prepareSaveFile(suggestedName);
+  downloading.value = true;
+  try {
+    const destination = await destinationPromise;
+    if (!destination) {
+      if (!downloadDialogVisible.value) {
+        pendingDownload.value = null;
+        downloadTitle.value = "";
+      }
+      return;
+    }
+    const result = await saveFileWithFeedback(
+      { suggestedName, mimeType: payload.mimeType, data: payload.data },
+      {
+        kind: "download",
+        title: "下载协作文件",
+        pendingDetail: "请选择本机保存位置",
+        completedDetail: "文件已下载到指定位置",
+      },
+      destination,
+    );
+    if (result === "saved") {
+      downloadDialogVisible.value = false;
+      pendingDownload.value = null;
+      downloadTitle.value = "";
+      try {
+        await recordCollaborationDownload(studyId.value, fileId.value, extension);
+      } catch {
+        ElMessage.warning("文件已下载，但下载审计记录失败");
+      }
+    }
+  } catch (error) {
+    ElMessage.error(await getApiErrorMessage(error, "协作文件下载失败"));
+  } finally {
+    downloading.value = false;
+  }
+};
+
+const confirmDownload = () => {
+  void savePendingDownload();
+};
+
+const handleDownload = (payload: OnlyOfficeSaveAsPayload) => {
+  if (downloading.value || pendingDownload.value || !editorConfig.value?.can_download) return;
+  pendingDownload.value = payload;
+  downloadTitle.value = suggestedDownloadName(payload);
+  if (isTauriRuntime()) {
+    void savePendingDownload();
+    return;
+  }
+  downloadDialogVisible.value = true;
+};
+
+const handleDownloadError = (message: string) => {
+  ElMessage.error(message || "协作文件下载失败");
+};
+
+const handleServerChange = () => {
+  destroyEditor();
+  loading.value = false;
+  errorMessage.value = "服务器地址已切换，请重新加载协作文件";
+  status.value = "error";
+};
+
+const goBack = async () => {
+  await exitWorkspaceFullscreen();
+  if (workspaceTaskController?.closeTransientTask(route.path)) return;
+  await router.push("/knowledge/collaboration");
+};
+
+onMounted(() => {
+  mounted = true;
+  syncWebFullscreenState();
+  webFullscreenUnlisten = listenWebFullscreenChange(syncWebFullscreenState);
+  void refreshWebFullscreenState().then(syncWebFullscreenState).catch(() => {});
+  window.addEventListener(DESKTOP_SERVER_URL_CHANGED_EVENT, handleServerChange);
+  void loadWorkspace();
+});
+onActivated(() => {
+  syncWebFullscreenState();
+  if (mounted && !editorConfig.value && !loading.value && !errorMessage.value) void loadWorkspace();
+});
+onDeactivated(() => {
+  void exitWorkspaceFullscreen();
+  destroyEditor();
+  loading.value = false;
+  errorMessage.value = "";
+});
+onBeforeUnmount(() => {
+  cancelFullscreenToolbarHide();
+  webFullscreenUnlisten?.();
+  webFullscreenUnlisten = null;
+  void exitWorkspaceFullscreen();
+  destroyEditor();
+  window.removeEventListener(DESKTOP_SERVER_URL_CHANGED_EVENT, handleServerChange);
+  study.setViewContext(null);
+});
+</script>
+
+<style scoped>
+.collaboration-workspace {
+  position: relative;
+  display: grid;
+  grid-template-rows: 36px minmax(0, 1fr);
+  width: 100%;
+  height: 100%;
+  min-width: 0;
+  min-height: 0;
+  overflow: hidden;
+  color: #26384c;
+  background: #f3f5f8;
+}
+.collaboration-workspace.is-fullscreen { grid-template-rows: minmax(0, 1fr); }
+.collaboration-workspace__fullscreen-hotzone {
+  position: absolute;
+  z-index: 20;
+  top: 0;
+  left: 0;
+  width: 88px;
+  height: 14px;
+}
+.collaboration-workspace__fullscreen-hotzone::after {
+  position: absolute;
+  top: 3px;
+  left: 32px;
+  width: 24px;
+  height: 3px;
+  border-radius: 999px;
+  background: rgba(38, 56, 76, 0.34);
+  content: "";
+}
+.collaboration-workspace__header {
+  z-index: 1;
+  display: grid;
+  grid-template-columns: 30px minmax(0, 1fr) auto auto auto auto;
+  align-items: center;
+  gap: 8px;
+  padding: 0 12px 0 6px;
+  border-bottom: 1px solid #dce3eb;
+  background: #fff;
+}
+.collaboration-workspace.is-macos-desktop:not(.is-fullscreen) .collaboration-workspace__header {
+  padding-left: 72px;
+}
+.collaboration-workspace.is-fullscreen .collaboration-workspace__header {
+  position: absolute;
+  z-index: 21;
+  top: 6px;
+  left: 6px;
+  display: flex;
+  width: auto;
+  height: 34px;
+  gap: 2px;
+  padding: 0 4px;
+  border: 1px solid #dce3eb;
+  border-radius: 11px;
+  background: #fff;
+  opacity: 0;
+  pointer-events: none;
+  transform: translateY(calc(-100% - 12px));
+  box-shadow: 0 8px 24px rgba(20, 32, 51, 0.16);
+  transition: opacity 150ms ease, transform 180ms ease;
+}
+.collaboration-workspace.is-fullscreen .collaboration-workspace__header > :not(.collaboration-workspace__back):not(.collaboration-workspace__fullscreen) {
+  display: none;
+}
+.collaboration-workspace.is-fullscreen.is-fullscreen-toolbar-visible .collaboration-workspace__header,
+.collaboration-workspace.is-fullscreen .collaboration-workspace__header:has(:focus-visible) {
+  opacity: 1;
+  pointer-events: auto;
+  transform: translateY(0);
+}
+.collaboration-workspace__back {
+  width: 28px;
+  height: 28px;
+  padding: 0 0 3px;
+  border: 0;
+  border-radius: 7px;
+  color: #516579;
+  background: transparent;
+  font: 26px/1 system-ui, sans-serif;
+  cursor: pointer;
+}
+.collaboration-workspace__back:hover { background: #edf2f7; }
+.collaboration-workspace__title { overflow: hidden; font-size: 14px; font-weight: 650; text-overflow: ellipsis; white-space: nowrap; }
+.collaboration-workspace__access,
+.collaboration-workspace__status { font-size: 12px; white-space: nowrap; }
+.collaboration-workspace__access { padding: 3px 8px; border-radius: 10px; color: #52667a; background: #eef2f6; }
+.collaboration-workspace__access.is-edit { color: #237451; background: #e7f5ee; }
+.collaboration-workspace__status { color: #738398; }
+.collaboration-workspace__status.is-saving { color: #99651e; }
+.collaboration-workspace__fullscreen {
+  display: inline-flex;
+  width: 28px;
+  height: 28px;
+  align-items: center;
+  justify-content: center;
+  padding: 0;
+  border: 0;
+  border-radius: 7px;
+  color: #516579;
+  background: transparent;
+  cursor: pointer;
+  font-size: 16px;
+}
+.collaboration-workspace__fullscreen:hover { color: #237451; background: #edf5f1; }
+.collaboration-workspace__fullscreen:focus-visible { outline: 2px solid rgba(35, 116, 81, 0.3); outline-offset: 1px; }
+.collaboration-workspace__status.is-saved,
+.collaboration-workspace__status.is-ready { color: #25845b; }
+.collaboration-workspace__status.is-warning,
+.collaboration-workspace__status.is-error { color: #b65c29; }
+.collaboration-workspace__content { min-height: 0; overflow: hidden; }
+.collaboration-workspace.is-fullscreen .collaboration-workspace__content { grid-row: 1; }
+.collaboration-workspace__state { display: flex; flex-direction: column; align-items: center; justify-content: center; gap: 12px; width: 100%; height: 100%; color: #718096; text-align: center; }
+.collaboration-workspace__state strong { color: #2f4054; font-size: 17px; }
+.collaboration-workspace__state p { margin: 0; }
+</style>