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

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

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