@alanwang-merit/meritdata-platform-skill-package 1.0.0

package/skills/meritdata-platform-file/references/examples.md

@@ -0,0 +1,421 @@
+# 正反例对照（examples）
+
+> **目的**：业务附件 6 个动作（上传/回显/下载/删除/复制/密级）的正确与错误写法对照。
+> **来源**：石油/研发 `merit-cloud-file` examples.md。
+
+---
+
+## 一、上传（upload）
+
+### ✅ 正确：业务对象先创建 → joinId 已知 → 上传
+
+```java
+@Transactional
+public Long uploadFile(Long orderId, MultipartFile file) {
+    // 1. 业务对象已存在
+    PurchaseOrder order = orderRepository.findById(orderId)
+        .orElseThrow(() -> new NotFoundException("订单不存在"));
+
+    // 2. joinId 已知
+    String joinId = "purchaseOrder:" + orderId;
+
+    // 3. 平台层校验（大小、类型、病毒）
+    Long fileId = uploadService.upload(joinId, file);
+
+    // 4. 审计
+    auditLogger.logUpload(currentUserId(), joinId, fileId, file);
+
+    return fileId;
+}
+```
+
+### ❌ 错误 1：业务对象未创建就上传
+
+```java
+public Long uploadFile(MultipartFile file) {
+    // ❌ 没有 joinId → 无法关联业务对象
+    String joinId = "temp:" + UUID.randomUUID();
+    return uploadService.upload(joinId, file);
+    // 业务对象创建后，这个附件无法关联上去
+}
+```
+
+### ❌ 错误 2：用裸 ID 做 joinId
+
+```java
+public Long uploadFile(Long orderId, MultipartFile file) {
+    // ❌ 没有业务类型前缀 → 与其他业务的 ID 冲突
+    String joinId = String.valueOf(orderId);  // "12345"
+    return uploadService.upload(joinId, file);
+    // 合同 ID=12345 和订单 ID=12345 冲突
+}
+```
+
+### ❌ 错误 3：绕过 IUploadService
+
+```java
+public Long uploadFile(MultipartFile file) throws IOException {
+    // ❌ 直接写文件系统
+    String path = "/data/uploads/" + file.getOriginalFilename();
+    file.transferTo(new File(path));
+    return null;  // 没有 fileId，无法后续下载/删除
+}
+```
+
+---
+
+## 二、回显（list）
+
+### ✅ 正确：按 joinId 列出
+
+```java
+public List<FileInfoVO> listFiles(Long orderId) {
+    String joinId = "purchaseOrder:" + orderId;
+    return uploadService.listByJoinId(joinId).stream()
+        .map(this::toVO)
+        .collect(toList());
+}
+
+private FileInfoVO toVO(PfUpload upload) {
+    FileInfoVO vo = new FileInfoVO();
+    vo.setFileId(upload.getId());
+    vo.setFileName(upload.getFileName());
+    vo.setFileSize(upload.getFileSize());
+    vo.setFileType(upload.getFileType());
+    vo.setSecretLevel(upload.getSecretLevel());
+    vo.setUploadTime(upload.getUploadTime());
+    return vo;
+}
+```
+
+### ❌ 错误：不带租户过滤
+
+```java
+public List<FileInfoVO> listFiles(Long orderId) {
+    // ❌ 没有 tenantId 过滤 → 跨租户泄露
+    String joinId = "purchaseOrder:" + orderId;
+    return uploadService.listByJoinId(joinId).stream()
+        // ❌ 应该用 listByJoinIdAndTenantId
+        .map(this::toVO)
+        .collect(toList());
+}
+```
+
+---
+
+## 三、下载（download）
+
+### ✅ 正确：3 层授权 + 临时 URL
+
+```java
+@GetMapping("/api/file/download/{fileId}")
+public void download(@PathVariable Long fileId, HttpServletResponse response) throws IOException {
+    // L1: 文件存在 + 未删除 + 租户匹配
+    PfUpload upload = uploadService.getById(fileId);
+    if (upload == null || upload.getDeleted()) {
+        throw new NotFoundException();
+    }
+
+    String currentTenant = SessionContext.getCurrentTenantId();
+    if (!currentTenant.equals(upload.getTenantId())) {
+        throw new TenantMismatchException();
+    }
+
+    // L2: 密级校验
+    String userId = SessionContext.getCurrentUserId();
+    if (!secretLevelService.canAccess(userId, upload.getSecretLevel())) {
+        throw new SecretLevelDeniedException();
+    }
+
+    // L3: 业务对象权限
+    String bizType = parseBizType(upload.getJoinId());
+    String bizId = parseBizId(upload.getJoinId());
+    if (!permissionService.canAccess(userId, bizType, bizId)) {
+        throw new PermissionDeniedException();
+    }
+
+    // 审计
+    auditLogger.logDownload(userId, upload);
+
+    // 生成临时 URL 重定向
+    String url = uploadService.generateDownloadUrl(fileId, 30);
+    response.sendRedirect(url);
+}
+```
+
+### ❌ 错误 1：不校验权限
+
+```java
+@GetMapping("/api/file/download/{fileId}")
+public void download(@PathVariable Long fileId, HttpServletResponse response) {
+    // ❌ 任何人都能下载
+    PfUpload upload = uploadService.getById(fileId);
+    String physicalPath = "/data/uploads/" + upload.getStoredFileName();
+    FileCopyUtils.copy(new File(physicalPath), response.getOutputStream());
+}
+```
+
+### ❌ 错误 2：暴露物理路径
+
+```java
+@GetMapping("/api/file/path/{fileId}")
+public String getPath(@PathVariable Long fileId) {
+    // ❌ 暴露物理路径 → 攻击者直接访问
+    PfUpload upload = uploadService.getById(fileId);
+    return "/data/uploads/" + upload.getStoredFileName();
+}
+```
+
+### ❌ 错误 3：用 fileId 直接下载（不校验业务权限）
+
+```java
+@GetMapping("/api/file/raw/{fileId}")
+public void rawDownload(@PathVariable Long fileId, HttpServletResponse response) {
+    // ❌ 没校验 L3 业务对象权限 → 用户 A 可下用户 B 的订单附件
+    PfUpload upload = uploadService.getById(fileId);
+    response.getOutputStream().write(uploadService.readBytes(fileId));
+}
+```
+
+---
+
+## 四、删除（delete）
+
+### ✅ 正确：业务对象删除联动附件
+
+```java
+@Transactional
+public void deleteOrder(Long orderId) {
+    // 1. 软删除业务对象
+    PurchaseOrder order = orderRepository.findById(orderId)
+        .orElseThrow(() -> new NotFoundException());
+    order.setDeleted(true);
+    orderRepository.save(order);
+
+    // 2. 联动删除附件（按 joinId）
+    String joinId = "purchaseOrder:" + orderId;
+    uploadService.deleteByJoinId(joinId);
+
+    // 3. 审计
+    auditLogger.logBatchDelete(currentUserId(), joinId);
+}
+```
+
+### ✅ 正确：单文件删除
+
+```java
+public void deleteFile(Long fileId) {
+    // 1. 校验权限
+    PfUpload upload = uploadService.getById(fileId);
+    if (!permissionService.canDelete(currentUserId(), upload)) {
+        throw new PermissionDeniedException();
+    }
+
+    // 2. 软删除（平台内部 30 天延迟物理清理）
+    uploadService.delete(fileId);
+
+    // 3. 审计
+    auditLogger.logDelete(currentUserId(), fileId);
+}
+```
+
+### ❌ 错误 1：业务对象硬删除不管附件
+
+```java
+public void deleteOrder(Long orderId) {
+    // ❌ 业务对象删了，附件还在 → 孤儿文件
+    orderRepository.deleteById(orderId);
+    // 缺：uploadService.deleteByJoinId(...)
+}
+```
+
+### ❌ 错误 2：直接物理删除
+
+```java
+public void deleteFile(Long fileId) {
+    // ❌ 跳过软删除，直接删物理文件
+    PfUpload upload = uploadService.getById(fileId);
+    File file = new File("/data/uploads/" + upload.getStoredFileName());
+    file.delete();
+    // 误删后无法恢复
+}
+```
+
+---
+
+## 五、复制（copy）
+
+### ✅ 正确：模板复制到新订单
+
+```java
+public Long copyTemplateFile(Long templateFileId, Long newOrderId) {
+    // 1. 校验源文件存在
+    PfUpload source = uploadService.getById(templateFileId);
+    if (source == null || source.getDeleted()) {
+        throw new NotFoundException("模板文件不存在");
+    }
+
+    // 2. 校验目标业务对象存在
+    PurchaseOrder newOrder = orderRepository.findById(newOrderId)
+        .orElseThrow(() -> new NotFoundException("新订单不存在"));
+
+    // 3. 复制到目标 joinId
+    String targetJoinId = "purchaseOrder:" + newOrderId;
+    Long newFileId = uploadService.copy(templateFileId, targetJoinId);
+
+    // 4. 审计
+    auditLogger.logCopy(currentUserId(), templateFileId, targetJoinId);
+
+    return newFileId;
+}
+```
+
+### ❌ 错误：复制后忘记改 joinId
+
+```java
+public Long copyTemplateFile(Long templateFileId, Long newOrderId) {
+    // ❌ 复制后关联到原 joinId（不是新订单）
+    return uploadService.copy(templateFileId, "purchaseOrder:OLD_ORDER_ID");
+    // 新订单列表看不到这个文件
+}
+```
+
+---
+
+## 六、密级（secret level）
+
+### ✅ 正确：上传时设置 + 后续可调整
+
+```java
+public Long uploadFile(Long orderId, MultipartFile file, Integer secretLevel) {
+    String joinId = "purchaseOrder:" + orderId;
+    Long fileId = uploadService.upload(joinId, file);
+
+    // 设置密级（上传后立即）
+    uploadService.setSecretLevel(fileId, secretLevel);
+
+    // 审计密级变更
+    auditLogger.logSecretChange(currentUserId(), fileId, null, secretLevel);
+
+    return fileId;
+}
+
+public void upgradeSecretLevel(Long fileId, Integer newLevel) {
+    PfUpload upload = uploadService.getById(fileId);
+    Integer oldLevel = upload.getSecretLevel();
+
+    uploadService.setSecretLevel(fileId, newLevel);
+
+    auditLogger.logSecretChange(currentUserId(), fileId, oldLevel, newLevel);
+}
+```
+
+### ❌ 错误：密级设置后无审计
+
+```java
+public void upgradeSecretLevel(Long fileId, Integer newLevel) {
+    // ❌ 密级变更不审计
+    uploadService.setSecretLevel(fileId, newLevel);
+    // 谁改的、什么时候改、改前改后 → 都不知道
+}
+```
+
+---
+
+## 七、综合正例：完整业务流
+
+### 场景：采购订单的附件管理
+
+```java
+@Service
+public class PurchaseOrderFileFacade {
+
+    @Autowired
+    private IUploadService uploadService;
+
+    @Autowired
+    private PermissionService permissionService;
+
+    @Autowired
+    private SecretLevelService secretLevelService;
+
+    /**
+     * 创建订单 + 上传附件
+     */
+    @Transactional
+    public OrderWithFilesVO createOrder(OrderDTO dto, List<MultipartFile> files) {
+        // 1. 创建订单
+        PurchaseOrder order = new PurchaseOrder(dto);
+        order = orderRepository.save(order);
+
+        // 2. 上传附件
+        String joinId = "purchaseOrder:" + order.getId();
+        List<Long> fileIds = files.stream()
+            .map(file -> uploadService.upload(joinId, file))
+            .collect(toList());
+
+        // 3. 设置密级（按订单密级）
+        for (Long fileId : fileIds) {
+            uploadService.setSecretLevel(fileId, order.getSecretLevel());
+        }
+
+        return toVO(order, fileIds);
+    }
+
+    /**
+     * 列出订单附件（带权限）
+     */
+    public List<FileInfoVO> listFiles(Long orderId) {
+        // L3 校验
+        permissionService.checkCanAccessOrder(currentUserId(), orderId);
+
+        String joinId = "purchaseOrder:" + orderId;
+        return uploadService.listByJoinId(joinId).stream()
+            // L2 过滤（按当前用户密级）
+            .filter(u -> secretLevelService.canAccess(currentUserId(), u.getSecretLevel()))
+            .map(this::toVO)
+            .collect(toList());
+    }
+
+    /**
+     * 删除订单 + 联动清理
+     */
+    @Transactional
+    public void deleteOrder(Long orderId) {
+        // L3 校验
+        permissionService.checkCanDeleteOrder(currentUserId(), orderId);
+
+        // 软删除订单
+        orderRepository.softDelete(orderId);
+
+        // 联动删除附件
+        String joinId = "purchaseOrder:" + orderId;
+        uploadService.deleteByJoinId(joinId);
+    }
+}
+```
+
+---
+
+## 八、典型反模式汇总
+
+| 反模式 | 严重性 | 后果 |
+|--------|:------:|------|
+| 业务对象未创建就上传 | 中 | 孤儿文件 |
+| joinId 用裸 ID | 中 | 跨业务冲突 |
+| 业务对象硬删除不管附件 | 高 | 孤儿文件膨胀 |
+| 不校验密级 | **高** | 高级别文件泄露 |
+| 不校验租户 | **高** | 跨租户访问 |
+| 不校验业务权限 | **高** | 越权下载 |
+| 暴露物理路径 | **高** | 路径穿越 |
+| 字符串拼接文件名 | 中 | 文件名注入 |
+| 跳过 IUploadService 直接写文件 | 高 | 绕过审计/密级/租户 |
+| 不做病毒扫描 | 高 | 病毒传播 |
+| 复制后忘改 joinId | 中 | 关联错误 |
+| 密级变更不审计 | 中 | 合规风险 |
+
+---
+
+**最后更新**：2026-09-08（v2.5.0 P1-B 新建）
+**来源**：石油/研发 `merit-cloud-file` examples.md
+**整合位置**：`meritdata-platform-file/references/examples.md`