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

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

@@ -0,0 +1,345 @@
+# joinId / fileId 生命周期（lifecycle）
+
+> **目的**：设计业务附件的 joinId（业务聚合关联）+ fileId（单个附件）的完整生命周期，避免孤儿文件和数据漂移。
+> **来源**：石油/研发 `merit-cloud-file` lifecycle.md。
+
+---
+
+## 一、两个 ID 模型
+
+### 1.1 joinId（业务聚合关联键）
+
+**定义**：业务对象 ID（如 `purchaseOrderId=12345`），用于关联一个业务对象与它的所有附件。
+
+| 特征 | 说明 |
+|------|------|
+| 来源 | 业务方（按业务对象类型 + ID 生成） |
+| 唯一性 | 按业务对象类型 + ID 维度唯一 |
+| 生命周期 | 跟随业务对象（创建 → 业务对象删除 → 关联附件删除）|
+
+### 1.2 fileId（单个附件 ID）
+
+**定义**：平台附件表主键 `PfUpload.id`（Long）。
+
+| 特征 | 说明 |
+|------|------|
+| 来源 | 平台 `PfUpload.id`（自动生成）|
+| 唯一性 | 全平台唯一 |
+| 生命周期 | 跟随附件本身（上传 → 删除 → 物理清理）|
+
+### 1.3 关系
+
+```
+业务对象 (purchaseOrderId=12345)
+  └─ joinId = "purchaseOrder:12345"
+      ├─ fileId=10001 (技术附件.pdf)
+      ├─ fileId=10002 (合同.docx)
+      └─ fileId=10003 (签字图.png)
+```
+
+---
+
+## 二、joinId 生成规则
+
+### 2.1 推荐格式
+
+```
+格式：{业务对象类型}:{业务对象ID}
+示例：
+  purchaseOrder:12345
+  contract:67890
+  report:2026Q3-001
+```
+
+**为什么用前缀**：
+- 避免不同业务对象 ID 冲突（如订单 1 和合同 1）
+- 一眼可识别关联关系
+- 便于按业务类型清理（删除整个 purchaseOrder:* 集合）
+
+### 2.2 不允许的 joinId
+
+| 反模式 | 风险 |
+|--------|------|
+| ❌ `"12345"`（裸 ID）| 与其他业务的 ID 冲突 |
+| ❌ `"purchaseOrder"`（无 ID）| 无法区分多个订单 |
+| ❌ `"/purchaseOrder/12345"`（路径分隔符）| 跨平台解析问题 |
+| ❌ `"purchaseOrder/12345"`（单分隔符）| 容易误判为路径 |
+
+### 2.3 joinId 长度限制
+
+```java
+public static final int JOIN_ID_MAX_LENGTH = 128;
+
+public static String generateJoinId(String bizType, String bizId) {
+    String joinId = bizType + ":" + bizId;
+    if (joinId.length() > JOIN_ID_MAX_LENGTH) {
+        throw new IllegalArgumentException("joinId 超过 128 字符: " + joinId);
+    }
+    return joinId;
+}
+```
+
+---
+
+## 三、6 个动作的生命周期
+
+### 3.1 上传（upload）
+
+```
+业务对象创建
+  ↓
+生成 joinId = "purchaseOrder:12345"
+  ↓
+调用 IUploadService.upload(joinId, file)
+  ↓
+平台：
+  1. 生成 fileId (PfUpload.id)
+  2. joinId → fileId 关联写入 PfUpload
+  3. 文件存到存储层
+  4. 返回 fileId
+```
+
+**注意**：
+- 业务对象**先创建** → joinId 已知 → 才能上传
+- 业务对象未创建时 → ❌ 不能上传（joinId 无意义）
+
+### 3.2 回显（display）
+
+```
+前端拿到业务对象 ID → 后端查 joinId = "purchaseOrder:12345" 的所有 fileId
+  ↓
+返回附件列表（fileId + 文件名 + 大小 + 上传时间）
+  ↓
+前端展示列表
+```
+
+**平台 API**：`IUploadService.listByJoinId(joinId)`
+
+### 3.3 下载（download）
+
+```
+前端拿到 fileId → 请求下载
+  ↓
+后端：
+  1. 校验 fileId 存在
+  2. 校验当前用户有权限（详见 security.md）
+  3. 生成临时下载 URL（带 token + 过期时间）
+  4. 返回 URL
+  ↓
+前端用 URL 拉文件
+```
+
+**平台 API**：`IUploadService.getDownloadUrl(fileId)` 或 `IEnclosureService.download(fileId)`
+
+### 3.4 删除（delete）
+
+```
+业务方调用 IUploadService.delete(fileId)
+  ↓
+平台：
+  1. 标记 PfUpload.deleted = true
+  2. 延迟物理删除（30 天后清理）
+  3. 不立即删物理文件（防止误删恢复）
+```
+
+**注意**：
+- 单文件删除 vs 批量删除（按 joinId）
+- 软删除 vs 物理删除
+
+### 3.5 复制（copy）
+
+```
+场景：合同模板复制给新订单
+  ↓
+业务方调用 IUploadService.copy(sourceFileId, targetJoinId)
+  ↓
+平台：
+  1. 复制 PfUpload 记录（新 fileId）
+  2. 复制物理文件（引用计数 +1）
+  3. 关联到 targetJoinId
+```
+
+**注意**：物理文件是引用计数 → 两个 fileId 共享同一物理文件 → 一个删除不影响另一个。
+
+### 3.6 密级（secret level）
+
+```
+业务方调用 IUploadService.setSecretLevel(fileId, level)
+  ↓
+平台：更新 PfUpload.secretLevel
+  ↓
+后续下载：自动按用户密级过滤（详见 data-classification/references/hibernate-filter.md）
+```
+
+---
+
+## 四、孤儿文件清理
+
+### 4.1 什么是孤儿文件
+
+**定义**：PfUpload 记录存在 + joinId 对应的业务对象已删除 → 附件变成孤儿。
+
+### 4.2 产生原因
+
+| 场景 | 原因 |
+|------|------|
+| 业务对象硬删除 | 业务方删表，附件 joinId 失效 |
+| 业务对象软删除 + 异步清理 | joinId 失效但 PfUpload 还在 |
+| 异常退出 | 业务对象创建 → 上传失败 → 事务回滚 → PfUpload 留下 |
+
+### 4.3 检测与清理
+
+```java
+@JobHandler("orphanFileCleanup")
+@Component
+public class OrphanFileCleanupJob extends IJobHandler {
+
+    @Autowired
+    private PfUploadRepository pfUploadRepo;
+
+    @Autowired
+    private BizObjectValidator validator;  // 校验业务对象是否还存在
+
+    @Override
+    public ReturnT<String> execute(String param) {
+        // 1. 查询所有 PfUpload（按业务类型）
+        List<PfUpload> all = pfUploadRepo.findAllNotDeleted();
+
+        int orphanCount = 0;
+        for (PfUpload upload : all) {
+            String joinId = upload.getJoinId();
+
+            // 2. 校验 joinId 对应的业务对象是否存在
+            if (!validator.isExist(joinId)) {
+                // 3. 标记孤儿（不立即物理删除）
+                upload.setOrphan(true);
+                upload.setOrphanDetectedTime(LocalDateTime.now());
+                pfUploadRepo.save(upload);
+                orphanCount++;
+            }
+        }
+
+        // 4. 报警
+        if (orphanCount > 100) {
+            alarmService.alert("孤儿文件超阈值: " + orphanCount);
+        }
+
+        return new ReturnT<>(SUCCESS, "清理 " + orphanCount + " 个孤儿标记");
+    }
+}
+```
+
+### 4.4 物理清理延迟
+
+```
+T0：业务对象删除
+T0+30 天：PfUpload.deleted = true
+T0+30 天：物理文件标记待清理
+T0+37 天：物理文件真正删除（保留 7 天恢复窗口）
+```
+
+**理由**：误删后 7 天内可恢复，超过 7 天不可逆。
+
+---
+
+## 五、生命周期对照表
+
+| 动作 | joinId 变化 | fileId 变化 | PfUpload 状态 |
+|------|------------|------------|---------------|
+| 上传 | 创建 | 创建 | `deleted=false, orphan=false` |
+| 回显 | 不变 | 不变 | 不变 |
+| 下载 | 不变 | 不变 | 不变 |
+| 删除（单文件）| 不变 | 不变 | `deleted=true` |
+| 删除（业务对象）| 删除 | 全部失效 | 全部 `deleted=true` |
+| 复制 | 新 joinId | 新 fileId | 新记录 `deleted=false` |
+| 改密级 | 不变 | 不变 | `secretLevel` 变 |
+
+---
+
+## 六、典型场景
+
+### 6.1 采购订单附件
+
+```java
+@Service
+public class PurchaseOrderFileService {
+
+    @Autowired
+    private IUploadService uploadService;
+
+    /**
+     * 采购订单创建后上传附件
+     */
+    public Long uploadFile(Long purchaseOrderId, MultipartFile file) {
+        String joinId = "purchaseOrder:" + purchaseOrderId;
+        return uploadService.upload(joinId, file);
+    }
+
+    /**
+     * 列出采购订单所有附件
+     */
+    public List<FileInfoVO> listFiles(Long purchaseOrderId) {
+        String joinId = "purchaseOrder:" + purchaseOrderId;
+        return uploadService.listByJoinId(joinId).stream()
+            .map(FileInfoVO::from)
+            .collect(toList());
+    }
+
+    /**
+     * 删除采购订单 → 联动清理附件
+     */
+    @Transactional
+    public void deletePurchaseOrder(Long purchaseOrderId) {
+        String joinId = "purchaseOrder:" + purchaseOrderId;
+
+        // 1. 软删除业务对象
+        purchaseOrderRepository.softDelete(purchaseOrderId);
+
+        // 2. 联动删除附件
+        uploadService.deleteByJoinId(joinId);
+    }
+}
+```
+
+### 6.2 合同模板复制
+
+```java
+/**
+ * 合同模板 → 新订单（复制附件）
+ */
+public Long copyTemplateFile(Long templateFileId, Long newOrderId) {
+    String newJoinId = "purchaseOrder:" + newOrderId;
+    return uploadService.copy(templateFileId, newJoinId);
+}
+```
+
+---
+
+## 七、与其他 skill 的协作
+
+| 场景 | 协作 skill |
+|------|----------|
+| 密级管理（用户/字段）| `meritdata-platform-data-classification/references/hibernate-filter.md` |
+| 多租户隔离 | `meritdata-platform-platform-config/references/multi-tenant-and-audit.md` |
+| 数据访问（同 JVM Service）| `meritdata-platform-data-access/references/outbound/service-catalog.md` |
+| Feign 调用（独立微服务）| `meritdata-platform-data-access/references/outbound/feign-guide.md` |
+| 定时清理（孤儿检测）| `meritdata-platform-job/references/scheduling-攻略/INDEX.md` |
+
+---
+
+## 八、常见错误
+
+| 错误 | 后果 | 正确做法 |
+|------|------|---------|
+| 业务对象未创建就上传 | joinId 无意义 | 业务对象先创建 |
+| joinId 用裸 ID | 与其他业务冲突 | `{bizType}:{bizId}` |
+| 业务对象硬删除不管附件 | 孤儿文件 | 联动删除附件 |
+| 不做孤儿检测 | 存储膨胀 | 定时 Job 检测 |
+| 不做延迟物理删除 | 误删无法恢复 | 软删 + 30 天延迟 |
+| 复制后忘记改 joinId | 关联到错误业务对象 | 复制时明确 targetJoinId |
+
+---
+
+**最后更新**：2026-09-08（v2.5.0 P1-B 新建）
+**来源**：石油/研发 `merit-cloud-file` lifecycle.md
+**整合位置**：`meritdata-platform-file/references/lifecycle.md`