@alanwang-merit/meritdata-platform-skill-package 1.0.10 → 1.0.12

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

@@ -1,423 +0,0 @@
-# 安全规范（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/references/auth-and-api.md

@@ -1,300 +0,0 @@
-# 前端权限与 API 调用（auth-and-api）
-
-> 前端按钮权限 / 路由权限 / 数据权限 + 与后端 API 的调用约定。
-
----
-
-## 1. 三层权限
-
-| 层级 | 控制内容 | 实现 |
-|------|---------|------|
-| 路由权限 | 哪些页面可访问 | 路由守卫 + meta.permission |
-| 按钮权限 | 页面内哪些按钮可见 | `v-permission` 指令 |
-| 数据权限 | 列表/详情看到哪些数据 | 后端控制，前端按权限过滤展示 |
-
----
-
-## 2. 路由权限
-
-### 2.1 路由 meta 配置
-
-```javascript
-const routes = [
-  {
-    path: '/orders',
-    component: () => import('@/views/order/List.vue'),
-    meta: {
-      requiresAuth: true,
-      permission: 'purchase_order:view'
-    }
-  }
-];
-```
-
-### 2.2 全局路由守卫
-
-```javascript
-// src/router/index.js
-import { useUserStore } from '@/store/user';
-import { hasPermission } from '@/utils/permission';
-
-router.beforeEach(async (to, from, next) => {
-  const userStore = useUserStore();
-
-  // 1. 不需要登录
-  if (!to.meta.requiresAuth) {
-    return next();
-  }
-
-  // 2. 未登录跳转登录
-  if (!userStore.token) {
-    return next('/login');
-  }
-
-  // 3. 已登录但没加载用户信息
-  if (!userStore.userInfo) {
-    await userStore.fetchUserInfo();
-    await userStore.fetchPermissions();
-  }
-
-  // 4. 校验权限
-  if (to.meta.permission && !hasPermission(to.meta.permission)) {
-    ElMessage.error('无访问权限');
-    return next('/403');
-  }
-
-  next();
-});
-```
-
----
-
-## 3. 按钮权限
-
-### 3.1 v-permission 指令
-
-```vue
-<template>
-  <el-button v-permission="'purchase_order:create'" @click="handleCreate">
-    新建采购订单
-  </el-button>
-
-  <el-button v-permission="'purchase_order:delete'" @click="handleDelete">
-    删除
-  </el-button>
-</template>
-
-<script setup>
-// 全局注册（在 main.js）
-app.directive('permission', {
-  mounted(el, binding) {
-    const required = binding.value;
-    const userStore = useUserStore();
-    if (!userStore.permissions.includes(required)) {
-      el.parentNode && el.parentNode.removeChild(el);
-    }
-  }
-});
-</script>
-```
-
-### 3.2 ❌ 反例：前端写死角色
-
-```vue
-<!-- ❌ 错：写死角色 -->
-<el-button v-if="userStore.userInfo.role === 'admin'">
-  删除
-</el-button>
-
-<!-- ✅ 正确：用权限点 -->
-<el-button v-permission="'purchase_order:delete'">
-  删除
-</el-button>
-```
-
----
-
-## 4. 数据权限
-
-### 4.1 原则
-
-**前端不控制数据权限，只控制展示**。
-
-```vue
-<!-- ✅ 正确：调后端 API，由后端按用户权限过滤 -->
-<template>
-  <el-table :data="orderList">
-    <el-table-column prop="orderNo" label="订单号" />
-    <el-table-column prop="amount" label="金额" />
-    <!-- 列表内容由后端按当前用户权限过滤后返回 -->
-  </el-table>
-</template>
-```
-
-### 4.2 ❌ 反例：前端过滤敏感字段
-
-```vue
-<!-- ❌ 错：前端隐藏字段 -->
-<el-table :data="orderList">
-  <el-table-column v-if="canSeeAmount" prop="amount" label="金额" />
-</el-table>
-
-<!-- 攻击者可以直接调 API 拿到 amount -->
-```
-
----
-
-## 5. API 调用约定
-
-### 5.1 URL 规范
-
-```
-GET    /api/v1/purchase-orders           列表
-GET    /api/v1/purchase-orders/{id}      详情
-POST   /api/v1/purchase-orders           创建
-PUT    /api/v1/purchase-orders/{id}      更新
-DELETE /api/v1/purchase-orders/{id}      删除
-POST   /api/v1/purchase-orders/{id}/submit  自定义动作
-```
-
-详见 [rules/api-design-rules.md](../../rules/api-design-rules.md)。
-
-### 5.2 请求 / 响应格式
-
-**请求**：
-
-```json
-POST /api/v1/purchase-orders
-Content-Type: application/json
-Authorization: Bearer eyJhbGc...
-
-{
-  "orderNo": "PO20260907001",
-  "applicantUserId": "10001",
-  "items": [...]
-}
-```
-
-**响应**：
-
-```json
-{
-  "code": 200,
-  "data": {
-    "id": 12345,
-    "orderNo": "PO20260907001",
-    "status": "DRAFT"
-  },
-  "message": "success"
-}
-```
-
-### 5.3 错误处理
-
-| HTTP | code | 含义 | 前端处理 |
-|------|------|------|---------|
-| 200 | 400 | 业务校验失败 | ElMessage.error(message) |
-| 200 | 401 | 未登录 | 跳转登录 |
-| 200 | 403 | 无权限 | ElMessage.error("无权限") |
-| 401 | - | Token 过期 | 清 token + 跳转登录 |
-| 500 | - | 服务器错误 | ElMessage.error("服务异常") |
-
----
-
-## 6. Token 管理
-
-### 6.1 存储
-
-```javascript
-// src/utils/auth.js
-const TOKEN_KEY = 'meritdata_token';
-
-export function getToken() {
-  return localStorage.getItem(TOKEN_KEY);
-}
-
-export function setToken(token) {
-  localStorage.setItem(TOKEN_KEY, token);
-}
-
-export function removeToken() {
-  localStorage.removeItem(TOKEN_KEY);
-}
-```
-
-### 6.2 ❌ 反例
-
-- ❌ Token 存 cookie（无 httpOnly → XSS 可盗）
-- ❌ Token 存 sessionStorage（关闭浏览器就丢）
-- ❌ Token 明文存 localStorage + 无加密（高风险场景）
-
-**生产环境建议**：Token 存 httpOnly cookie + 前端用 Refresh Token 机制。
-
-### 6.3 Token 刷新
-
-```javascript
-// request.js 响应拦截器
-request.interceptors.response.use(
-  response => response.data,
-  async error => {
-    const originalRequest = error.config;
-
-    // 401 + 不是刷新接口 + 没重试过
-    if (error.response?.status === 401 && !originalRequest._retry) {
-      originalRequest._retry = true;
-
-      try {
-        const newToken = await refreshTokenApi();
-        setToken(newToken);
-        originalRequest.headers['Authorization'] = `Bearer ${newToken}`;
-        return request(originalRequest);  // 重试原请求
-      } catch (refreshError) {
-        removeToken();
-        window.location.href = '/login';
-        return Promise.reject(refreshError);
-      }
-    }
-
-    return Promise.reject(error);
-  }
-);
-```
-
----
-
-## 7. 表单提交约定
-
-### 7.1 提交前校验
-
-```vue
-<template>
-  <el-form :model="form" :rules="rules" ref="formRef">
-    <el-form-item label="订单号" prop="orderNo">
-      <el-input v-model="form.orderNo" />
-    </el-form-item>
-  </el-form>
-</template>
-
-<script setup>
-const rules = {
-  orderNo: [
-    { required: true, message: '请输入订单号', trigger: 'blur' },
-    { min: 5, max: 64, message: '长度 5-64', trigger: 'blur' }
-  ]
-};
-</script>
-```
-
-### 7.2 ❌ 反例：仅前端校验
-
-前端校验**仅用于 UX**，**不能作为安全屏障**。后端必须再次校验。
-
----
-
-## 8. 关联阅读
-
-- [components.md](components.md) — 平台组件
-- [project-structure.md](project-structure.md) — 工程结构
-- [rules/api-design-rules.md](../../rules/api-design-rules.md) — API 设计
-- [rules/security-rules.md](../../rules/security-rules.md) — 安全规范
-- [SKILL.md](../SKILL.md)