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

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

@@ -1,345 +0,0 @@
-# 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`