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

package/skills/meritdata-platform-file/references/api-contracts.md

@@ -0,0 +1,392 @@
+# API 契约（api-contracts）
+
+> **目的**：MeritData Cloud 6.13.2 业务附件的真实类、方法和实体字段。
+> **来源**：石油/研发 `merit-cloud-file` api-contracts.md。
+> **警告**：仅使用 6.13.2 已验证签名，不要根据旧版本/方法名推断未公开语义。
+
+---
+
+## 一、两个核心 Service
+
+### 1.1 `IUploadService`（按 joinId 管理）
+
+**定位**：**业务附件首选**。按 `joinId` 管理附件集合，按 `PfUpload.id` 管理单个附件。
+
+```java
+public interface IUploadService {
+
+    /**
+     * 上传附件到 joinId 集合
+     * @param joinId 业务聚合关联键（"bizType:id"）
+     * @param file 上传的文件
+     * @return fileId (PfUpload.id)
+     */
+    Long upload(String joinId, MultipartFile file);
+
+    /**
+     * 列出 joinId 集合下所有附件
+     */
+    List<PfUpload> listByJoinId(String joinId);
+
+    /**
+     * 按 fileId 获取附件信息
+     */
+    PfUpload getById(Long fileId);
+
+    /**
+     * 单附件软删除
+     */
+    void delete(Long fileId);
+
+    /**
+     * 按 joinId 删除整个集合（联动删除）
+     */
+    void deleteByJoinId(String joinId);
+
+    /**
+     * 复制附件到新 joinId
+     * @return 新 fileId
+     */
+    Long copy(Long sourceFileId, String targetJoinId);
+
+    /**
+     * 设置密级
+     * @param level 1-5（见 data-classification）
+     */
+    void setSecretLevel(Long fileId, Integer level);
+
+    /**
+     * 生成临时下载 URL（带 token + 过期）
+     */
+    String generateDownloadUrl(Long fileId, Integer expireMinutes);
+}
+```
+
+### 1.2 `IEnclosureService`（通用 enclosure）
+
+**定位**：**仅在参数语义已由当前项目证明时使用**。独立契约，与 IUploadService 不能互相替代。
+
+```java
+public interface IEnclosureService {
+
+    /**
+     * 上传到 enclosure（与 joinId 无关）
+     */
+    String upload(MultipartFile file);
+
+    /**
+     * 下载 enclosure
+     */
+    void download(String enclosureId, HttpServletResponse response);
+
+    /**
+     * 删除 enclosure
+     */
+    void delete(String enclosureId);
+}
+```
+
+**何时用 IEnclosureService**：
+- 不需要关联业务对象（独立文件存储）
+- 参数语义已经本项目业务方证明
+- ❌ **不要**仅因存在 upload/download 方法就替代业务附件服务
+
+### 1.3 调用边界
+
+| Service | 同 JVM | 独立微服务 |
+|---------|--------|----------|
+| `IUploadService` | 直接注入 | Feign 调用 |
+| `IEnclosureService` | 直接注入 | Feign 调用 |
+
+---
+
+## 二、PfUpload 实体字段
+
+### 2.1 完整字段
+
+```java
+@Data
+@Entity
+@Table(name = "PF_UPLOAD")
+public class PfUpload {
+    private Long id;                       // fileId（主键）
+    private String joinId;                 // 业务聚合关联键
+    private String fileName;               // 原始文件名
+    private String storedFileName;         // 存储文件名（UUID）
+    private String fileType;               // MIME 类型
+    private Long fileSize;                 // 字节数
+    private String fileHash;               // SHA-256 哈希
+    private Integer secretLevel;           // 密级 1-5
+    private String tenantId;               // 租户 ID
+    private Long referenceCount;           // 复制引用计数
+    private Boolean deleted;               // 软删除标记
+    private Boolean orphan;                // 孤儿标记
+    private LocalDateTime uploadTime;
+    private String uploadUserId;           // 上传用户 ID
+    private LocalDateTime orphanDetectedTime;
+    private LocalDateTime deleteTime;      // 软删除时间
+}
+```
+
+### 2.2 关键字段语义
+
+| 字段 | 用途 |
+|------|------|
+| `id` | 平台 fileId（主键） |
+| `joinId` | 业务聚合关联（如 `purchaseOrder:12345`） |
+| `storedFileName` | 平台内部存储名（UUID，不暴露） |
+| `fileHash` | 用于去重（相同 hash 不重复存） |
+| `secretLevel` | 1-5 密级（详见 `data-classification/hibernate-filter.md`） |
+| `referenceCount` | 复制次数 > 1 时，物理文件不删除 |
+| `orphan` | 定时检测标记，业务对象删除后置 true |
+| `tenantId` | 多租户隔离（按租户过滤） |
+
+---
+
+## 三、同 JVM 注入（Feign 替代）
+
+### 3.1 系统管理同进程
+
+```java
+@Service
+public class PurchaseOrderFileService {
+
+    @Autowired
+    private IUploadService uploadService;  // 直接注入（同 JVM）
+}
+```
+
+### 3.2 独立微服务（走 Feign）
+
+```java
+@FeignClient(name = "cloud-system-manage")
+public interface UploadFeignClient {
+
+    @PostMapping(value = "/api/upload/upload", consumes = MULTIPART_FORM_DATA_VALUE)
+    ResultBody<Long> upload(@RequestParam("joinId") String joinId,
+                             @RequestPart("file") MultipartFile file);
+
+    @GetMapping("/api/upload/list")
+    ResultBody<List<PfUploadDTO>> listByJoinId(@RequestParam("joinId") String joinId);
+
+    @DeleteMapping("/api/upload/delete")
+    ResultBody<Void> delete(@RequestParam("fileId") Long fileId);
+}
+```
+
+---
+
+## 四、HTTP 网关契约（独立微服务）
+
+### 4.1 上传
+
+```http
+POST /api/upload/upload
+Content-Type: multipart/form-data
+
+file: <binary>
+joinId: purchaseOrder:12345
+```
+
+**响应**：
+```json
+{
+  "code": 200,
+  "data": 10001,
+  "message": "success"
+}
+```
+
+### 4.2 列出附件
+
+```http
+GET /api/upload/list?joinId=purchaseOrder:12345
+```
+
+**响应**：
+```json
+{
+  "code": 200,
+  "data": [
+    {
+      "id": 10001,
+      "joinId": "purchaseOrder:12345",
+      "fileName": "技术附件.pdf",
+      "fileType": "application/pdf",
+      "fileSize": 1048576,
+      "secretLevel": 2,
+      "uploadTime": "2026-09-08T15:30:00Z"
+    }
+  ]
+}
+```
+
+### 4.3 下载
+
+```http
+GET /api/upload/download?fileId=10001
+```
+
+**响应**：直接返回文件二进制（Content-Disposition: attachment）。
+
+### 4.4 删除
+
+```http
+DELETE /api/upload/delete?fileId=10001
+```
+
+### 4.5 复制
+
+```http
+POST /api/upload/copy
+Content-Type: application/json
+
+{
+  "sourceFileId": 10001,
+  "targetJoinId": "purchaseOrder:67890"
+}
+```
+
+---
+
+## 五、内部抽象（业务方**不可直接调用**）
+
+### 5.1 `AbstractFileOperation`
+
+**定位**：平台内部存储抽象，封装 OSS/本地文件系统/S3 等多种后端。
+
+```java
+public abstract class AbstractFileOperation {
+    public abstract String store(String storedFileName, byte[] content);
+    public abstract byte[] read(String storedFileName);
+    public abstract void delete(String storedFileName);
+    public abstract String getPhysicalPath(String storedFileName);
+}
+```
+
+**业务方禁止**：
+- ❌ 直接 `new` AbstractFileOperation 子类
+- ❌ 直接拼接物理路径
+- ❌ 绕过元数据（PfUpload）层直接操作文件
+
+**为什么**：平台抽象层会处理密级 / 租户 / 审计 / 存储路由，业务方直接调用会绕过这些保护。
+
+---
+
+## 六、错误码
+
+| 错误码 | 含义 | 处置 |
+|--------|------|------|
+| `ERR_FILE_NOT_FOUND` | fileId 不存在 | 404 |
+| `ERR_FILE_DELETED` | 已软删除 | 不返回 |
+| `ERR_FILE_NO_PERMISSION` | 无下载权限 | 403 |
+| `ERR_FILE_SECRET_LEVEL` | 用户密级不足 | 403 |
+| `ERR_FILE_TENANT_MISMATCH` | 跨租户访问 | 403 |
+| `ERR_FILE_SIZE_EXCEED` | 文件超过限制 | 400 |
+| `ERR_FILE_TYPE_DENIED` | 文件类型被禁 | 400 |
+| `ERR_FILE_VIRUS_DETECTED` | 病毒扫描命中 | 400 |
+| `ERR_JOIN_ID_TOO_LONG` | joinId > 128 | 400 |
+
+---
+
+## 七、配置项（Nacos）
+
+```properties
+# 文件大小限制（字节）
+meritdata.cloud.file.max-size=104857600  # 100MB
+
+# 允许的文件类型
+meritdata.cloud.file.allowed-types=pdf,docx,xlsx,pptx,jpg,png,zip
+
+# 临时下载 URL 过期时间（分钟）
+meritdata.cloud.file.download-url-expire=30
+
+# 病毒扫描开关
+meritdata.cloud.file.virus-scan.enabled=true
+```
+
+---
+
+## 八、典型场景代码
+
+### 8.1 完整上传 + 关联业务对象
+
+```java
+@Service
+public class PurchaseOrderFileService {
+
+    @Autowired
+    private IUploadService uploadService;
+
+    @Autowired
+    private PurchaseOrderRepository orderRepository;
+
+    @Transactional
+    public Long uploadFile(Long orderId, MultipartFile file) {
+        // 1. 校验业务对象存在
+        PurchaseOrder order = orderRepository.findById(orderId)
+            .orElseThrow(() -> new NotFoundException("订单不存在: " + orderId));
+
+        // 2. 生成 joinId
+        String joinId = "purchaseOrder:" + orderId;
+
+        // 3. 上传（平台自动校验：大小、类型、病毒）
+        Long fileId = uploadService.upload(joinId, file);
+
+        return fileId;
+    }
+}
+```
+
+### 8.2 下载（带权限校验）
+
+```java
+@GetMapping("/api/file/download/{fileId}")
+public void download(@PathVariable Long fileId, HttpServletResponse response) {
+    // 1. 鉴权（业务方负责，平台不再重复）
+    PfUpload upload = uploadService.getById(fileId);
+    if (upload == null || upload.getDeleted()) {
+        throw new NotFoundException("文件不存在");
+    }
+
+    // 2. 密级 + 租户校验（详见 security.md）
+    if (!permissionService.canDownload(currentUserId(), upload)) {
+        throw new PermissionDeniedException("无下载权限");
+    }
+
+    // 3. 生成临时 URL 或直接流式返回
+    String url = uploadService.generateDownloadUrl(fileId, 30);
+    response.sendRedirect(url);
+}
+```
+
+---
+
+## 九、与其他 skill 的协作
+
+| 场景 | 协作 skill |
+|------|----------|
+| Feign 写法 | `meritdata-platform-data-access/references/outbound/feign-guide.md` |
+| 同 JVM Service | `meritdata-platform-data-access/references/outbound/service-catalog.md` |
+| 密级管理 | `meritdata-platform-data-classification/references/hibernate-filter.md` |
+| Nacos 配置 | `meritdata-platform-nacos-config/references/configuration-properties.md` |
+| 多租户 | `meritdata-platform-platform-config/references/multi-tenant-and-audit.md` |
+
+---
+
+## 十、常见错误
+
+| 错误 | 后果 | 正确做法 |
+|------|------|---------|
+| 用 IEnclosureService 做业务附件 | 参数语义不对 | 用 IUploadService + joinId |
+| 业务对象未创建就上传 | joinId 无意义 | 业务对象先创建 |
+| 直接拼接物理路径 | 路径穿越风险 | 用 download URL |
+| 不查 PfUpload 直接 download | 密级/租户失效 | 先 getById 再校验 |
+| 同 JVM 也走 Feign | 性能浪费 | 同 JVM 直接注入 |
+| 独立微服务直接注入 | ClassNotFound | 走 Feign HTTP 契约 |
+
+---
+
+**最后更新**：2026-09-08（v2.5.0 P1-B 新建）
+**来源**：石油/研发 `merit-cloud-file` api-contracts.md
+**整合位置**：`meritdata-platform-file/references/api-contracts.md`