feat(knowledge): 添加知识条目文件上传和下载功能

- 新增文件上传接口支持批量上传知识条目文件
- 实现文件存储路径管理和安全验证机制
- 添加文件下载功能支持知识条目文件导出
- 扩展知识内容类型枚举增加FILE类型
- 扩展知识来源类型枚举增加FILE_UPLOAD类型
- 新增上传请求DTO定义文件验证和元数据配置
- 实现文件上传目录管理和文件名安全处理
- 添加文件扩展名识别和内容类型转换逻辑

backend/services/data-management-service/src/main/java/com/datamate/datamanagement/application/KnowledgeItemApplicationService.java

@@ -15,6 +15,7 @@ import com.datamate.datamanagement.domain.model.dataset.DatasetFile;
 import com.datamate.datamanagement.domain.model.dataset.Tag;
 import com.datamate.datamanagement.domain.model.knowledge.KnowledgeItem;
 import com.datamate.datamanagement.domain.model.knowledge.KnowledgeSet;
+import com.datamate.datamanagement.infrastructure.config.DataManagementProperties;
 import com.datamate.datamanagement.infrastructure.exception.DataManagementErrorCode;
 import com.datamate.datamanagement.infrastructure.persistence.mapper.TagMapper;
 import com.datamate.datamanagement.infrastructure.persistence.repository.DatasetFileRepository;
@@ -27,6 +28,7 @@ import com.datamate.datamanagement.interfaces.dto.ImportKnowledgeItemsRequest;
 import com.datamate.datamanagement.interfaces.dto.KnowledgeItemPagingQuery;
 import com.datamate.datamanagement.interfaces.dto.KnowledgeItemResponse;
 import com.datamate.datamanagement.interfaces.dto.UpdateKnowledgeItemRequest;
+import com.datamate.datamanagement.interfaces.dto.UploadKnowledgeItemsRequest;
 import jakarta.servlet.http.HttpServletResponse;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
@@ -37,8 +39,12 @@ import org.apache.commons.compress.archivers.zip.ZipArchiveOutputStream;
 import org.springframework.http.HttpHeaders;
 import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
+import org.springframework.web.multipart.MultipartFile;
 
+import java.io.File;
 import java.io.IOException;
+import java.io.InputStream;
+import java.net.URLEncoder;
 import java.nio.charset.StandardCharsets;
 import java.nio.file.Files;
 import java.nio.file.Path;
@@ -69,12 +75,16 @@ public class KnowledgeItemApplicationService {
     private static final String EXPORT_FILE_SUFFIX = ".zip";
     private static final String EXPORT_CONTENT_TYPE = "application/zip";
     private static final int MAX_FILE_BASE_LENGTH = 120;
+    private static final int MAX_TITLE_LENGTH = 200;
+    private static final String KNOWLEDGE_ITEM_UPLOAD_DIR = "knowledge-items";
+    private static final String DEFAULT_FILE_EXTENSION = "bin";
 
     private final KnowledgeItemRepository knowledgeItemRepository;
     private final KnowledgeSetRepository knowledgeSetRepository;
     private final DatasetRepository datasetRepository;
     private final DatasetFileRepository datasetFileRepository;
     private final TagMapper tagMapper;
+    private final DataManagementProperties dataManagementProperties;
 
     public KnowledgeItem createKnowledgeItem(String setId, CreateKnowledgeItemRequest request) {
         KnowledgeSet knowledgeSet = requireKnowledgeSet(setId);
@@ -106,6 +116,73 @@ public class KnowledgeItemApplicationService {
         return knowledgeItem;
     }
 
+    public List<KnowledgeItem> uploadKnowledgeItems(String setId, UploadKnowledgeItemsRequest request) {
+        KnowledgeSet knowledgeSet = requireKnowledgeSet(setId);
+        BusinessAssert.isTrue(!isReadOnlyStatus(knowledgeSet.getStatus()),
+            DataManagementErrorCode.KNOWLEDGE_SET_STATUS_ERROR);
+
+        List<MultipartFile> files = request.getFiles();
+        BusinessAssert.isTrue(CollectionUtils.isNotEmpty(files), CommonErrorCode.PARAM_ERROR);
+
+        Path uploadRoot = resolveUploadRootPath();
+        Path setDir = uploadRoot.resolve(KNOWLEDGE_ITEM_UPLOAD_DIR).resolve(setId).normalize();
+        BusinessAssert.isTrue(setDir.startsWith(uploadRoot), CommonErrorCode.PARAM_ERROR);
+        createDirectories(setDir);
+
+        boolean singleFile = files.size() == 1;
+        String overrideTitle = StringUtils.trimToNull(request.getTitle());
+        List<KnowledgeItem> items = new ArrayList<>();
+
+        for (MultipartFile file : files) {
+            BusinessAssert.notNull(file, CommonErrorCode.PARAM_ERROR);
+            BusinessAssert.isTrue(!file.isEmpty(), CommonErrorCode.PARAM_ERROR);
+
+            String originalName = resolveOriginalFileName(file);
+            String safeOriginalName = sanitizeFileName(originalName);
+            if (StringUtils.isBlank(safeOriginalName)) {
+                safeOriginalName = "file";
+            }
+
+            String extension = getFileExtension(safeOriginalName);
+            String storedName = UUID.randomUUID().toString() +
+                (StringUtils.isBlank(extension) ? "" : "." + extension);
+            Path targetPath = setDir.resolve(storedName).normalize();
+            BusinessAssert.isTrue(targetPath.startsWith(setDir), CommonErrorCode.PARAM_ERROR);
+
+            saveMultipartFile(file, targetPath);
+
+            KnowledgeItem knowledgeItem = new KnowledgeItem();
+            knowledgeItem.setId(UUID.randomUUID().toString());
+            knowledgeItem.setSetId(setId);
+            String title = singleFile && StringUtils.isNotBlank(overrideTitle)
+                ? overrideTitle
+                : stripExtension(safeOriginalName);
+            if (StringUtils.isBlank(title)) {
+                title = "未命名文件";
+            }
+            knowledgeItem.setTitle(trimToLength(title, MAX_TITLE_LENGTH));
+            knowledgeItem.setContent(buildRelativeFilePath(setId, storedName));
+            knowledgeItem.setContentType(KnowledgeContentType.FILE);
+            knowledgeItem.setSourceType(KnowledgeSourceType.FILE_UPLOAD);
+            knowledgeItem.setSourceFileId(trimToLength(safeOriginalName, MAX_TITLE_LENGTH));
+            knowledgeItem.setStatus(request.getStatus() == null ? KnowledgeStatusType.DRAFT : request.getStatus());
+
+            applyDefaultsFromSet(knowledgeItem, knowledgeSet, request.getTags(), request.getDomain(),
+                request.getBusinessLine(), request.getOwner(), request.getSensitivity(),
+                request.getValidFrom(), request.getValidTo(), request.getMetadata());
+
+            validateEffectivePeriod(knowledgeItem.getValidFrom(), knowledgeItem.getValidTo());
+            validatePublishable(knowledgeItem);
+
+            items.add(knowledgeItem);
+        }
+
+        if (CollectionUtils.isNotEmpty(items)) {
+            knowledgeItemRepository.saveBatch(items, items.size());
+        }
+        return items;
+    }
+
     public KnowledgeItem updateKnowledgeItem(String setId, String itemId, UpdateKnowledgeItemRequest request) {
         KnowledgeSet knowledgeSet = requireKnowledgeSet(setId);
         KnowledgeItem knowledgeItem = knowledgeItemRepository.getById(itemId);
@@ -245,8 +322,7 @@ public class KnowledgeItemApplicationService {
                 String entryName = buildItemEntryName(item, nameCounter);
                 ZipArchiveEntry entry = new ZipArchiveEntry(entryName);
                 zos.putArchiveEntry(entry);
-                byte[] contentBytes = (item.getContent() == null ? "" : item.getContent())
-                    .getBytes(StandardCharsets.UTF_8);
+                byte[] contentBytes = resolveExportContent(item);
                 zos.write(contentBytes);
                 zos.closeArchiveEntry();
             }
@@ -257,6 +333,126 @@ public class KnowledgeItemApplicationService {
         }
     }
 
+    @Transactional(readOnly = true)
+    public void downloadKnowledgeItemFile(String setId, String itemId, HttpServletResponse response) {
+        BusinessAssert.notNull(response, CommonErrorCode.PARAM_ERROR);
+        KnowledgeItem knowledgeItem = knowledgeItemRepository.getById(itemId);
+        BusinessAssert.notNull(knowledgeItem, DataManagementErrorCode.KNOWLEDGE_ITEM_NOT_FOUND);
+        BusinessAssert.isTrue(Objects.equals(knowledgeItem.getSetId(), setId), CommonErrorCode.PARAM_ERROR);
+        BusinessAssert.isTrue(knowledgeItem.getContentType() == KnowledgeContentType.FILE
+                || knowledgeItem.getSourceType() == KnowledgeSourceType.FILE_UPLOAD,
+            CommonErrorCode.PARAM_ERROR);
+
+        String relativePath = knowledgeItem.getContent();
+        BusinessAssert.isTrue(StringUtils.isNotBlank(relativePath), CommonErrorCode.PARAM_ERROR);
+        Path filePath = resolveKnowledgeItemStoragePath(relativePath);
+        BusinessAssert.isTrue(Files.exists(filePath) && Files.isRegularFile(filePath), CommonErrorCode.PARAM_ERROR);
+
+        String downloadName = StringUtils.isNotBlank(knowledgeItem.getSourceFileId())
+            ? knowledgeItem.getSourceFileId()
+            : filePath.getFileName().toString();
+
+        response.setContentType("application/octet-stream");
+        response.setCharacterEncoding(StandardCharsets.UTF_8.name());
+        response.setHeader(HttpHeaders.CONTENT_DISPOSITION,
+            "attachment; filename=\"" + URLEncoder.encode(downloadName, StandardCharsets.UTF_8) + "\"");
+
+        try (InputStream inputStream = Files.newInputStream(filePath)) {
+            inputStream.transferTo(response.getOutputStream());
+            response.flushBuffer();
+        } catch (IOException e) {
+            log.error("download knowledge item file error, itemId: {}", itemId, e);
+            throw BusinessException.of(SystemErrorCode.FILE_SYSTEM_ERROR);
+        }
+    }
+
+    private byte[] resolveExportContent(KnowledgeItem item) {
+        if (item.getContentType() == KnowledgeContentType.FILE) {
+            String relativePath = item.getContent();
+            BusinessAssert.isTrue(StringUtils.isNotBlank(relativePath), CommonErrorCode.PARAM_ERROR);
+            Path filePath = resolveKnowledgeItemStoragePath(relativePath);
+            BusinessAssert.isTrue(Files.exists(filePath) && Files.isRegularFile(filePath), CommonErrorCode.PARAM_ERROR);
+            try {
+                return Files.readAllBytes(filePath);
+            } catch (IOException e) {
+                log.error("export knowledge item file error, itemId: {}", item.getId(), e);
+                throw BusinessException.of(SystemErrorCode.FILE_SYSTEM_ERROR);
+            }
+        }
+        return (item.getContent() == null ? "" : item.getContent()).getBytes(StandardCharsets.UTF_8);
+    }
+
+    private String resolveExportExtension(KnowledgeItem item) {
+        if (item.getContentType() == KnowledgeContentType.MARKDOWN) {
+            return "md";
+        }
+        if (item.getContentType() == KnowledgeContentType.FILE) {
+            String extension = getFileExtension(item.getSourceFileId());
+            if (StringUtils.isBlank(extension)) {
+                extension = getFileExtensionFromPath(item.getContent());
+            }
+            return StringUtils.isBlank(extension) ? DEFAULT_FILE_EXTENSION : extension;
+        }
+        return "txt";
+    }
+
+    private String getFileExtensionFromPath(String path) {
+        if (StringUtils.isBlank(path)) {
+            return "";
+        }
+        Path fileName = Paths.get(path).getFileName();
+        return fileName == null ? "" : getFileExtension(fileName.toString());
+    }
+
+    private Path resolveUploadRootPath() {
+        String uploadDir = dataManagementProperties.getFileStorage().getUploadDir();
+        BusinessAssert.isTrue(StringUtils.isNotBlank(uploadDir), CommonErrorCode.PARAM_ERROR);
+        return Paths.get(uploadDir).toAbsolutePath().normalize();
+    }
+
+    private Path resolveKnowledgeItemStoragePath(String relativePath) {
+        String normalizedRelativePath = relativePath.replace("/", File.separator);
+        Path root = resolveUploadRootPath();
+        Path target = root.resolve(normalizedRelativePath).toAbsolutePath().normalize();
+        BusinessAssert.isTrue(target.startsWith(root), CommonErrorCode.PARAM_ERROR);
+        return target;
+    }
+
+    private String buildRelativeFilePath(String setId, String storedName) {
+        String relativePath = Paths.get(KNOWLEDGE_ITEM_UPLOAD_DIR, setId, storedName).toString();
+        return relativePath.replace(File.separatorChar, '/');
+    }
+
+    private void createDirectories(Path path) {
+        try {
+            Files.createDirectories(path);
+        } catch (IOException e) {
+            log.error("create knowledge item upload dir error, path: {}", path, e);
+            throw BusinessException.of(SystemErrorCode.FILE_SYSTEM_ERROR);
+        }
+    }
+
+    private void saveMultipartFile(MultipartFile file, Path targetPath) {
+        try (InputStream inputStream = file.getInputStream()) {
+            Files.copy(inputStream, targetPath);
+        } catch (IOException e) {
+            log.error("save knowledge item file error, target: {}", targetPath, e);
+            throw BusinessException.of(SystemErrorCode.FILE_SYSTEM_ERROR);
+        }
+    }
+
+    private String resolveOriginalFileName(MultipartFile file) {
+        String originalName = file.getOriginalFilename();
+        if (StringUtils.isBlank(originalName)) {
+            originalName = file.getName();
+        }
+        if (originalName == null) {
+            return "";
+        }
+        Path fileName = Paths.get(originalName).getFileName();
+        return fileName == null ? originalName : fileName.toString();
+    }
+
     private KnowledgeSet requireKnowledgeSet(String setId) {
         KnowledgeSet knowledgeSet = knowledgeSetRepository.getById(setId);
         BusinessAssert.notNull(knowledgeSet, DataManagementErrorCode.KNOWLEDGE_SET_NOT_FOUND);
@@ -275,7 +471,7 @@ public class KnowledgeItemApplicationService {
         }
         baseName = trimToLength(baseName, MAX_FILE_BASE_LENGTH);
 
-        String extension = item.getContentType() == KnowledgeContentType.MARKDOWN ? "md" : "txt";
+        String extension = resolveExportExtension(item);
         String baseKey = baseName + "." + extension;
         int count = nameCounter.getOrDefault(baseKey, 0);
         nameCounter.put(baseKey, count + 1);
@@ -325,6 +521,17 @@ public class KnowledgeItemApplicationService {
             : KnowledgeContentType.TEXT;
     }
 
+    private String getFileExtension(String fileName) {
+        if (StringUtils.isBlank(fileName)) {
+            return "";
+        }
+        int dotIndex = fileName.lastIndexOf('.');
+        if (dotIndex <= 0 || dotIndex >= fileName.length() - 1) {
+            return "";
+        }
+        return fileName.substring(dotIndex + 1);
+    }
+
     private String getFileExtension(DatasetFile datasetFile) {
         String fileName = datasetFile.getFileName();
         if (StringUtils.isNotBlank(fileName) && fileName.contains(".")) {

backend/services/data-management-service/src/main/java/com/datamate/datamanagement/common/enums/KnowledgeContentType.java

@@ -11,5 +11,9 @@ public enum KnowledgeContentType {
     /**
      * Markdown
      */
-    MARKDOWN
+    MARKDOWN,
+    /**
+     * 文件（不解析内容）
+     */
+    FILE
 }

backend/services/data-management-service/src/main/java/com/datamate/datamanagement/common/enums/KnowledgeSourceType.java

@@ -11,5 +11,9 @@ public enum KnowledgeSourceType {
     /**
      * 数据集文件导入
      */
-    DATASET_FILE
+    DATASET_FILE,
+    /**
+     * 文件上传
+     */
+    FILE_UPLOAD
 }

backend/services/data-management-service/src/main/java/com/datamate/datamanagement/interfaces/dto/UploadKnowledgeItemsRequest.java

@@ -0,0 +1,72 @@
+package com.datamate.datamanagement.interfaces.dto;
+
+import com.datamate.datamanagement.common.enums.KnowledgeStatusType;
+import jakarta.validation.constraints.NotEmpty;
+import jakarta.validation.constraints.Size;
+import lombok.Getter;
+import lombok.Setter;
+import org.springframework.format.annotation.DateTimeFormat;
+import org.springframework.web.multipart.MultipartFile;
+
+import java.time.LocalDate;
+import java.util.List;
+
+/**
+ * 上传知识条目请求DTO（基于文件）
+ */
+@Getter
+@Setter
+public class UploadKnowledgeItemsRequest {
+    /**
+     * 上传文件列表
+     */
+    @NotEmpty(message = "文件列表不能为空")
+    private List<MultipartFile> files;
+    /**
+     * 标题（单文件时可指定）
+     */
+    @Size(min = 1, max = 200)
+    private String title;
+    /**
+     * 状态
+     */
+    private KnowledgeStatusType status;
+    /**
+     * 标签列表
+     */
+    private List<String> tags;
+    /**
+     * 领域
+     */
+    @Size(max = 100)
+    private String domain;
+    /**
+     * 业务线
+     */
+    @Size(max = 100)
+    private String businessLine;
+    /**
+     * 负责人
+     */
+    @Size(max = 100)
+    private String owner;
+    /**
+     * 有效期开始
+     */
+    @DateTimeFormat(iso = DateTimeFormat.ISO.DATE)
+    private LocalDate validFrom;
+    /**
+     * 有效期结束
+     */
+    @DateTimeFormat(iso = DateTimeFormat.ISO.DATE)
+    private LocalDate validTo;
+    /**
+     * 敏感级别
+     */
+    @Size(max = 50)
+    private String sensitivity;
+    /**
+     * 扩展元数据
+     */
+    private String metadata;
+}

backend/services/data-management-service/src/main/java/com/datamate/datamanagement/interfaces/rest/KnowledgeItemController.java

@@ -10,10 +10,12 @@ import com.datamate.datamanagement.interfaces.dto.ImportKnowledgeItemsRequest;
 import com.datamate.datamanagement.interfaces.dto.KnowledgeItemPagingQuery;
 import com.datamate.datamanagement.interfaces.dto.KnowledgeItemResponse;
 import com.datamate.datamanagement.interfaces.dto.UpdateKnowledgeItemRequest;
+import com.datamate.datamanagement.interfaces.dto.UploadKnowledgeItemsRequest;
 import jakarta.servlet.http.HttpServletResponse;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
+import org.springframework.http.MediaType;
 import org.springframework.web.bind.annotation.*;
 
 import java.util.List;
@@ -48,12 +50,27 @@ public class KnowledgeItemController {
         return KnowledgeConverter.INSTANCE.convertItemResponses(items);
     }
 
+    @PostMapping(value = "/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
+    public List<KnowledgeItemResponse> uploadKnowledgeItems(@PathVariable("setId") String setId,
+                                                            @Valid UploadKnowledgeItemsRequest request) {
+        List<KnowledgeItem> items = knowledgeItemApplicationService.uploadKnowledgeItems(setId, request);
+        return KnowledgeConverter.INSTANCE.convertItemResponses(items);
+    }
+
     @IgnoreResponseWrap
     @GetMapping("/export")
     public void exportKnowledgeItems(@PathVariable("setId") String setId, HttpServletResponse response) {
         knowledgeItemApplicationService.exportKnowledgeItems(setId, response);
     }
 
+    @IgnoreResponseWrap
+    @GetMapping("/{itemId}/file")
+    public void downloadKnowledgeItemFile(@PathVariable("setId") String setId,
+                                          @PathVariable("itemId") String itemId,
+                                          HttpServletResponse response) {
+        knowledgeItemApplicationService.downloadKnowledgeItemFile(setId, itemId, response);
+    }
+
     @GetMapping("/{itemId}")
     public KnowledgeItemResponse getKnowledgeItemById(@PathVariable("setId") String setId,
                                                       @PathVariable("itemId") String itemId) {