Просмотр исходного кода

feat(case): 新增桌面端/AI 客户端案件副本接口,上传文件改为原名_雪花id

- 匿名接口 /case/public/list、/case/public/workspace、/case/public/aidesk:
  桌面端按案件生成 DuckDB 副本;AI 客户端生成 aidesk/{import,db} 副本,
  aidesk/case.json 说明两个目录用途,接口返回 caseId/name/aideskPath
- DuckDB 副本统一走 DuckdbSnapshot(ATTACH + COPY FROM DATABASE),
  兼容案件已打开(原库被持锁)与未打开两种场景,不直接复制原库文件
- 上传文件落盘名改为 原名_雪花id.ext(替代 UUID),所有上传入口统一走
  StorageLayout.storedFileName;同步 storage-layout 文档
- 匿名返回体用 VO 限定字段(PublicCaseInfoVO/PublicCaseWorkspaceVO/PublicAideskVO)
- 新增测试:公开 VO 字段边界、桌面工作区副本、storage 路径/命名与 aidesk 布局
cc 1 неделя назад
Родитель
Сommit
e19f94022b
18 измененных файлов с 891 добавлено и 40 удалено
  1. 9 0
      ai-server/src/main/java/com/zsjz/ai/common/config/SaTokenWebConfig.java
  2. 23 0
      ai-server/src/main/java/com/zsjz/ai/common/model/plat/dto/PublicAideskDTO.java
  3. 16 0
      ai-server/src/main/java/com/zsjz/ai/common/model/plat/dto/PublicCaseWorkspaceDTO.java
  4. 38 0
      ai-server/src/main/java/com/zsjz/ai/common/model/plat/vo/PublicAideskVO.java
  5. 35 0
      ai-server/src/main/java/com/zsjz/ai/common/model/plat/vo/PublicCaseInfoVO.java
  6. 40 0
      ai-server/src/main/java/com/zsjz/ai/common/model/plat/vo/PublicCaseWorkspaceVO.java
  7. 92 19
      ai-server/src/main/java/com/zsjz/ai/common/storage/StorageLayout.java
  8. 1 1
      ai-server/src/main/java/com/zsjz/ai/module/agent/attachment/ChatAttachmentService.java
  9. 1 1
      ai-server/src/main/java/com/zsjz/ai/module/dm/service/DmService.java
  10. 2 2
      ai-server/src/main/java/com/zsjz/ai/module/eds/service/EdsMaterialProcessService.java
  11. 1 1
      ai-server/src/main/java/com/zsjz/ai/module/knowledge/service/KnowledgeDocService.java
  12. 53 0
      ai-server/src/main/java/com/zsjz/ai/module/plat/controller/CaseInfoController.java
  13. 271 0
      ai-server/src/main/java/com/zsjz/ai/module/plat/service/CaseInfoService.java
  14. 54 0
      ai-server/src/test/java/com/zsjz/ai/common/model/plat/vo/PublicCaseInfoVOTest.java
  15. 55 0
      ai-server/src/test/java/com/zsjz/ai/common/model/plat/vo/PublicCaseWorkspaceVOTest.java
  16. 32 4
      ai-server/src/test/java/com/zsjz/ai/common/storage/StorageLayoutTest.java
  17. 156 0
      ai-server/src/test/java/com/zsjz/ai/module/plat/service/CaseInfoServicePublicWorkspaceTest.java
  18. 12 12
      docs/design/storage-layout.md

+ 9 - 0
ai-server/src/main/java/com/zsjz/ai/common/config/SaTokenWebConfig.java

@@ -48,6 +48,15 @@ public class SaTokenWebConfig implements WebMvcConfigurer {
             "/plugin/**",
             /* 本机技能市场:桌面端主进程匿名读取目录与技能文档。 */
             "/skill/**",
+            /*
+             * 桌面端案件库:PI-Desktop 没有平台登录态,只读取卡片用的 ID/名称,
+             * 并按案件生成桌面工作区数据库副本 / AI 客户端副本(aidesk)。
+             * 返回体分别由 PublicCaseInfoVO / PublicCaseWorkspaceVO / PublicAideskVO
+             * 限制字段;只放行这些明确路径,不把 /case/** 整体暴露出去。
+             */
+            "/case/public/list",
+            "/case/public/workspace",
+            "/case/public/aidesk",
             "/error",
     };
 

+ 23 - 0
ai-server/src/main/java/com/zsjz/ai/common/model/plat/dto/PublicAideskDTO.java

@@ -0,0 +1,23 @@
+package com.zsjz.ai.common.model.plat.dto;
+
+import lombok.Data;
+
+/**
+ * 匿名创建 AI 客户端工作区的请求 DTO。
+ *
+ * <p>AI 客户端没有平台登录态,按案件 ID 请求服务端生成一份 {@code aidesk} 副本:
+ * 上传原件复制到 {@code aidesk/import},DuckDB 由持锁方导出到 {@code aidesk/db}。
+ * 不接收密码或路径,避免匿名调用方指定任意文件。
+ */
+@Data
+public class PublicAideskDTO {
+
+    /** 案件 ID(雪花算法 Long,前端以字符串传递,避免 JS number 精度丢失) */
+    private Long id;
+
+    /**
+     * 可选:只复制指定上传批次的原件({@code imports/{batchId}})。
+     * 为空时复制案件下所有批次的文件(平铺到 {@code aidesk/import})。
+     */
+    private Long batchId;
+}

+ 16 - 0
ai-server/src/main/java/com/zsjz/ai/common/model/plat/dto/PublicCaseWorkspaceDTO.java

@@ -0,0 +1,16 @@
+package com.zsjz.ai.common.model.plat.dto;
+
+import lombok.Data;
+
+/**
+ * 匿名创建桌面端案件工作区的请求 DTO。
+ *
+ * <p>桌面端案件库没有平台登录态,只能按案件 ID 请求服务端生成一份数据库副本;
+ * 这里不接收密码或路径,避免匿名调用方影响案件归属或指定任意文件。
+ */
+@Data
+public class PublicCaseWorkspaceDTO {
+
+    /** 案件 ID(雪花算法 Long,前端以字符串传递,避免 JS number 精度丢失) */
+    private Long id;
+}

+ 38 - 0
ai-server/src/main/java/com/zsjz/ai/common/model/plat/vo/PublicAideskVO.java

@@ -0,0 +1,38 @@
+package com.zsjz.ai.common.model.plat.vo;
+
+import com.zsjz.ai.common.model.plat.entity.CaseInfo;
+import lombok.Data;
+
+import java.nio.file.Path;
+
+/**
+ * AI 客户端工作区副本。
+ *
+ * <p>只返回三个字段:
+ * <ol>
+ *   <li>{@code caseId}:案件 ID</li>
+ *   <li>{@code name}:案件名称</li>
+ *   <li>{@code aideskPath}:副本根目录,例如 {@code E:\data\cases\{caseId}\aidesk}</li>
+ * </ol>
+ * 目录内部的 {@code import/}、{@code db/case.duckdb} 由 {@code aidesk/case.json} 描述。
+ */
+@Data
+public class PublicAideskVO {
+
+    /** 案件 ID */
+    private Long caseId;
+
+    /** 案件名称 */
+    private String name;
+
+    /** AI 客户端工作区根目录:{@code cases/{caseId}/aidesk} */
+    private String aideskPath;
+
+    public static PublicAideskVO of(CaseInfo caseInfo, Path aideskDir) {
+        PublicAideskVO vo = new PublicAideskVO();
+        vo.setCaseId(caseInfo.getId());
+        vo.setName(caseInfo.getName());
+        vo.setAideskPath(aideskDir.toAbsolutePath().toString());
+        return vo;
+    }
+}

+ 35 - 0
ai-server/src/main/java/com/zsjz/ai/common/model/plat/vo/PublicCaseInfoVO.java

@@ -0,0 +1,35 @@
+package com.zsjz.ai.common.model.plat.vo;
+
+import com.zsjz.ai.common.model.plat.entity.CaseInfo;
+import lombok.Data;
+
+/**
+ * 匿名案件列表项。
+ *
+ * <p>桌面端(PI-Desktop)的案件库页面没有登录态,只能通过公开接口读取案件卡片。
+ * 该返回体刻意只暴露「ID + 名称」:案件密码、数据库路径、归属用户、备注,以及
+ * 服务器上的案件目录都不应离开服务端。桌面端打开工作区时另行调用工作区接口,
+ * 由服务端生成数据库副本并返回副本目录。
+ */
+@Data
+public class PublicCaseInfoVO {
+
+    /** 案件 ID(雪花算法 Long,前端按字符串处理) */
+    private Long id;
+
+    /** 案件名称 */
+    private String name;
+
+    /**
+     * 从案件实体构造公开列表项。
+     *
+     * @param caseInfo 案件实体
+     * @return 仅含公开字段的列表项
+     */
+    public static PublicCaseInfoVO from(CaseInfo caseInfo) {
+        PublicCaseInfoVO vo = new PublicCaseInfoVO();
+        vo.setId(caseInfo.getId());
+        vo.setName(caseInfo.getName());
+        return vo;
+    }
+}

+ 40 - 0
ai-server/src/main/java/com/zsjz/ai/common/model/plat/vo/PublicCaseWorkspaceVO.java

@@ -0,0 +1,40 @@
+package com.zsjz.ai.common.model.plat.vo;
+
+import com.zsjz.ai.common.model.plat.entity.CaseInfo;
+import lombok.Data;
+
+/**
+ * 桌面端案件工作区。
+ *
+ * <p>返回的 {@code workspacePath} 不是案件原目录,而是服务端刚生成的
+ * <b>数据库副本目录</b>:原库被 ai-server 的写锁持有,桌面端只有打开副本才能在
+ * 另一个进程里做 DuckDB 分析。副本布局与案件目录一致,数据库位于
+ * {@code db/case.duckdb}。
+ */
+@Data
+public class PublicCaseWorkspaceVO {
+
+    /** 案件 ID */
+    private Long caseId;
+
+    /** 案件名称(用于桌面端识别工作区来源) */
+    private String name;
+
+    /** 已创建完成的工作区目录(绝对路径) */
+    private String workspacePath;
+
+    /**
+     * 构造工作区返回体。
+     *
+     * @param caseInfo      案件实体
+     * @param workspacePath 已创建完成的工作区目录
+     * @return 工作区返回体
+     */
+    public static PublicCaseWorkspaceVO of(CaseInfo caseInfo, String workspacePath) {
+        PublicCaseWorkspaceVO vo = new PublicCaseWorkspaceVO();
+        vo.setCaseId(caseInfo.getId());
+        vo.setName(caseInfo.getName());
+        vo.setWorkspacePath(workspacePath);
+        return vo;
+    }
+}

+ 92 - 19
ai-server/src/main/java/com/zsjz/ai/common/storage/StorageLayout.java

@@ -1,6 +1,7 @@
 package com.zsjz.ai.common.storage;
 
 import cn.hutool.core.io.FileUtil;
+import cn.hutool.core.util.IdUtil;
 import cn.hutool.core.util.StrUtil;
 import com.zsjz.ai.common.constants.PathConst;
 import com.zsjz.ai.common.exception.ServerException;
@@ -13,7 +14,6 @@ import java.nio.charset.StandardCharsets;
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.nio.file.Paths;
-import java.util.UUID;
 
 /**
  * 业务文件存储布局(唯一路径来源)。
@@ -26,12 +26,12 @@ import java.util.UUID;
  * ├── cases/{caseId}/
  * │   ├── case.json
  * │   ├── db/case.duckdb
- * │   ├── imports/{batchId}/{uuid}{ext}
- * │   ├── materials/{packageId}/{uuid}.zip,extracted,media/{采集编号MD5}/{uuid}.ext}
- * │   ├── attachments/{uuid}{ext}
+ * │   ├── imports/{batchId}/{原名}_{雪花id}{ext}
+ * │   ├── materials/{packageId}/{原名}_{雪花id}.zip,extracted,media/{采集编号MD5}/{原名}_{雪花id}.ext}
+ * │   ├── attachments/{原名}_{雪花id}{ext}
  * │   ├── ai/{artifacts,sessions,agents,insight,python,graph}
  * │   └── tmp/
- * ├── users/{userId}/knowledge/{kbId}/docs/{uuid}{ext}(sidecar 同目录 .txt)
+ * ├── users/{userId}/knowledge/{kbId}/docs/{原名}_{雪花id}{ext}(sidecar 同目录 .txt)
  * ├── index/cases.tsv
  * └── tmp/
  * </pre>
@@ -57,6 +57,13 @@ public class StorageLayout {
     public static final String CASE_ATTACHMENTS_DIR = "attachments";
     public static final String CASE_AI_DIR = "ai";
     public static final String CASE_TMP_DIR = "tmp";
+    /** 桌面端工作区根:{@code cases/{caseId}/desktop}(只放派生副本,删案时随案件目录清理)。 */
+    public static final String CASE_DESKTOP_DIR = "desktop";
+
+    /** AI 客户端工作区根:{@code cases/{caseId}/aidesk}(导入副本 + 数据库副本,删案时随案件目录清理)。 */
+    public static final String CASE_AIDESK_DIR = "aidesk";
+    public static final String AIDESK_IMPORT_DIR = "import";
+    public static final String AIDESK_DB_DIR = "db";
 
     private static final String DRAFT_SESSION = "_draft";
     private static final int MAX_FILE_NAME_LENGTH = 120;
@@ -143,6 +150,58 @@ public class StorageLayout {
         return caseDir(caseId).resolve(CASE_DB_DIR).resolve(CASE_DB_FILE);
     }
 
+    /**
+     * 桌面端工作区根目录:{@code cases/{caseId}/desktop}。
+     *
+     * <p>桌面端不能直接打开案件原库(DuckDB 单文件被本进程写锁持有),
+     * 所以每次“打开工作区”都在这里生成一份独立副本,再把副本目录交给桌面端。
+     * 目录放在案件目录内,删案时随 {@link #deleteCase(long)} 一起清理。
+     */
+    public Path caseDesktopDir(long caseId) {
+        return caseDir(caseId).resolve(CASE_DESKTOP_DIR);
+    }
+
+    /** 单次桌面端工作区目录:{@code cases/{caseId}/desktop/{workspaceName}}。 */
+    public Path desktopWorkspaceDir(long caseId, String workspaceName) {
+        return caseDesktopDir(caseId).resolve(workspaceName);
+    }
+
+    /** 桌面端工作区里的案件库副本:{@code .../db/case.duckdb},相对布局与案件原库一致。 */
+    public Path desktopWorkspaceDb(long caseId, String workspaceName) {
+        return desktopWorkspaceDir(caseId, workspaceName).resolve(CASE_DB_DIR).resolve(CASE_DB_FILE);
+    }
+
+    /**
+     * AI 客户端工作区根目录:{@code cases/{caseId}/aidesk}。
+     *
+     * <p>给外部 AI 客户端使用的派生副本区:{@code import/} 放上传原件副本,
+     * {@code db/} 放由持锁方导出的 DuckDB 副本(不能直接复制原库,见
+     * {@code CaseInfoService#createAideskWorkspace})。删案时随案件目录一起清理。
+     */
+    public Path caseAideskDir(long caseId) {
+        return caseDir(caseId).resolve(CASE_AIDESK_DIR);
+    }
+
+    /** AI 客户端上传原件副本目录:{@code cases/{caseId}/aidesk/import}。 */
+    public Path aideskImportDir(long caseId) {
+        return caseAideskDir(caseId).resolve(AIDESK_IMPORT_DIR);
+    }
+
+    /** AI 客户端数据库副本目录:{@code cases/{caseId}/aidesk/db}。 */
+    public Path aideskDbDir(long caseId) {
+        return caseAideskDir(caseId).resolve(AIDESK_DB_DIR);
+    }
+
+    /** AI 客户端数据库副本文件:{@code cases/{caseId}/aidesk/db/case.duckdb}。 */
+    public Path aideskDb(long caseId) {
+        return aideskDbDir(caseId).resolve(CASE_DB_FILE);
+    }
+
+    /** AI 客户端工作区说明文件:{@code cases/{caseId}/aidesk/case.json}。 */
+    public Path aideskCaseJson(long caseId) {
+        return caseAideskDir(caseId).resolve("case.json");
+    }
+
     public Path caseManifest(long caseId) {
         return caseDir(caseId).resolve("case.json");
     }
@@ -156,8 +215,8 @@ public class StorageLayout {
     }
 
     /**
-     * 清洗导入文件相对路径:{@code cases/{caseId}/imports/{batchId}/{uuid}{ext}}。
-     * <p>磁盘统一 UUID 重命名,源文件名由 {@code file_info.file_name} 保存用于展示。</p>
+     * 清洗导入文件相对路径:{@code cases/{caseId}/imports/{batchId}/{原名}_{雪花id}{ext}}。
+     * <p>磁盘统一重命名为「原名_雪花id」,源文件名由 {@code file_info.file_name} 保存用于展示。</p>
      */
     public String importFile(long caseId, long batchId, String originalName) {
         return relative(importBatchDir(caseId, batchId).resolve(storedFileName(originalName)));
@@ -183,9 +242,9 @@ public class StorageLayout {
     }
 
     /**
-     * 人员头像相对路径:{@code attachments/{uuid}{ext}}。
+     * 人员头像相对路径:{@code attachments/{原名}_{雪花id}{ext}}。
      *
-     * <p>磁盘统一 UUID 重命名;人员与文件的关联以 {@code person_basic_info.photograph} 为准,
+     * <p>磁盘统一重命名为「原名_雪花id」;人员与文件的关联以 {@code person_basic_info.photograph} 为准,
      * 不按人建目录,也不把源文件名带进路径。</p>
      */
     public String personPhoto(long caseId, String originalName) {
@@ -204,7 +263,7 @@ public class StorageLayout {
     }
 
     /**
-     * 对话附件相对路径:{@code ai/sessions/{sessionId}/attachments/{uuid}{ext}}。
+     * 对话附件相对路径:{@code ai/sessions/{sessionId}/attachments/{原名}_{雪花id}{ext}}。
      */
     public String sessionAttachment(long caseId, Long sessionId, String originalName) {
         return relative(sessionAttachmentsDir(caseId, sessionId).resolve(storedFileName(originalName)));
@@ -337,9 +396,9 @@ public class StorageLayout {
     }
 
     /**
-     * 知识库文档相对路径:{@code users/{userId}/knowledge/{kbId}/docs/{uuid}{ext}}。
+     * 知识库文档相对路径:{@code users/{userId}/knowledge/{kbId}/docs/{原名}_{雪花id}{ext}}。
      *
-     * <p>磁盘统一 UUID 重命名;源文件名由 {@code knowledge_doc.file_name} 保存用于展示。
+     * <p>磁盘统一重命名为「原名_雪花id」;源文件名由 {@code knowledge_doc.file_name} 保存用于展示。
      * 全文 sidecar 与原件同目录、同名换 {@code .txt}。</p>
      */
     public String knowledgeDoc(long userId, long kbId, String originalName) {
@@ -429,16 +488,30 @@ public class StorageLayout {
         return DigestUtils.md5DigestAsHex(value.getBytes(StandardCharsets.UTF_8));
     }
 
-    public static String randomId() {
-        return UUID.randomUUID().toString().replace("-", "");
-    }
-
     /**
-     * 磁盘落盘名:UUID + 原扩展名。所有上传文件统一用该规则重命名,
-     * 源文件名只保存在业务表中用于展示。
+     * 磁盘落盘名:{@code 原始文件名_雪花ID + 原扩展名}。
+     *
+     * <p>所有上传文件统一用该规则重命名:磁盘上保留可读的原文件名,雪花 ID 保证唯一;
+     * 源文件名同时也保存在业务表中,用于列表展示与下载。
+     *
+     * <p>原文件名会先经过 {@link #safeName(String)} 清洗(去路径分隔符/非法字符、限长),
+     * 再为 {@code _雪花ID} 留出长度预算,避免 Windows 路径超长。
      */
     public static String storedFileName(String originalName) {
-        return randomId() + extensionOf(originalName);
+        String safe = safeName(originalName);
+        String ext = extensionOf(safe);
+        String base = ext.isEmpty() ? safe : safe.substring(0, safe.length() - ext.length());
+        // "_" + 19 位雪花 ID 约 20 字符;给主体留出预算
+        int maxBase = Math.max(1, MAX_FILE_NAME_LENGTH - 20 - ext.length());
+        if (base.length() > maxBase) {
+            base = base.substring(0, maxBase);
+        }
+        // Windows 不允许文件名以点或空格结尾
+        base = base.replaceAll("[. ]+$", "");
+        if (StrUtil.isBlank(base)) {
+            base = "file";
+        }
+        return base + "_" + IdUtil.getSnowflakeNextId() + ext;
     }
 
     /**

+ 1 - 1
ai-server/src/main/java/com/zsjz/ai/module/agent/attachment/ChatAttachmentService.java

@@ -285,7 +285,7 @@ public class ChatAttachmentService {
     }
 
     private Path allocate(Path dir, String safeName) {
-        // 磁盘统一 UUID 重命名;ChatAttachment.fileName 保存源文件名用于展示
+        // 磁盘统一重命名为「原名_雪花id」;ChatAttachment.fileName 保存源文件名用于展示
         Path target = dir.resolve(StorageLayout.storedFileName(safeName)).normalize();
         if (!target.startsWith(dir)) {
             throw new ServerException(400, "非法文件名: " + safeName);

+ 1 - 1
ai-server/src/main/java/com/zsjz/ai/module/dm/service/DmService.java

@@ -496,7 +496,7 @@ public class DmService {
         Path dir = storageLayout.importBatchDir(caseId, batchId);
         try {
             Files.createDirectories(dir);
-            // 磁盘统一 UUID 重命名;源文件名只落 file_info.file_name 用于展示
+            // 磁盘统一重命名为「原名_雪花id」;源文件名只落 file_info.file_name 用于展示
             Path target = dir.resolve(StorageLayout.storedFileName(originalName)).normalize();
             if (!target.startsWith(dir)) {
                 throw ServerException.build("非法文件名:" + originalName);

+ 2 - 2
ai-server/src/main/java/com/zsjz/ai/module/eds/service/EdsMaterialProcessService.java

@@ -325,8 +325,8 @@ public class EdsMaterialProcessService {
     }
 
     /**
-     * 落盘到 {@code cases/{caseId}/materials/{id}/{uuid}.zip}。
-     * 磁盘统一 UUID 重命名;源文件名保存在 {@code eds_material_process.file_name} 用于展示。
+     * 落盘到 {@code cases/{caseId}/materials/{id}/{原名}_{雪花id}.zip}。
+     * 磁盘统一重命名为「原名_雪花id」;源文件名保存在 {@code eds_material_process.file_name} 用于展示。
      */
     private Path saveZip(MultipartFile file, Long caseId, Long id, String originalName) {
         Path dir = storageLayout.materialDir(caseId, id);

+ 1 - 1
ai-server/src/main/java/com/zsjz/ai/module/knowledge/service/KnowledgeDocService.java

@@ -114,7 +114,7 @@ public class KnowledgeDocService extends ServiceImpl<KnowledgeDocMapper, Knowled
             throw new ServerException(400, "该知识库下我的文档数已达上限(" + props.getMaxDocsPerUser() + ")");
         }
 
-        // 原件落盘:users/{userId}/knowledge/{kbId}/docs/{uuid}{ext}(保持原命名逻辑)
+        // 原件落盘:users/{userId}/knowledge/{kbId}/docs/{原名}_{雪花id}{ext}
         String filePath = storageLayout.knowledgeDoc(userId, kbId, safeName);
         try {
             storageUtil.upload(file, filePath);

+ 53 - 0
ai-server/src/main/java/com/zsjz/ai/module/plat/controller/CaseInfoController.java

@@ -2,8 +2,13 @@ package com.zsjz.ai.module.plat.controller;
 
 import com.zsjz.ai.common.config.Result;
 import com.zsjz.ai.common.model.plat.dto.OpenCaseDTO;
+import com.zsjz.ai.common.model.plat.dto.PublicAideskDTO;
+import com.zsjz.ai.common.model.plat.dto.PublicCaseWorkspaceDTO;
 import com.zsjz.ai.common.model.plat.dto.UpdateCasePwdDTO;
 import com.zsjz.ai.common.model.plat.entity.CaseInfo;
+import com.zsjz.ai.common.model.plat.vo.PublicAideskVO;
+import com.zsjz.ai.common.model.plat.vo.PublicCaseInfoVO;
+import com.zsjz.ai.common.model.plat.vo.PublicCaseWorkspaceVO;
 import com.zsjz.ai.module.plat.service.CaseInfoService;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.web.bind.annotation.RestController;
@@ -31,6 +36,54 @@ public class CaseInfoController {
     @Autowired
     private CaseInfoService caseInfoService;
 
+    /**
+     * 匿名案件列表(桌面端案件库使用)。
+     *
+     * <p>该路径在 {@code SaTokenWebConfig} 的白名单里,不需要登录;返回体也
+     * 只包含卡片所需的名称、ID 与工作区目录,避免把密码、数据库路径等
+     * 敏感字段暴露给匿名请求。
+     *
+     * @return 平台内全部案件的公开信息
+     */
+    @GetMapping("/public/list")
+    public Result<List<PublicCaseInfoVO>> publicList() {
+        return Result.succeed(caseInfoService.listPublicCases());
+    }
+
+    /**
+     * 匿名创建桌面端案件工作区。
+     *
+     * <p>桌面端不能直接打开案件原库(DuckDB 单文件被本进程写锁持有),
+     * 这里按案件 ID 生成一份独立数据库副本,并返回副本目录。该路径也在
+     * {@code SaTokenWebConfig} 白名单里;不接收密码、路径等可写参数。
+     *
+     * @param dto 案件 ID(JSON body)
+     * @return 已创建完成的工作区目录
+     */
+    @PostMapping("/public/workspace")
+    public Result<PublicCaseWorkspaceVO> publicWorkspace(@RequestBody PublicCaseWorkspaceDTO dto) {
+        return Result.succeed(caseInfoService.createPublicWorkspace(dto == null ? null : dto.getId()));
+    }
+
+    /**
+     * 匿名创建 AI 客户端工作区(上传原件 + DuckDB 副本)。
+     *
+     * <p>AI 客户端没有平台登录态,按案件 ID 生成固定目录
+     * {@code cases/{caseId}/aidesk/}:{@code import/} 放上传原件副本,
+     * {@code db/case.duckdb} 放由持锁方导出的 DuckDB 副本(不能直接复制原库)。
+     * 该路径在 {@code SaTokenWebConfig} 的登录白名单里;请求体只接收案件 ID
+     * 与可选批次 ID,不接受路径/密码。
+     *
+     * @param dto 案件 ID + 可选上传批次 ID
+     * @return caseId / name / aideskPath 三个字段
+     */
+    @PostMapping("/public/aidesk")
+    public Result<PublicAideskVO> publicAidesk(@RequestBody PublicAideskDTO dto) {
+        return Result.succeed(caseInfoService.createAideskWorkspace(
+                dto == null ? null : dto.getId(),
+                dto == null ? null : dto.getBatchId()));
+    }
+
     /**
      * 查询案件列表(仅当前登录用户自己的案件)
      *

+ 271 - 0
ai-server/src/main/java/com/zsjz/ai/module/plat/service/CaseInfoService.java

@@ -10,21 +10,36 @@ import com.zsjz.ai.common.constants.PathConst;
 import com.zsjz.ai.common.context.CaseContextHolder;
 import com.zsjz.ai.common.datasource.CaseActivityProbe;
 import com.zsjz.ai.common.datasource.CaseDataSourceRegistry;
+import com.zsjz.ai.common.datasource.DuckdbSnapshot;
 import com.zsjz.ai.common.exception.ServerException;
 import com.zsjz.ai.common.model.plat.dto.UpdateCasePwdDTO;
 import com.zsjz.ai.common.model.plat.entity.CaseInfo;
+import com.zsjz.ai.common.model.plat.vo.PublicAideskVO;
+import com.zsjz.ai.common.model.plat.vo.PublicCaseInfoVO;
+import com.zsjz.ai.common.model.plat.vo.PublicCaseWorkspaceVO;
 import com.zsjz.ai.common.storage.CaseStorageManifest;
 import com.zsjz.ai.common.storage.StorageLayout;
+import com.zsjz.ai.common.utils.Json;
 import com.zsjz.ai.common.utils.StateManager;
 import com.zsjz.ai.module.plat.mapper.CaseInfoMapper;
 import com.zsjz.ai.module.search.service.SearchDocIndexService;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.stereotype.Service;
 
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
 import java.nio.file.Files;
 import java.nio.file.Path;
+import java.nio.file.StandardCopyOption;
+import java.sql.Connection;
+import java.sql.DriverManager;
 import java.time.LocalDateTime;
+import java.util.LinkedHashMap;
 import java.util.List;
+import java.util.Map;
+import java.util.UUID;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.stream.Stream;
 
 /**
  * 案件服务。
@@ -63,6 +78,12 @@ public class CaseInfoService extends ServiceImpl<CaseInfoMapper, CaseInfo> {
      */
     private final List<CaseActivityProbe> activityProbes;
 
+    /**
+     * 同一案件的桌面端工作区创建串行化:并发点击/多端同时打开时,避免两个连接
+     * 同时争抢源库或重复导出。不同案件之间互不阻塞。
+     */
+    private final Map<Long, Object> workspaceCreationLocks = new ConcurrentHashMap<>();
+
     public CaseInfoService(CaseDataSourceRegistry caseDataSourceRegistry, SseService sseService,
                            SearchDocIndexService searchDocIndexService,
                            CaseDataCleanupService caseDataCleanupService,
@@ -90,6 +111,256 @@ public class CaseInfoService extends ServiceImpl<CaseInfoMapper, CaseInfo> {
         return list;
     }
 
+    /**
+     * 匿名案件列表(桌面端案件库使用)。
+     *
+     * <p>只返回卡片需要的 ID 与名称,不读取登录态,也不暴露密码、数据库路径、
+     * 归属用户或服务器上的案件目录。桌面端打开工作区时再调用
+     * {@link #createPublicWorkspace(Long)} 生成数据库副本。
+     */
+    public List<PublicCaseInfoVO> listPublicCases() {
+        return lambdaQuery()
+                .orderByDesc(CaseInfo::getId)
+                .list()
+                .stream()
+                .map(PublicCaseInfoVO::from)
+                .toList();
+    }
+
+    /**
+     * 为桌面端创建一份独立的案件工作区(含数据库副本)。
+     *
+     * <p><b>为什么不直接返回案件原目录</b>:DuckDB 单文件只允许一个进程写打开,
+     * 且本进程持写锁时其它进程连只读都打不开。桌面端要在自己的进程/子进程里做
+     * DuckDB 分析,必须使用副本;副本由持锁方导出,才能保证读到一致的数据。
+     *
+     * <p>导出复用 {@link DuckdbSnapshot}({@code ATTACH + COPY FROM DATABASE}):
+     * 案件已在本进程打开时走 {@link CaseDataSourceRegistry#exportSnapshot};
+     * 案件未打开时没有写锁,临时直连源库导出,若与并发开案冲突再让持锁方重试一次。
+     *
+     * <p>每次调用生成一个带短随机后缀的新目录,避免同一案件的多次打开互相覆盖;
+     * 目录位于 {@code cases/{caseId}/desktop/} 下,删案时随案件目录一起清理。
+     *
+     * @param caseId 案件 ID
+     * @return 已创建完成的工作区信息(路径为副本目录,不是案件原目录)
+     */
+    public PublicCaseWorkspaceVO createPublicWorkspace(Long caseId) {
+        if (caseId == null || caseId <= 0) {
+            throw new ServerException(400, "案件ID不能为空!");
+        }
+        CaseInfo caseInfo = getById(caseId);
+        if (caseInfo == null) {
+            throw new ServerException(404, "案件不存在!");
+        }
+        // 复用与开案相同的库文件校验:缺失/空文件在这里就报可读错误,
+        // 不要让 DuckDB 在目标目录静默建一个空库。
+        Path sourceDb = validateCaseDbPath(caseInfo);
+        String workspaceName = desktopWorkspaceName(caseInfo);
+        Path workspaceDir = storageLayout.desktopWorkspaceDir(caseId, workspaceName);
+        Path targetDb = storageLayout.desktopWorkspaceDb(caseId, workspaceName);
+
+        Object lock = workspaceCreationLocks.computeIfAbsent(caseId, key -> new Object());
+        boolean exported;
+        synchronized (lock) {
+            exported = caseDataSourceRegistry.isOpen(caseId)
+                    ? caseDataSourceRegistry.exportSnapshot(caseId, targetDb)
+                    : exportStandaloneSnapshot(sourceDb, targetDb)
+                    || caseDataSourceRegistry.exportSnapshot(caseId, targetDb);
+            if (!exported) {
+                // 导出失败时不留半成品目录(DuckdbSnapshot 自身会清理临时文件)
+                FileUtil.del(workspaceDir.toFile());
+                throw new ServerException(500, "案件工作区创建失败,请稍后重试");
+            }
+        }
+        log.info("桌面端案件工作区已创建: caseId={}, workspace={}", caseId, workspaceDir);
+        return PublicCaseWorkspaceVO.of(caseInfo, workspaceDir.toString());
+    }
+
+    /**
+     * 为外部 AI 客户端创建案件副本工作区。
+     *
+     * <p>目录固定为 {@code cases/{caseId}/aidesk/}:
+     * <ul>
+     *   <li>{@code import/}:上传原件副本。{@code batchId} 为空时复制案件下所有批次的文件
+     *       (平铺),指定时只复制该批次;每次调用先清空旧副本,AI 端不会读到已删除文件。</li>
+     *   <li>{@code db/}:DuckDB 案件库副本。<b>不能直接复制原库</b>:DuckDB 单文件只允许
+     *       一个进程写打开,原库被 ai-server 持锁时其它进程连只读都打不开,直接复制还可能
+     *       拿到不一致的中间状态。这里复用 {@link DuckdbSnapshot}({@code ATTACH + COPY FROM
+     *       DATABASE}):案件已在本进程打开时由持锁方导出;未打开时临时直连源库导出,
+     *       若与并发开案冲突再让持锁方重试一次。</li>
+     * </ul>
+     *
+     * <p>同一案件的副本创建串行化,避免并发调用互相覆盖。
+     *
+     * @param caseId  案件 ID
+     * @param batchId 可选:只复制指定上传批次;为空复制全部批次
+     * @return 副本目录与复制文件数
+     */
+    public PublicAideskVO createAideskWorkspace(Long caseId, Long batchId) {
+        if (caseId == null || caseId <= 0) {
+            throw new ServerException(400, "案件ID不能为空!");
+        }
+        CaseInfo caseInfo = getById(caseId);
+        if (caseInfo == null) {
+            throw new ServerException(404, "案件不存在!");
+        }
+        Path sourceDb = validateCaseDbPath(caseInfo);
+        Path aideskDir = storageLayout.caseAideskDir(caseId);
+        Path importDir = storageLayout.aideskImportDir(caseId);
+        Path dbDir = storageLayout.aideskDbDir(caseId);
+        Path targetDb = storageLayout.aideskDb(caseId);
+
+        Object lock = workspaceCreationLocks.computeIfAbsent(caseId, key -> new Object());
+        int copied;
+        synchronized (lock) {
+            try {
+                // 每次刷新:清掉上一次的导入副本,避免 AI 端读到已删除/旧文件
+                FileUtil.del(importDir.toFile());
+                Files.createDirectories(importDir);
+                copied = copyImportFiles(caseId, batchId, importDir);
+                Files.createDirectories(dbDir);
+                boolean exported = caseDataSourceRegistry.isOpen(caseId)
+                        ? caseDataSourceRegistry.exportSnapshot(caseId, targetDb)
+                        : exportStandaloneSnapshot(sourceDb, targetDb)
+                                || caseDataSourceRegistry.exportSnapshot(caseId, targetDb);
+                if (!exported) {
+                    throw new ServerException(500,
+                            "AI 客户端数据库副本创建失败:请确认 aidesk 目录(尤其 db/case.duckdb)"
+                                    + "未被其他进程占用,且案件原库未被其他进程锁住后重试");
+                }
+                writeAideskCaseJson(caseId, caseInfo, copied);
+            } catch (IOException e) {
+                throw new ServerException(500, "AI 客户端工作区创建失败: " + e.getMessage());
+            }
+        }
+        log.info("AI 客户端工作区已创建: caseId={}, batchId={}, importFiles={}, db={}",
+                caseId, batchId, copied, targetDb);
+        return PublicAideskVO.of(caseInfo, aideskDir);
+    }
+
+    /**
+     * 写 {@code aidesk/case.json}:给 AI 客户端说明 import/db 两个目录的用途。
+     *
+     * <p>路径全部写相对 {@code aidesk/} 的相对路径,客户端拿到目录后可直接拼接;
+     * 同时带案件 ID/名称、生成时间与导入文件数,便于 AI 判断副本是否最新。
+     */
+    private void writeAideskCaseJson(Long caseId, CaseInfo caseInfo, int importFileCount)
+            throws IOException {
+        Map<String, Object> meta = new LinkedHashMap<>();
+        // 雪花 ID 用字符串,避免 AI 客户端按 JS number 解析丢精度
+        meta.put("caseId", String.valueOf(caseInfo.getId()));
+        meta.put("caseName", caseInfo.getName());
+        meta.put("createdAt", LocalDateTime.now().toString());
+        meta.put("description", "AI 客户端案件副本工作区:import/ 是上传原件副本,db/ 是 DuckDB 案件库副本。");
+        Map<String, Object> importMeta = new LinkedHashMap<>();
+        importMeta.put("path", "import");
+        importMeta.put("description", "上传原件副本(CSV/XLSX/文档/图片等),可直接读取;每次生成工作区会刷新。");
+        importMeta.put("fileCount", importFileCount);
+        Map<String, Object> dbMeta = new LinkedHashMap<>();
+        dbMeta.put("path", "db");
+        dbMeta.put("dbFile", "db/case.duckdb");
+        dbMeta.put("description",
+                "DuckDB 案件库副本,请只读打开;不要访问案件原库(原库被服务进程写锁持有)。");
+        Map<String, Object> dirs = new LinkedHashMap<>();
+        dirs.put("import", importMeta);
+        dirs.put("db", dbMeta);
+        meta.put("directories", dirs);
+        meta.put("usage", "读取原始文件用 import/;DuckDB 查询用 db/case.duckdb。");
+        Files.writeString(storageLayout.aideskCaseJson(caseId), Json.toStr(meta),
+                StandardCharsets.UTF_8);
+    }
+
+    /**
+     * 复制上传原件到 {@code aidesk/import}。
+     *
+     * <p>上传目录下的文件都是平铺的;指定批次只复制该目录,未指定时遍历全部批次。
+     * 跨批次同名时追加 {@code -N},避免平铺覆盖(新命名带雪花 ID,正常不会撞名)。
+     */
+    private int copyImportFiles(Long caseId, Long batchId, Path targetDir) throws IOException {
+        Path importsRoot = storageLayout.caseImportsDir(caseId);
+        if (!Files.isDirectory(importsRoot)) {
+            return 0;
+        }
+        List<Path> batchDirs;
+        if (batchId != null) {
+            Path batchDir = storageLayout.importBatchDir(caseId, batchId);
+            if (!Files.isDirectory(batchDir)) {
+                throw new ServerException(404, "上传批次不存在: " + batchId);
+            }
+            batchDirs = List.of(batchDir);
+        } else {
+            try (Stream<Path> stream = Files.list(importsRoot)) {
+                batchDirs = stream.filter(Files::isDirectory)
+                        .filter(path -> !Files.isSymbolicLink(path))
+                        .sorted()
+                        .toList();
+            }
+        }
+        int count = 0;
+        for (Path batchDir : batchDirs) {
+            try (Stream<Path> stream = Files.list(batchDir)) {
+                List<Path> files = stream.filter(Files::isRegularFile)
+                        .filter(path -> !Files.isSymbolicLink(path))
+                        .sorted()
+                        .toList();
+                for (Path file : files) {
+                    Path target = targetDir.resolve(file.getFileName().toString());
+                    if (Files.exists(target)) {
+                        target = uniqueCopyTarget(targetDir, file.getFileName().toString());
+                    }
+                    Files.copy(file, target, StandardCopyOption.REPLACE_EXISTING);
+                    count++;
+                }
+            }
+        }
+        return count;
+    }
+
+    /** 平铺复制时的同名兜底:{@code name-1.ext}、{@code name-2.ext}… */
+    private static Path uniqueCopyTarget(Path dir, String name) {
+        int dot = name.lastIndexOf('.');
+        String base = dot > 0 ? name.substring(0, dot) : name;
+        String ext = dot > 0 ? name.substring(dot) : "";
+        for (int i = 1; i < 1000; i++) {
+            Path candidate = dir.resolve(base + "-" + i + ext);
+            if (!Files.exists(candidate)) {
+                return candidate;
+            }
+        }
+        return dir.resolve(base + "-"
+                + UUID.randomUUID().toString().replace("-", "").substring(0, 8) + ext);
+    }
+
+    /**
+     * 案件未在本进程打开时,直接连源库导出副本。
+     *
+     * <p>没有写锁时这是安全窗口;连接用读写模式,让 DuckDB 能重放可能存在的 WAL。
+     * 若与并发开案冲突而失败,调用方会再让持锁方导一次。
+     */
+    private boolean exportStandaloneSnapshot(Path sourceDb, Path targetDb) {
+        try (Connection con = DriverManager.getConnection("jdbc:duckdb:" + sourceDb)) {
+            return DuckdbSnapshot.export(con, targetDb);
+        } catch (Exception e) {
+            log.warn("直连案件库导出副本失败,将尝试由持锁方导出: db={}, error={}",
+                    sourceDb, e.getMessage());
+            return false;
+        }
+    }
+
+    /**
+     * 工作区目录名:案件名 + 8 位随机后缀。
+     *
+     * <p>桌面端把工作区目录当作项目名展示,所以保留可读的案件名(去掉 Windows
+     * 非法字符并限长);随机后缀保证同一案件多次打开不互相覆盖。
+     */
+    private static String desktopWorkspaceName(CaseInfo caseInfo) {
+        String base = StorageLayout.safeName(caseInfo.getName());
+        if (base.length() > 40) {
+            base = base.substring(0, 40);
+        }
+        return base + "-" + UUID.randomUUID().toString().replace("-", "").substring(0, 8);
+    }
+
     /**
      * 案件工作空间目录:{@code <root>/qingjian/data/cases/<案件ID>}。
      *

+ 54 - 0
ai-server/src/test/java/com/zsjz/ai/common/model/plat/vo/PublicCaseInfoVOTest.java

@@ -0,0 +1,54 @@
+package com.zsjz.ai.common.model.plat.vo;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.zsjz.ai.common.model.plat.entity.CaseInfo;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import java.util.Set;
+import java.util.TreeSet;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+
+/**
+ * 匿名案件列表返回体的字段边界测试。
+ *
+ * <p>该接口在 Sa-Token 白名单里,任何匿名请求都能读到。这里锁定序列化后的
+ * 字段集合,防止后续有人为了方便把实体直接挂进返回体,把密码、数据库路径
+ * 或归属用户带出去。
+ */
+class PublicCaseInfoVOTest {
+
+    private final ObjectMapper objectMapper = new ObjectMapper();
+
+    @Test
+    @DisplayName("匿名列表只序列化 id 与 name")
+    void serializesOnlyPublicFields() throws Exception {
+        CaseInfo caseInfo = new CaseInfo();
+        caseInfo.setId(1001L);
+        caseInfo.setName("海天专案");
+        caseInfo.setPwd("secret");
+        caseInfo.setDb("case.duckdb");
+        caseInfo.setDbPath("cases/1001/db/case.duckdb");
+        caseInfo.setOwnerId(7L);
+        caseInfo.setRemark("内部备注");
+
+        PublicCaseInfoVO vo = PublicCaseInfoVO.from(caseInfo);
+        JsonNode json = objectMapper.readTree(objectMapper.writeValueAsString(vo));
+
+        Set<String> fields = new TreeSet<>();
+        json.fieldNames().forEachRemaining(fields::add);
+
+        assertEquals(Set.of("id", "name"), fields);
+        assertEquals(1001L, json.get("id").asLong());
+        assertEquals("海天专案", json.get("name").asText());
+        assertFalse(json.has("workspacePath"));
+        assertFalse(json.has("pwd"));
+        assertFalse(json.has("db"));
+        assertFalse(json.has("dbPath"));
+        assertFalse(json.has("ownerId"));
+        assertFalse(json.has("remark"));
+    }
+}

+ 55 - 0
ai-server/src/test/java/com/zsjz/ai/common/model/plat/vo/PublicCaseWorkspaceVOTest.java

@@ -0,0 +1,55 @@
+package com.zsjz.ai.common.model.plat.vo;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.zsjz.ai.common.model.plat.entity.CaseInfo;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import java.util.Set;
+import java.util.TreeSet;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+
+/**
+ * 匿名工作区返回体的字段边界测试。
+ *
+ * <p>工作区接口也是匿名可调用的;返回体只允许暴露案件 ID、名称和新生成的
+ * 副本目录,不能把原库路径、密码或归属用户带出去。
+ */
+class PublicCaseWorkspaceVOTest {
+
+    private final ObjectMapper objectMapper = new ObjectMapper();
+
+    @Test
+    @DisplayName("工作区返回体只序列化 caseId、name 与 workspacePath")
+    void serializesOnlyPublicFields() throws Exception {
+        CaseInfo caseInfo = new CaseInfo();
+        caseInfo.setId(1001L);
+        caseInfo.setName("海天专案");
+        caseInfo.setPwd("secret");
+        caseInfo.setDb("case.duckdb");
+        caseInfo.setDbPath("cases/1001/db/case.duckdb");
+        caseInfo.setOwnerId(7L);
+        caseInfo.setRemark("内部备注");
+
+        PublicCaseWorkspaceVO vo = PublicCaseWorkspaceVO.of(
+                caseInfo, "E:/data/cases/1001/desktop/海天专案-abcd1234");
+        JsonNode json = objectMapper.readTree(objectMapper.writeValueAsString(vo));
+
+        Set<String> fields = new TreeSet<>();
+        json.fieldNames().forEachRemaining(fields::add);
+
+        assertEquals(Set.of("caseId", "name", "workspacePath"), fields);
+        assertEquals(1001L, json.get("caseId").asLong());
+        assertEquals("海天专案", json.get("name").asText());
+        assertEquals("E:/data/cases/1001/desktop/海天专案-abcd1234",
+                json.get("workspacePath").asText());
+        assertFalse(json.has("pwd"));
+        assertFalse(json.has("db"));
+        assertFalse(json.has("dbPath"));
+        assertFalse(json.has("ownerId"));
+        assertFalse(json.has("remark"));
+    }
+}

+ 32 - 4
ai-server/src/test/java/com/zsjz/ai/common/storage/StorageLayoutTest.java

@@ -8,6 +8,7 @@ import org.junit.jupiter.api.io.TempDir;
 import java.nio.file.Path;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotEquals;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
@@ -32,19 +33,46 @@ class StorageLayoutTest {
         String imported = layout.importFile(42, 7, "报告.xlsx");
         assertTrue(imported.startsWith("cases/42/imports/7/"), imported);
         assertTrue(imported.endsWith(".xlsx"), imported);
-        assertTrue(Path.of(imported).getFileName().toString().matches("[0-9a-f]{32}\\.xlsx"), imported);
+        assertTrue(Path.of(imported).getFileName().toString().matches("报告_\\d+\\.xlsx"), imported);
 
         String attachment = layout.sessionAttachment(42, 0L, "a.txt");
         assertTrue(attachment.startsWith("cases/42/ai/sessions/_draft/attachments/"), attachment);
-        assertTrue(Path.of(attachment).getFileName().toString().matches("[0-9a-f]{32}\\.txt"), attachment);
+        assertTrue(Path.of(attachment).getFileName().toString().matches("a_\\d+\\.txt"), attachment);
 
         String photo = layout.personPhoto(42, "头像.png");
         assertTrue(photo.startsWith("cases/42/attachments/"), photo);
-        assertTrue(Path.of(photo).getFileName().toString().matches("[0-9a-f]{32}\\.png"), photo);
+        assertTrue(Path.of(photo).getFileName().toString().matches("头像_\\d+\\.png"), photo);
 
         String docPath = layout.knowledgeDoc(1, 2, "a.pdf");
         assertTrue(docPath.startsWith("users/1/knowledge/2/docs/"), docPath);
-        assertTrue(Path.of(docPath).getFileName().toString().matches("[0-9a-f]{32}\\.pdf"), docPath);
+        assertTrue(Path.of(docPath).getFileName().toString().matches("a_\\d+\\.pdf"), docPath);
+    }
+
+    @Test
+    void aideskPathsStayInsideCaseDir() {
+        StorageLayout layout = layout();
+        Path aidesk = tempDir.resolve("cases/42/aidesk").toAbsolutePath().normalize();
+        assertEquals(aidesk, layout.caseAideskDir(42));
+        assertEquals(aidesk.resolve("import"), layout.aideskImportDir(42));
+        assertEquals(aidesk.resolve("db"), layout.aideskDbDir(42));
+        assertEquals(aidesk.resolve("db/case.duckdb"), layout.aideskDb(42));
+        assertEquals(aidesk.resolve("case.json"), layout.aideskCaseJson(42));
+    }
+
+    @Test
+    void storedFileNameKeepsOriginalNameAndAddsSnowflakeId() {
+        String name = StorageLayout.storedFileName("../../a:b.txt");
+        assertTrue(name.matches("a_b_\\d+\\.txt"), name);
+
+        assertTrue(StorageLayout.storedFileName(null).matches("file_\\d+"), "空文件名回退 file");
+        assertTrue(StorageLayout.storedFileName("报告.xlsx").matches("报告_\\d+\\.xlsx"), "保留中文原名");
+
+        // 雪花 id 保证唯一
+        assertNotEquals(StorageLayout.storedFileName("a.txt"), StorageLayout.storedFileName("a.txt"));
+
+        // 超长原名截断后总长度仍受控(Windows 路径安全)
+        String longName = "很长的文件名".repeat(40) + ".xlsx";
+        assertTrue(StorageLayout.storedFileName(longName).length() <= 120, "落盘名超长");
     }
 
     @Test

+ 156 - 0
ai-server/src/test/java/com/zsjz/ai/module/plat/service/CaseInfoServicePublicWorkspaceTest.java

@@ -0,0 +1,156 @@
+package com.zsjz.ai.module.plat.service;
+
+import com.zsjz.ai.common.datasource.CaseDataSourceRegistry;
+import com.zsjz.ai.common.exception.ServerException;
+import com.zsjz.ai.common.model.plat.entity.CaseInfo;
+import com.zsjz.ai.common.model.plat.vo.PublicCaseWorkspaceVO;
+import com.zsjz.ai.common.storage.StorageLayout;
+import com.zsjz.ai.module.plat.mapper.CaseInfoMapper;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+import org.springframework.test.util.ReflectionTestUtils;
+
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.sql.Connection;
+import java.sql.DriverManager;
+import java.sql.ResultSet;
+import java.sql.Statement;
+import java.util.Properties;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+/**
+ * 桌面端案件工作区的核心契约:返回的必须是<b>数据库副本目录</b>,而不是案件原目录。
+ *
+ * <p>DuckDB 单文件只允许一个进程写打开,本进程持锁时桌面端连原库都打不开,
+ * 所以这里用真实 DuckDB 文件验证三件事:
+ * <ol>
+ *   <li>副本被创建在 {@code cases/{caseId}/desktop/.../db/case.duckdb};</li>
+ *   <li>副本能被<b>另一个连接只读打开</b>,表和视图都在(多进程分析的前提);</li>
+ *   <li>案件已在本进程打开时,走 {@link CaseDataSourceRegistry#exportSnapshot}。</li>
+ * </ol>
+ */
+class CaseInfoServicePublicWorkspaceTest {
+
+    private static final long CASE_ID = 1001L;
+
+    @TempDir
+    Path tempDir;
+
+    private StorageLayout layout;
+    private CaseInfoMapper mapper;
+    private CaseDataSourceRegistry registry;
+    private CaseInfoService service;
+
+    @BeforeEach
+    void setUp() {
+        layout = new StorageLayout(tempDir.toString(), "http://localhost:8980/js/a");
+        mapper = mock(CaseInfoMapper.class);
+        registry = mock(CaseDataSourceRegistry.class);
+        service = new CaseInfoService(registry, null, null, null, layout, null, null);
+        ReflectionTestUtils.setField(service, "baseMapper", mapper);
+    }
+
+    @Test
+    @DisplayName("案件未打开时直连源库导出副本,副本可被独立连接只读打开")
+    void createsSnapshotThatAnotherConnectionCanOpen() throws Exception {
+        Path sourceDb = layout.caseDb(CASE_ID);
+        createSourceDatabase(sourceDb);
+        CaseInfo caseInfo = caseInfo();
+        when(mapper.selectById(CASE_ID)).thenReturn(caseInfo);
+        when(registry.isOpen(CASE_ID)).thenReturn(false);
+
+        PublicCaseWorkspaceVO workspace = service.createPublicWorkspace(CASE_ID);
+
+        Path workspaceDir = Path.of(workspace.getWorkspacePath());
+        assertTrue(Files.isDirectory(workspaceDir), "工作区目录应存在");
+        assertTrue(workspaceDir.startsWith(layout.caseDir(CASE_ID)), "工作区应位于案件目录下");
+        assertEquals(CASE_ID, workspace.getCaseId());
+        assertEquals("海天专案", workspace.getName());
+        assertTrue(workspaceDir.getFileName().toString().startsWith("海天专案-"),
+                "工作区目录名应保留可读的案件名");
+
+        Path copy = workspaceDir.resolve("db").resolve("case.duckdb");
+        assertTrue(Files.isRegularFile(copy), "数据库副本应存在");
+        try (Connection con = openReadOnly(copy)) {
+            assertEquals(5, scalar(con, "select count(*) from t"), "表数据应完整复制");
+            assertEquals(5, scalar(con, "select count(*) from v"), "视图应随副本一起导出");
+        }
+        // 源库没有被副本导出删改,仍可被另一个连接打开
+        try (Connection con = openReadOnly(sourceDb)) {
+            assertEquals(5, scalar(con, "select count(*) from t"));
+        }
+    }
+
+    @Test
+    @DisplayName("案件已打开时由持锁方导出,避免直连原库")
+    void usesRegistrySnapshotWhenCaseIsOpen() throws Exception {
+        Path sourceDb = layout.caseDb(CASE_ID);
+        createSourceDatabase(sourceDb);
+        when(mapper.selectById(CASE_ID)).thenReturn(caseInfo());
+        when(registry.isOpen(CASE_ID)).thenReturn(true);
+        when(registry.exportSnapshot(eq(CASE_ID), any(Path.class))).thenAnswer(invocation -> {
+            Path target = invocation.getArgument(1);
+            Files.createDirectories(target.getParent());
+            Files.copy(sourceDb, target);
+            return true;
+        });
+
+        PublicCaseWorkspaceVO workspace = service.createPublicWorkspace(CASE_ID);
+
+        Path copy = Path.of(workspace.getWorkspacePath()).resolve("db").resolve("case.duckdb");
+        assertTrue(Files.isRegularFile(copy));
+        verify(registry).exportSnapshot(eq(CASE_ID), any(Path.class));
+    }
+
+    @Test
+    @DisplayName("不存在或非法的案件 ID 直接报可读错误,不创建目录")
+    void rejectsInvalidCaseIds() {
+        when(mapper.selectById(999L)).thenReturn(null);
+
+        assertThrows(ServerException.class, () -> service.createPublicWorkspace(null));
+        assertThrows(ServerException.class, () -> service.createPublicWorkspace(0L));
+        assertThrows(ServerException.class, () -> service.createPublicWorkspace(999L));
+    }
+
+    private CaseInfo caseInfo() {
+        CaseInfo caseInfo = new CaseInfo();
+        caseInfo.setId(CASE_ID);
+        caseInfo.setName("海天专案");
+        caseInfo.setDbPath("cases/" + CASE_ID + "/db/case.duckdb");
+        return caseInfo;
+    }
+
+    private static void createSourceDatabase(Path sourceDb) throws Exception {
+        Files.createDirectories(sourceDb.getParent());
+        try (Connection con = DriverManager.getConnection("jdbc:duckdb:" + sourceDb);
+             Statement st = con.createStatement()) {
+            st.execute("create table t as select * from range(5) tbl(i)");
+            st.execute("create view v as select i * 2 as j from t");
+        }
+    }
+
+    private static Connection openReadOnly(Path db) throws Exception {
+        Properties props = new Properties();
+        props.setProperty("access_mode", "read_only");
+        return DriverManager.getConnection("jdbc:duckdb:" + db, props);
+    }
+
+    private static int scalar(Connection con, String sql) throws Exception {
+        try (Statement st = con.createStatement();
+             ResultSet rs = st.executeQuery(sql)) {
+            rs.next();
+            return rs.getInt(1);
+        }
+    }
+}

+ 12 - 12
docs/design/storage-layout.md

@@ -39,13 +39,13 @@ qingjian/
     │   ├── case.json                 # 案件快照:id/name/ownerId/createdAt/dbPath/schemaVersion
     │   ├── db/case.duckdb            # 案件 DuckDB(+ .wal)
     │   ├── imports/{batchId}/        # 清洗导入原件
-    │   │   └── {uuid}{ext}
+    │   │   └── {原名}_{雪花id}{ext}
     │   ├── materials/{packageId}/    # 电子数据包
-    │   │   ├── {uuid}.zip
+    │   │   ├── {原名}_{雪花id}.zip
     │   │   ├── extracted/            # 解压临时,导入后删除
     │   │   └── media/{采集编号MD5}/{uuid}.{ext}
     │   ├── attachments/              # 案件级附件(人员头像等)
-    │   │   └── {uuid}{ext}
+    │   │   └── {原名}_{雪花id}{ext}
     │   ├── knowledge/                # 预留:案件级知识库
     │   ├── ai/
     │   │   ├── artifacts/            # 工具 CSV、agent_file_*
@@ -60,24 +60,24 @@ qingjian/
     │   │   └── graph/{graphHisId}_{名称}.json
     │   └── tmp/                      # 案件级临时
     ├── users/{userId}/knowledge/{kbId}/
-    │   └── docs/{uuid}{ext}          # 原件(保持原 UUID 命名逻辑)
-    │       └── {uuid}.txt            # Tika 全文 sidecar(同目录、同名换扩展名)
+    │   └── docs/{原名}_{雪花id}{ext}  # 原件
+    │       └── {原名}_{雪花id}.txt    # Tika 全文 sidecar(同目录、同名换扩展名)
     ├── index/cases.tsv               # caseId / name / ownerId / createdAt / dbPath
     └── tmp/                          # 全局临时(24h 清理)
 ```
 
 ## 3. 命名与路径规则
 
-1. **目录名固定英文小写**;文件名为 `{业务ID}_{安全原名}`(导入、附件、知识库)或
-   `{uuid}.{ext}`(EDS 媒体)或 `{域}_{工具}_{时间戳}_{uuid8}.{ext}`(AI 工具产物)。
+1. **目录名固定英文小写**;上传文件名为 `{原名}_{雪花id}{ext}`(清洗导入、EDS 包、对话附件、
+   知识库文档、人员头像统一);EDS 包内解压出的媒体仍为 `{uuid}.{ext}`(包内原始文件名
+   可能乱码,且不是用户直接上传);AI 工具产物为 `{域}_{工具}_{时间戳}_{uuid8}.{ext}`。
 2. **数据库只存相对数据根的路径**(POSIX `/`),读取时由 `StorageLayout.resolve(String)` 还原;
    `StorageLayout.relative(Path)` 负责写库前的转换。
 3. 用户输入的文件名统一经过 `StorageLayout.safeName(...)`:去路径段、过滤 `\/:*?"<>|` 与控制字符、限制长度。
-4. **磁盘统一 UUID 重命名,展示用源文件名**:所有上传文件落盘名为 `{uuid}{ext}`
-   (清洗导入、EDS 包、对话附件、知识库文档、EDS 媒体、人员头像一致);
-   数据库里的 `file_info.file_name`、`chat_attachment.file_name`、`knowledge_doc.file_name`、
-   `eds_material.file_name` 保存**源文件名**,列表与下载展示源文件名。
-   人员头像的 URL 中就是 UUID 文件名;人员与文件的关联以 `person_basic_info.photograph` 为准。
+4. **磁盘统一重命名为 `{原名}_{雪花id}{ext}`,展示用源文件名**:雪花 id 保证唯一,
+   原文件名保留可读性;数据库里的 `file_info.file_name`、`chat_attachment.file_name`、
+   `knowledge_doc.file_name`、`eds_material.file_name` 保存**源文件名**,列表与下载展示源文件名。
+   人员头像的 URL 中就是重命名后的文件名;人员与文件的关联以 `person_basic_info.photograph` 为准。
 5. EDS 媒体路径必须带 `caseId` 与 `packageId`,删案/删包可整目录清理,不同案件同采集编号不会撞目录。
 6. 案件是唯一物理隔离单元:删案 = 删除 `data/cases/{caseId}` + PG/ES/Redis 清理。