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

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

@@ -0,0 +1,393 @@
+# 验收清单（acceptance）
+
+> **目的**：业务附件 8 大验收标准（MS-01 ~ MS-08），含自动化测试方法。
+> **来源**：石油/研发 `merit-cloud-file` acceptance.md。
+> **警告**：仅"HTTP 200"不算成功，必须通过角色和业务场景验收。
+
+---
+
+## 一、MS-01 ~ MS-08 验收清单
+
+| ID | 标准 | 自动化 | 测试方法 |
+|----|------|:------:|---------|
+| MS-01 | 业务对象不存在时不能上传 | ✅ | 单元测试 + 集成测试 |
+| MS-02 | joinId 格式校验（`{bizType}:{bizId}`）| ✅ | 单元测试 |
+| MS-03 | joinId 长度限制 ≤ 128 字符 | ✅ | 单元测试 |
+| MS-04 | 跨租户不能下载 | ✅ | 集成测试（多租户切换）|
+| MS-05 | 密级不足不能下载 | ✅ | 单元测试（5 级密级组合）|
+| MS-06 | 业务对象权限校验（L3）| ✅ | 集成测试 |
+| MS-07 | 业务对象删除联动清理附件 | ✅ | 集成测试 + 定时 Job 验证 |
+| MS-08 | 6 类操作全部审计 | ✅ | 单元测试 + 日志验证 |
+
+---
+
+## 二、MS-01：业务对象不存在时不能上传
+
+### 测试场景
+
+```java
+@Test
+public void upload_whenBusinessObjectNotExists_shouldFail() {
+    Long nonExistentOrderId = 99999L;
+    MultipartFile file = mockFile("test.pdf");
+
+    // 执行
+    assertThatThrownBy(() -> fileService.uploadFile(nonExistentOrderId, file))
+        .isInstanceOf(NotFoundException.class)
+        .hasMessageContaining("订单不存在");
+}
+```
+
+### 通过标准
+
+- ✅ 业务对象不存在 → 抛 `NotFoundException` → HTTP 404
+- ✅ 数据库无 PfUpload 记录
+- ✅ 无孤儿文件产生
+
+---
+
+## 三、MS-02：joinId 格式校验
+
+### 测试场景
+
+```java
+@ParameterizedTest
+@ValueSource(strings = {
+    "purchaseOrder:12345",     // ✅ 标准格式
+    "contract:67890",          // ✅
+    "report:2026Q3-001"        // ✅
+})
+public void joinId_validFormat_shouldPass(String joinId) {
+    assertDoesNotThrow(() -> joinIdValidator.validate(joinId));
+}
+
+@ParameterizedTest
+@ValueSource(strings = {
+    "12345",                   // ❌ 裸 ID
+    "purchaseOrder",           // ❌ 无 ID
+    "/purchaseOrder/12345",    // ❌ 路径分隔符
+    "purchaseOrder/12345",     // ❌ 单分隔符
+    "purchaseOrder:12345:extra" // ❌ 多冒号（按业务约定）
+})
+public void joinId_invalidFormat_shouldFail(String joinId) {
+    assertThatThrownBy(() -> joinIdValidator.validate(joinId))
+        .isInstanceOf(InvalidJoinIdException.class);
+}
+```
+
+### 通过标准
+
+- ✅ 合规格式 → 通过校验
+- ✅ 所有反模式格式 → 抛 `InvalidJoinIdException`
+- ✅ 错误信息提示具体违反的规则
+
+---
+
+## 四、MS-03：joinId 长度限制
+
+### 测试场景
+
+```java
+@Test
+public void joinId_lengthOver128_shouldFail() {
+    String longJoinId = "purchaseOrder:" + "x".repeat(200);
+
+    assertThatThrownBy(() -> joinIdValidator.validate(longJoinId))
+        .isInstanceOf(InvalidJoinIdException.class)
+        .hasMessageContaining("超过 128 字符");
+}
+```
+
+---
+
+## 五、MS-04：跨租户不能下载
+
+### 测试场景
+
+```java
+@Test
+public void download_crossTenant_shouldFail() {
+    // 租户 A 创建文件
+    setCurrentTenant("TENANT_A");
+    Long fileId = fileService.uploadFile(orderId, mockFile);
+
+    // 租户 B 尝试下载
+    setCurrentTenant("TENANT_B");
+
+    assertThatThrownBy(() -> fileService.download(fileId))
+        .isInstanceOf(TenantMismatchException.class);
+}
+```
+
+### 通过标准
+
+- ✅ 跨租户访问 → 抛 `TenantMismatchException` → HTTP 403
+- ✅ 审计日志记录跨租户访问尝试
+- ✅ 不返回 PfUpload 信息（避免信息泄露）
+
+---
+
+## 六、MS-05：密级不足不能下载
+
+### 测试场景
+
+```java
+@ParameterizedTest
+@MethodSource("secretLevelCombinations")
+public void download_insufficientSecretLevel_shouldFail(int userLevel, int fileLevel, boolean shouldPass) {
+    setCurrentUser(mockUser(userId, userLevel));
+    Long fileId = fileWithSecretLevel(fileLevel);
+
+    if (shouldPass) {
+        assertDoesNotThrow(() -> fileService.download(fileId));
+    } else {
+        assertThatThrownBy(() -> fileService.download(fileId))
+            .isInstanceOf(SecretLevelDeniedException.class);
+    }
+}
+
+static Stream<Arguments> secretLevelCombinations() {
+    return Stream.of(
+        Arguments.of(3, 3, true),    // 用户=3，文件=3，通过
+        Arguments.of(2, 3, false),   // 用户=2，文件=3，拒绝
+        Arguments.of(4, 3, true),    // 用户=4，文件=3，通过
+        Arguments.of(1, 5, false),   // 用户=1，文件=5，拒绝
+        Arguments.of(5, 1, true)     // 用户=5，文件=1，通过
+    );
+}
+```
+
+### 通过标准
+
+- ✅ 用户密级 ≥ 文件密级 → 通过
+- ✅ 用户密级 < 文件密级 → 抛 `SecretLevelDeniedException`
+- ✅ 5 级密级全组合覆盖
+
+---
+
+## 七、MS-06：业务对象权限校验（L3）
+
+### 测试场景
+
+```java
+@Test
+public void download_userCannotAccessOrder_shouldFail() {
+    // 订单属于部门 A
+    Long orderId = createOrderInDept("DEPT_A");
+
+    // 用户属于部门 B，没有订单权限
+    setCurrentUser(mockUserInDept("DEPT_B"));
+
+    assertThatThrownBy(() -> fileService.download(orderId))
+        .isInstanceOf(PermissionDeniedException.class);
+}
+```
+
+### 通过标准
+
+- ✅ 无业务对象权限 → 抛 `PermissionDeniedException` → HTTP 403
+- ✅ 业务方自定义权限规则生效（如"只能看本部门"）
+
+---
+
+## 八、MS-07：业务对象删除联动清理附件
+
+### 测试场景
+
+```java
+@Test
+@Transactional
+public void deleteOrder_shouldCleanupFiles() {
+    // 1. 创建订单 + 上传 3 个附件
+    Long orderId = createOrder();
+    String joinId = "purchaseOrder:" + orderId;
+    Long fileId1 = uploadService.upload(joinId, mockFile1);
+    Long fileId2 = uploadService.upload(joinId, mockFile2);
+    Long fileId3 = uploadService.upload(joinId, mockFile3);
+
+    // 2. 删除订单
+    orderService.deleteOrder(orderId);
+
+    // 3. 验证附件被软删除
+    PfUpload upload1 = pfUploadRepo.findById(fileId1).orElseThrow();
+    assertThat(upload1.getDeleted()).isTrue();
+    assertThat(upload1.getDeleteTime()).isNotNull();
+
+    // 4. 验证 list 不返回
+    List<PfUpload> remaining = uploadService.listByJoinId(joinId);
+    assertThat(remaining).isEmpty();
+}
+```
+
+### 验证孤儿检测 Job
+
+```java
+@Test
+public void orphanDetectionJob_shouldMarkOrphans() {
+    // 1. 创建订单 + 上传附件
+    Long orderId = createOrder();
+    Long fileId = uploadService.upload("purchaseOrder:" + orderId, mockFile);
+
+    // 2. 模拟业务对象被硬删除（绕过联动）
+    jdbcTemplate.execute("DELETE FROM T_PURCHASE_ORDER WHERE id = " + orderId);
+
+    // 3. 手动清理 PfUpload（让它变成孤儿）
+    pfUploadRepo.deleteById(fileId);  // 注意：实际生产 PfUpload 不会硬删，这里模拟
+
+    // 重新创建 PfUpload 但业务对象不存在
+    PfUpload orphan = new PfUpload();
+    orphan.setId(fileId);
+    orphan.setJoinId("purchaseOrder:" + orderId);
+    orphan.setDeleted(false);
+    pfUploadRepo.save(orphan);
+
+    // 4. 执行孤儿检测 Job
+    orphanCleanupJob.execute("");
+
+    // 5. 验证标记为 orphan
+    PfUpload detected = pfUploadRepo.findById(fileId).orElseThrow();
+    assertThat(detected.getOrphan()).isTrue();
+    assertThat(detected.getOrphanDetectedTime()).isNotNull();
+}
+```
+
+### 通过标准
+
+- ✅ 业务对象删除 → 附件软删除
+- ✅ 孤儿检测 Job 能识别孤儿
+- ✅ 物理清理延迟 30 天生效
+
+---
+
+## 九、MS-08：6 类操作全部审计
+
+### 测试场景
+
+```java
+@Test
+public void allOperations_shouldBeAudited() {
+    // 1. 上传
+    Long fileId = fileService.uploadFile(orderId, mockFile);
+    verify(auditLogger).logUpload(userId, "purchaseOrder:" + orderId, fileId, mockFile);
+
+    // 2. 下载
+    fileService.download(fileId);
+    verify(auditLogger).logDownload(userId, any());
+
+    // 3. 删除
+    uploadService.delete(fileId);
+    verify(auditLogger).logDelete(userId, fileId);
+
+    // 4. 复制
+    Long newFileId = uploadService.copy(fileId, "purchaseOrder:99999");
+    verify(auditLogger).logCopy(userId, fileId, "purchaseOrder:99999");
+
+    // 5. 密级变更
+    uploadService.setSecretLevel(fileId, 4);
+    verify(auditLogger).logSecretChange(userId, fileId, 2, 4);
+
+    // 6. 病毒扫描（模拟）
+    doThrow(new VirusDetectedException()).when(virusScanService).scan(any());
+    assertThatThrownBy(() -> fileService.uploadFile(orderId, infectedFile));
+    verify(auditLogger).logVirusDetected(userId, "infected.pdf", "Win32.Eicar");
+}
+```
+
+### 通过标准
+
+- ✅ 6 类操作全部触发审计
+- ✅ 审计内容含：操作类型、操作人、实体 ID、关键参数
+- ✅ 审计日志落库（`T_OPERATION_LOG`）
+
+---
+
+## 十、集成验收（端到端）
+
+### 场景：完整订单附件生命周期
+
+```java
+@Test
+public void endToEnd_orderAttachmentLifecycle() {
+    // 1. 创建订单
+    PurchaseOrder order = orderService.createOrder(new OrderDTO());
+
+    // 2. 上传 3 个附件（不同密级）
+    Long fileId1 = fileService.uploadFile(order.getId(), mockPdf, 1);
+    Long fileId2 = fileService.uploadFile(order.getId(), mockContract, 3);
+    Long fileId3 = fileService.uploadFile(order.getId(), mockFinance, 5);
+
+    // 3. 列出附件
+    List<FileInfoVO> files = fileService.listFiles(order.getId());
+    assertThat(files).hasSize(3);
+
+    // 4. 下载（用户密级足够）
+    setCurrentUser(mockUser("user1", 5));  // 5 级用户
+    fileService.download(fileId3);  // ✅ 通过
+
+    // 5. 下载（用户密级不足）
+    setCurrentUser(mockUser("user2", 2));  // 2 级用户
+    assertThatThrownBy(() -> fileService.download(fileId3))
+        .isInstanceOf(SecretLevelDeniedException.class);
+
+    // 6. 复制
+    PurchaseOrder newOrder = orderService.createOrder(new OrderDTO());
+    Long copiedFileId = fileService.copyFile(fileId1, newOrder.getId());
+
+    // 7. 删除订单（联动）
+    orderService.deleteOrder(order.getId());
+
+    // 8. 验证附件清理
+    List<PfUpload> remaining = pfUploadRepo.findByJoinId("purchaseOrder:" + order.getId());
+    assertThat(remaining).isEmpty();
+}
+```
+
+### 通过标准
+
+- ✅ 完整流程无异常
+- ✅ 6 类操作全部审计
+- ✅ 权限校验在每个动作生效
+- ✅ 联动清理生效
+
+---
+
+## 十一、性能验收
+
+| 指标 | 标准 |
+|------|------|
+| 上传 100MB 文件 | ≤ 5 秒 |
+| 列出 1000 个附件 | ≤ 200ms |
+| 生成下载 URL | ≤ 100ms |
+| 孤儿检测（10万 PfUpload）| ≤ 30 秒（XXL-JOB）|
+
+---
+
+## 十二、上线前 Checklist
+
+- [ ] 8 项验收（MS-01 ~ MS-08）全部通过
+- [ ] Nacos 配置（大小/类型/病毒扫描）已部署
+- [ ] 临时下载 URL 过期时间合理（30 分钟）
+- [ ] 审计日志开启
+- [ ] 孤儿清理 Job 调度（每日凌晨）
+- [ ] 病毒扫描引擎已对接（ClamAV / 阿里云杀毒）
+- [ ] 多租户字段已添加（PfUpload.tenantId）
+- [ ] 业务方权限规则已对接（L3 校验）
+- [ ] 物理路径不暴露（前端只接 fileId / URL）
+- [ ] 6 类操作审计内容完整
+
+---
+
+## 十三、与其他 skill 的协作
+
+| 场景 | 协作 skill |
+|------|----------|
+| 自动化测试模板 | `meritdata-platform-test-case` |
+| 集成测试 | `meritdata-platform-code-review` |
+| 审计日志 | `meritdata-platform-operation-log` |
+| 定时 Job | `meritdata-platform-job` |
+
+---
+
+**最后更新**：2026-09-08（v2.5.0 P1-B 新建）
+**来源**：石油/研发 `merit-cloud-file` acceptance.md
+**整合位置**：`meritdata-platform-file/references/acceptance.md`