@alanwang-merit/meritdata-platform-skill-package 1.0.10 → 1.0.11

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

@@ -1,421 +0,0 @@
-# 正反例对照（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`