Merge pull request #5 from dream-num/codex/workspace-exchange-ribbon-sync

feat(workspace): add server-side Office exchange

Author: OTime-Coder

apps/workspace/README.md

@@ -36,6 +36,18 @@ Product data is stored in `.data/univer-workspace.sqlite`. Univer unit data is
 stored separately in `.data/univer-collaboration.sqlite`, and uploaded Blob
 bytes default to `.data/univer-workspace-blobs`.
 
+The Univer editors import and export XLSX/CSV/TSV, DOCX, and PPTX through the
+server-side `@univerjs-pro/exchange-node` runtime. These endpoints follow the
+Universer Exchange shape under `/universer-api/exchange/**`; they are not part
+of the product OpenAPI. The Workspace file action automatically imports
+XLS/XLSX/CSV/TSV, DOC/DOCX, and PPT/PPTX as normal Univer Resources in the
+selected Space and folder; other file types remain downloadable Blob
+Resources. Editor Ribbon imports default to the root of the signed-in user's
+Personal Space. Uploaded source files, converted JSON snapshots, and export
+files are temporary BlobStore objects with process-local task metadata and a
+two-hour lifetime. Exchange actions are not shown for Worktree or merge-preview
+editors because those scopes do not yet have scope-aware Office conversion.
+
 ### Configuration
 
 Copy `.env.example` to `.env`. Development, database, and production start

apps/workspace/contracts/http/openapi.yaml

@@ -94,6 +94,8 @@ paths:
     $ref: ./paths/resources.yaml#/~1api~1resources
   /api/resources/{resourceId}:
     $ref: ./paths/resources.yaml#/~1api~1resources~1{resourceId}
+  /api/unit-resources/{unitId}:
+    $ref: ./paths/resources.yaml#/~1api~1unit-resources~1{unitId}
   /api/resources/{resourceId}/open:
     $ref: ./paths/resources.yaml#/~1api~1resources~1{resourceId}~1open
   /api/blob-upload-sessions:

apps/workspace/contracts/http/paths/resources.yaml

@@ -69,6 +69,29 @@
       "404":
         $ref: ../schemas/common.yaml#/NotFound
 
+/api/unit-resources/{unitId}:
+  parameters:
+    - name: unitId
+      in: path
+      required: true
+      schema:
+        type: string
+  get:
+    tags: [Resources]
+    operationId: getResourceByUnit
+    summary: Resolve Resource and owning Node metadata from a Univer Unit.
+    responses:
+      "200":
+        description: Current Resource and Node accessible to the signed-in User.
+        content:
+          application/json:
+            schema:
+              $ref: ../schemas/resources.yaml#/ResourceResponse
+      "401":
+        $ref: ../schemas/common.yaml#/Unauthorized
+      "404":
+        $ref: ../schemas/common.yaml#/NotFound
+
 /api/resources/{resourceId}/open:
   parameters:
     - name: resourceId

apps/workspace/docs/application-design.md

@@ -14,6 +14,7 @@ React
   │           ├── Nodes
   │           ├── Resources
   │           ├── Blobs / BlobStore
+  │           ├── Office Exchange
   │           ├── Univer Assets / File Gateway
   │           ├── Permissions / Trash / Views
   │           ├── Worktrees
@@ -130,6 +131,25 @@ Univer Asset Module 适配原生 File API。它将 Slide、Board、Base 等 Unit
 `/content` 网关，网关在每次请求时重新解析 Unit/Worktree 权限并禁止缓存。Worktree-local
 Asset 在对应 Unit 合入后发布到 Trunk。
 
+Office Exchange Module 适配 Univer Exchange Client 使用的 Universer 协议：
+
+- `source=HttpImport` 的 `/universer-api/stream/file/upload` 由 Exchange 接收；Unit Embedded
+  Asset 的上传继续由 Univer Asset Module 处理；
+- import task 使用 `@univerjs-pro/exchange-node` 转换 XLS/XLSX/CSV/TSV、DOC/DOCX 或
+  PPT/PPTX；Workspace 文件入口按扩展名自动识别这些格式，并在当前 Space 与目录创建正式
+  Resource，Editor Ribbon 导入则默认创建在当前 User 的 Personal Space 根目录。两种入口都
+  必须通过 Resource Module，不能直接写入一个没有产品归属的 Collaboration Unit；
+- export task 只接受服务端 `AccessResolver` 能解析且允许打开的 Trunk Unit，服务端自行
+  确认 Unit Type，并物化最新 snapshot 与 Sheet blocks；
+- 转换用 source、JSON 和 output 字节保存在 `BlobStore`，任务与临时文件身份只在当前进程
+  保存并在两小时后失效，不写入产品数据库；
+- Worktree 和 Merge Preview 暂不注册 Exchange 插件，避免把 Trunk 内容误当作当前 Scope
+  导出。Board 没有受支持的 Office 格式，也不注册 Exchange。
+
+这些 `/universer-api` Route 属于 Univer/Universer 兼容入口，不是产品 HTTP contract，因此
+不添加到 `contracts/http`。身份仍来自 Workspace Login Session；客户端提交的 User、Role、
+Unit Type 或 Unit 可见性都不作为授权依据。
+
 ## Collaboration Access Resolver
 
 Collaboration Endpoint 不信任客户端提交的 Resource ID、Unit Type、Role 或

apps/workspace/docs/architecture.md

@@ -67,6 +67,7 @@ apps/workspace/
 │       │   ├── nodes/
 │       │   ├── resources/
 │       │   ├── blobs/
+│       │   ├── exchange/
 │       │   ├── univer-assets/
 │       │   ├── operations/
 │       │   ├── trash/
@@ -180,6 +181,14 @@ snapshot、changeset 或 revision。Tree Blob 和内嵌 Asset 共用注入的 `B
 本地目录，未来可替换为 `S3BlobStore` 或迁移包装器。Univer Collaboration Database Adapter
 独立管理协作数据。
 
+Office Exchange Module 使用已发布的 `@univerjs-pro/exchange-node` 将 Office 字节与 Univer
+数据互转。`/universer-api/exchange/**`、Exchange File Upload 和签名下载遵循 Universer
+协议形状，不进入产品 OpenAPI。导入为 Unit 时通过 Resource Module 创建 Personal Space
+根目录下的正式 Node/Resource/Unit；导出时通过 Collaboration SDK 的公开 Unit Runtime
+物化最新 Trunk snapshot 和 Sheet blocks，再交给 Exchange Node。转换源文件、JSON snapshot
+和导出文件是 `BlobStore` 中的临时对象，任务元数据只存在当前进程并在两小时后过期；它们
+不写入产品数据库，也不改变 Collaboration Database Adapter 的所有权边界。
+
 ## OpenAPI
 
 ```text

apps/workspace/generated/http/openapi.bundled.yaml

@@ -772,6 +772,29 @@ paths:
           $ref: '#/components/responses/Unauthorized'
         '404':
           $ref: '#/components/responses/NotFound'
+  /api/unit-resources/{unitId}:
+    parameters:
+      - name: unitId
+        in: path
+        required: true
+        schema:
+          type: string
+    get:
+      tags:
+        - Resources
+      operationId: getResourceByUnit
+      summary: Resolve Resource and owning Node metadata from a Univer Unit.
+      responses:
+        '200':
+          description: Current Resource and Node accessible to the signed-in User.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ResourceResponse'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
   /api/resources/{resourceId}/open:
     parameters:
       - name: resourceId

apps/workspace/generated/http/schema.d.ts

@@ -483,6 +483,25 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/unit-resources/{unitId}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                unitId: string;
+            };
+            cookie?: never;
+        };
+        /** Resolve Resource and owning Node metadata from a Univer Unit. */
+        get: operations["getResourceByUnit"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/resources/{resourceId}/open": {
         parameters: {
             query?: never;
@@ -2533,6 +2552,30 @@ export interface operations {
             404: components["responses"]["NotFound"];
         };
     };
+    getResourceByUnit: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                unitId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Current Resource and Node accessible to the signed-in User. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ResourceResponse"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            404: components["responses"]["NotFound"];
+        };
+    };
     openResource: {
         parameters: {
             query?: never;

apps/workspace/package.json

@@ -72,6 +72,8 @@
     "@univerjs-pro/embed-ui": "1.0.0-insiders.20260819-8595af2",
     "@univerjs-pro/engine-chart": "1.0.0-insiders.20260819-8595af2",
     "@univerjs-pro/engine-formula": "1.0.0-insiders.20260819-8595af2",
+    "@univerjs-pro/exchange-client": "1.0.0-insiders.20260819-8595af2",
+    "@univerjs-pro/exchange-node": "1.0.0-insiders.20260819-8595af2",
     "@univerjs-pro/ink": "1.0.0-insiders.20260819-8595af2",
     "@univerjs-pro/ink-ui": "1.0.0-insiders.20260819-8595af2",
     "@univerjs-pro/license": "1.0.0-insiders.20260819-8595af2",

apps/workspace/server/src/app.ts

@@ -9,6 +9,7 @@ import { openWorkspaceDatabase } from "./db/initialize.js";
 import {
   createCollaborationRuntime,
   type CollaborationRuntime,
+  type UnitSnapshotStore,
   type UnitStore,
 } from "./integrations/univer/unit-store.js";
 import { createWorktreeBackend } from "./integrations/univer/worktree-store.js";
@@ -97,6 +98,11 @@ import {
   UniverAssetsRepository,
   type UniverAssetsModule,
 } from "./modules/univer-assets/index.js";
+import {
+  createExchangeModule,
+  createExchangeRouter,
+  type ExchangeModule,
+} from "./modules/exchange/index.js";
 
 export interface WorkspaceApplication {
   readonly app: express.Express;
@@ -113,6 +119,7 @@ export interface WorkspaceApplication {
   readonly operations: OperationsModule;
   readonly blobs: BlobsModule;
   readonly univerAssets: UniverAssetsModule;
+  readonly exchange: ExchangeModule;
   attachWebSocket(server: Server): void;
   closeRealtime(): Promise<void>;
   close(): Promise<void>;
@@ -122,6 +129,7 @@ export function createWorkspaceApplication(
   config: WorkspaceConfig,
   dependencies: {
     readonly unitStore?: UnitStore;
+    readonly unitSnapshotStore?: UnitSnapshotStore;
     readonly worktreeBackend?: WorktreeBackend;
     readonly blobStore?: BlobStore;
     readonly githubOAuthProvider?: GitHubOAuthProvider;
@@ -136,6 +144,10 @@ export function createWorkspaceApplication(
     (collaboration = createCollaborationRuntime(
       config.collaborationDatabaseFilename
     )).unitStore;
+  const unitSnapshotStore =
+    dependencies.unitSnapshotStore ??
+    collaboration?.unitSnapshotStore ??
+    unavailableUnitSnapshotStore();
   const oauthStateSecret =
     dependencies.oauthStateSecret ??
     config.githubOAuth?.clientSecret ??
@@ -219,6 +231,13 @@ export function createWorkspaceApplication(
     resources,
     worktrees,
   });
+  const exchange = createExchangeModule({
+    access,
+    resources,
+    spaces,
+    snapshots: unitSnapshotStore,
+    store: blobStore,
+  });
   const collaborationGateway: CollaborationGateway | null = collaboration
     ? createCollaborationGateway({
         service: collaboration.service,
@@ -283,6 +302,10 @@ export function createWorkspaceApplication(
     "/api",
     createWorktreesRouter({ identity, worktrees })
   );
+  app.use(
+    "/universer-api",
+    createExchangeRouter({ identity, exchange })
+  );
   app.use(
     "/universer-api",
     createUniverAssetsRouter({ identity, assets: univerAssets })
@@ -318,6 +341,7 @@ export function createWorkspaceApplication(
     operations,
     blobs,
     univerAssets,
+    exchange,
     attachWebSocket(server) {
       collaborationGateway?.attachWebSocket(server);
     },
@@ -329,15 +353,29 @@ export function createWorkspaceApplication(
         await collaborationGateway?.dispose();
       } finally {
         try {
-          await collaboration?.dispose();
+          await exchange.dispose();
         } finally {
-          database.close();
+          try {
+            await collaboration?.dispose();
+          } finally {
+            database.close();
+          }
         }
       }
     },
   };
 }
 
+function unavailableUnitSnapshotStore(): UnitSnapshotStore {
+  return {
+    async materialize() {
+      throw new Error(
+        "A Collaboration snapshot store is required for Unit export."
+      );
+    },
+  };
+}
+
 function unavailableWorktreeBackend(): WorktreeBackend {
   const unavailable = async (): Promise<never> => {
     throw new Error(