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

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

@@ -0,0 +1,423 @@
+# 安全规范（security）
+
+> **目的**：业务附件的密级 / 租户 / 下载授权 / 文件校验 / 路径安全 / 审计 6 大安全控制。
+> **来源**：石油/研发 `merit-cloud-file` security.md + security-rules.md §三 §五。
+
+---
+
+## 一、6 大安全控制
+
+| 控制 | 防护对象 | 实现位置 |
+|------|---------|---------|
+| 1. 密级 | 字段值泄露 | PfUpload.secretLevel + data-classification |
+| 2. 租户 | 跨租户访问 | PfUpload.tenantId |
+| 3. 下载授权 | 越权下载 | 业务层 `permissionService.canDownload()` |
+| 4. 文件校验 | 病毒 / 类型伪造 | 平台上传时扫描 |
+| 5. 路径安全 | 路径穿越 | `storedFileName` UUID，不暴露物理路径 |
+| 6. 审计 | 操作追溯 | operation-log |
+
+---
+
+## 二、密级（secret level）
+
+### 2.1 5 级密级定义
+
+| 级别 | 名称 | 适用场景 |
+|:--:|------|---------|
+| 1 | 公开 | 普通文档 |
+| 2 | 内部 | 公司内部资料 |
+| 3 | 秘密 | 合同 / 报价单 |
+| 4 | 机密 | 财务凭证 / 审计报告 |
+| 5 | 绝密 | 战略文件 / 密钥 |
+
+### 2.2 设置密级
+
+```java
+// 上传时设置
+Long fileId = uploadService.upload(joinId, file);
+uploadService.setSecretLevel(fileId, 3);
+
+// 后续密级变更（审计）
+uploadService.setSecretLevel(fileId, 4);  // 升密级
+```
+
+### 2.3 下载时密级过滤
+
+**用户密级 < 文件密级 → 拒绝下载**。
+
+```java
+public boolean canDownload(String userId, PfUpload upload) {
+    Integer userSecretLevel = secretLevelService.getUserLevel(userId);
+    return userSecretLevel >= upload.getSecretLevel();
+}
+```
+
+详见 `meritdata-platform-data-classification/references/hibernate-filter.md`。
+
+---
+
+## 三、租户隔离
+
+### 3.1 多租户模型
+
+```java
+@Data
+@Entity
+@Table(name = "PF_UPLOAD")
+public class PfUpload {
+    private String tenantId;  // 租户 ID（按多租户字段过滤）
+}
+```
+
+### 3.2 上传时自动打租户
+
+```java
+public Long upload(String joinId, MultipartFile file) {
+    // 1. 从 Session 取当前租户
+    String tenantId = SessionContext.getCurrentTenantId();
+
+    // 2. 上传时自动写入 tenantId
+    PfUpload upload = new PfUpload();
+    upload.setJoinId(joinId);
+    upload.setTenantId(tenantId);  // 平台自动
+    // ...
+}
+```
+
+### 3.3 查询时自动过滤
+
+```java
+public List<PfUpload> listByJoinId(String joinId) {
+    String tenantId = SessionContext.getCurrentTenantId();
+    return pfUploadRepo.findByJoinIdAndTenantId(joinId, tenantId);
+}
+```
+
+**禁止跨租户访问**：
+- 租户 A 不能看到租户 B 的 PfUpload
+- 即使猜对 fileId + joinId 也无法访问
+
+详见 `meritdata-platform-platform-config/references/multi-tenant-and-audit.md`。
+
+---
+
+## 四、下载授权
+
+### 4.1 3 层授权
+
+| 层 | 校验内容 | 实现 |
+|----|---------|------|
+| L1 平台 | 文件存在 + 未删除 + 租户匹配 | `IUploadService.getById()` |
+| L2 密级 | 用户密级 >= 文件密级 | `secretLevelService.getUserLevel()` |
+| L3 业务 | 业务对象权限（如"只能看自己部门的订单"）| `permissionService.canAccessOrder()` |
+
+### 4.2 业务层授权模板
+
+```java
+@Service
+public class FileDownloadAuthorizationService {
+
+    @Autowired
+    private IUploadService uploadService;
+
+    @Autowired
+    private SecretLevelService secretLevelService;
+
+    @Autowired
+    private PermissionService permissionService;
+
+    public boolean canDownload(String userId, Long fileId) {
+        // L1: 文件存在 + 未删除 + 租户匹配
+        PfUpload upload = uploadService.getById(fileId);
+        if (upload == null || upload.getDeleted()) {
+            return false;
+        }
+
+        String tenantId = SessionContext.getCurrentTenantId();
+        if (!tenantId.equals(upload.getTenantId())) {
+            return false;
+        }
+
+        // L2: 密级足够
+        Integer userLevel = secretLevelService.getUserLevel(userId);
+        if (userLevel < upload.getSecretLevel()) {
+            return false;
+        }
+
+        // L3: 业务对象权限
+        String joinId = upload.getJoinId();
+        String bizType = parseBizType(joinId);     // "purchaseOrder"
+        String bizId = parseBizId(joinId);          // "12345"
+        if (!permissionService.canAccess(userId, bizType, bizId)) {
+            return false;
+        }
+
+        return true;
+    }
+}
+```
+
+### 4.3 临时下载 URL
+
+```java
+// 生成 30 分钟过期的 URL
+String url = uploadService.generateDownloadUrl(fileId, 30);
+// URL: https://cloud.meritdata.com/api/upload/download?fileId=10001&token=xxx&expire=1736380800
+
+// 30 分钟后 token 失效，需要重新生成
+```
+
+**好处**：
+- 不暴露物理路径
+- 不暴露 fileId 给前端直接访问
+- token 自动过期
+
+---
+
+## 五、文件校验
+
+### 5.1 平台层校验（上传时）
+
+| 校验 | 规则 |
+|------|------|
+| 大小 | `<= 100MB`（可配置 Nacos） |
+| 类型 | 白名单（pdf/docx/xlsx/pptx/jpg/png/zip） |
+| 文件名 | 不含 `../` `/` `\` 等路径分隔符 |
+| 病毒扫描 | 调 ClamAV / 杀毒引擎 |
+| MIME | 通过文件头判断（不是后缀名）|
+
+### 5.2 业务方附加校验
+
+```java
+public class FileValidationService {
+
+    public void validateAdditional(MultipartFile file, String bizType) {
+        // 1. 文件名长度
+        if (file.getOriginalFilename().length() > 200) {
+            throw new ValidationException("文件名超过 200 字符");
+        }
+
+        // 2. 中文文件名编码
+        String fileName = new String(file.getOriginalFilename().getBytes(ISO_8859_1), UTF_8);
+
+        // 3. 业务方特殊校验
+        if ("contract".equals(bizType) && !fileName.endsWith(".pdf")) {
+            throw new ValidationException("合同必须是 PDF");
+        }
+
+        // 4. SHA-256 去重（可选）
+        String hash = DigestUtils.sha256Hex(file.getBytes());
+        if (pfUploadRepo.existsByFileHash(hash)) {
+            throw new ValidationException("文件已存在");
+        }
+    }
+}
+```
+
+### 5.3 病毒扫描
+
+```java
+@Component
+public class VirusScanService {
+
+    @Autowired
+    private ClamAVClient clamAV;
+
+    public void scan(MultipartFile file) {
+        ScanResult result = clamAV.scan(file.getBytes());
+        if (result.isInfected()) {
+            // 不上传 + 报警 + 审计
+            throw new VirusDetectedException("病毒扫描命中: " + result.getVirusName());
+        }
+    }
+}
+```
+
+---
+
+## 六、路径安全
+
+### 6.1 不暴露物理路径
+
+```java
+// ❌ 错误：暴露物理路径
+@GetMapping("/download")
+public void download(Long fileId, HttpServletResponse response) {
+    String physicalPath = "/data/cloud/uploads/2026/09/08/abc-uuid.pdf";
+    File file = new File(physicalPath);
+    // 前端拿到物理路径 → 越权访问风险
+}
+
+// ✅ 正确：用临时 URL
+@GetMapping("/download-url")
+public String getDownloadUrl(Long fileId) {
+    return uploadService.generateDownloadUrl(fileId, 30);
+    // 返回 https://cloud.meritdata.com/api/upload/download?token=xxx&expire=...
+}
+```
+
+### 6.2 文件名注入防护
+
+```java
+public static String sanitizeFileName(String fileName) {
+    // 移除路径分隔符
+    fileName = fileName.replaceAll("[/\\\\]", "");
+
+    // 移除 ..
+    fileName = fileName.replaceAll("\\.\\.", "");
+
+    // 移除 null 字节
+    fileName = fileName.replaceAll("\\x00", "");
+
+    // 限制长度
+    if (fileName.length() > 200) {
+        fileName = fileName.substring(0, 200);
+    }
+
+    return fileName;
+}
+```
+
+### 6.3 存储文件名 UUID
+
+```java
+public static String generateStoredFileName(String originalFileName) {
+    String ext = FilenameUtils.getExtension(originalFileName);  // "pdf"
+    String uuid = UUID.randomUUID().toString();
+    return uuid + "." + ext;  // "abc-uuid.pdf"
+}
+```
+
+**好处**：
+- 用户上传 `../etc/passwd` → 存储名变为 `uuid.pdf` → 不可能路径穿越
+- 攻击者拿到存储名也无法推断原始文件名
+
+---
+
+## 七、审计
+
+### 7.1 必须审计的 6 类操作
+
+| 操作 | 审计内容 |
+|------|---------|
+| 上传 | 谁、何时、joinId、文件名、大小、密级 |
+| 下载 | 谁、何时、fileId、joinId、用户密级 |
+| 删除 | 谁、何时、fileId、原因（业务删除 / 误删）|
+| 复制 | 谁、何时、源 fileId、目标 joinId |
+| 密级变更 | 谁、何时、fileId、旧密级、新密级、原因 |
+| 病毒检测命中 | 谁、何时、文件名、病毒名 |
+
+### 7.2 审计实现
+
+```java
+@Component
+public class FileAuditLogger {
+
+    @Autowired
+    private OperationLogService logService;
+
+    public void logUpload(String userId, String joinId, Long fileId, MultipartFile file) {
+        logService.log(
+            "FILE_UPLOAD",           // 操作类型
+            userId,                  // 操作人
+            "PfUpload",              // 实体
+            fileId,                  // 实体 ID
+            Map.of(
+                "joinId", joinId,
+                "fileName", file.getOriginalFilename(),
+                "fileSize", file.getSize(),
+                "fileHash", sha256(file)
+            )
+        );
+    }
+
+    public void logDownload(String userId, PfUpload upload) {
+        logService.log(
+            "FILE_DOWNLOAD",
+            userId,
+            "PfUpload",
+            upload.getId(),
+            Map.of(
+                "joinId", upload.getJoinId(),
+                "fileName", upload.getFileName(),
+                "secretLevel", upload.getSecretLevel()
+            )
+        );
+    }
+
+    // ... logDelete / logCopy / logSecretChange / logVirusDetected
+}
+```
+
+详见 `meritdata-platform-operation-log`。
+
+---
+
+## 八、安全配置（Nacos）
+
+```properties
+# 路径安全
+meritdata.cloud.file.path.use-uuid=true
+
+# 下载授权
+meritdata.cloud.file.download.require-business-permission=true
+meritdata.cloud.file.download.url-expire-minutes=30
+
+# 文件校验
+meritdata.cloud.file.max-size=104857600
+meritdata.cloud.file.allowed-types=pdf,docx,xlsx,pptx,jpg,png,zip
+meritdata.cloud.file.virus-scan.enabled=true
+
+# 审计
+meritdata.cloud.file.audit.enabled=true
+meritdata.cloud.file.audit.log-download=true
+```
+
+详见 `meritdata-platform-nacos-config/references/configuration-properties.md`。
+
+---
+
+## 九、与其他 skill 的协作
+
+| 安全维度 | 协作 skill |
+|---------|----------|
+| 密级管理 | `meritdata-platform-data-classification/references/hibernate-filter.md` |
+| 多租户隔离 | `meritdata-platform-platform-config/references/multi-tenant-and-audit.md` |
+| 通用安全规范 | `rules/security-rules.md` |
+| 审计日志 | `meritdata-platform-operation-log` |
+| Nacos 配置 | `meritdata-platform-nacos-config/references/configuration-properties.md` |
+| 平台资源权限 | `meritdata-platform-permission` |
+
+---
+
+## 十、典型攻击与防御
+
+| 攻击 | 防护 |
+|------|------|
+| 路径穿越（`../etc/passwd`）| 文件名 sanitization + UUID 存储名 |
+| MIME 伪造（.exe 改 .pdf）| 文件头验证 + 病毒扫描 |
+| 越权下载（猜 fileId）| L3 业务对象权限校验 |
+| 大文件攻击（10GB 上传）| 大小限制 100MB |
+| 文件名注入（`<script>`）| 文件名 sanitization |
+| 病毒传播 | ClamAV 扫描 |
+| 跨租户访问 | tenantId 字段隔离 |
+
+---
+
+## 十一、常见错误
+
+| 错误 | 后果 | 正确做法 |
+|------|------|---------|
+| 不校验密级 | 高级别文件被低级别用户下载 | L2 密级校验 |
+| 不校验租户 | 跨租户访问 | tenantId 过滤 |
+| 不校验业务权限 | 越权下载 | L3 业务对象权限 |
+| 暴露物理路径 | 路径穿越 | 临时下载 URL |
+| 不做病毒扫描 | 病毒传播 | ClamAV 集成 |
+| 不审计 | 事故无法追溯 | operation-log |
+| 不限制大小 | DoS | max-size 100MB |
+
+---
+
+**最后更新**：2026-09-08（v2.5.0 P1-B 新建）
+**来源**：石油/研发 `merit-cloud-file` security.md + security-rules §三 §五
+**整合位置**：`meritdata-platform-file/references/security.md`

package/skills/meritdata-platform-frontend/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: meritdata-platform-frontend
+description: |
+  前端组件与工程。平台提供的 Vue/React 组件（人员弹框/部门树/字典下拉/资源选择）；前端工程结构、构建、路由、权限点接入、API 调用约定。
+  触发场景：新二开前端模块启动；引入平台 UI 组件；前端打包/部署。
+  何时不用：纯后端代码 → 用 code-spec；接口设计 → 用 rules/api-design-rules.md。
+metadata:
+  version: "1.0.0"
+  author: petroleum+rd
+  source: petroleum+rd
+  date_added: "2026-09-07"
+  last_modified: "2026-09-08"
+  risk: low
+  layer: L2
+  sub-layer: L2-F
+  stack: frontend
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# 前端组件与工程（frontend）
+
+## 触发
+- 新二开前端模块冷启动
+- 需要平台 UI 组件（人员弹框/部门树/字典下拉/资源树）
+- 前端权限点接入（按钮级/菜单级）
+- 前端 API 调用规范
+- **前端多服务 HTTP 客户端**（业务 + 人员 + BPM + 附件跨 service 调用）🆕 v2.6.0
+
+## 不触发
+- 纯后端代码 → 用 `meritdata-platform-code-spec`
+- REST API 设计 → 用 `rules/api-design-rules.md`
+- 前端部署/Docker → L3 部署（待建）
+- 对外 WebApi（外部系统调平台）→ 用 `meritdata-platform-data-access/references/outbound/webapi.md`
+
+## 前置约束
+- URL 必须遵守 [rules/api-design-rules.md](../../rules/api-design-rules.md)（复数/小写/连字符）
+- 响应包装 `{ code, data, message }`
+- 组件按需引入，不全量打包
+- **HTTP 客户端必须用平台 plugin**（`@cloud-module-base/httpConfig/http-plugin`），禁止自建 axios / `Axios.defaults.headers.*`（v2.6.0 新增）
+
+## 路由
+- 平台组件清单 + props → [references/components.md](references/components.md)
+- 工程结构 + 路由约定 → [references/project-structure.md](references/project-structure.md)
+- 权限点接入 + API 调用 → [references/auth-and-api.md](references/auth-and-api.md)
+- **前端多服务 HTTP 客户端**（registry / plugin / 路径 / 验收）🆕 → [references/http-client/INDEX.md](references/http-client/INDEX.md)