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

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

@@ -1,393 +0,0 @@
-# 验收清单（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`