npm - @alanwang-merit/meritdata-platform-skill-package - Versions diffs - 1.0.10 → 1.0.12 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (631) hide show

package/skills/meritdata-platform-data-classification/references/hibernate-filter.md DELETED Viewed

@@ -1,255 +0,0 @@
-# Hibernate 数据密级过滤（hibernate-filter）
-> **目的**：补齐 v2.4.0 复核发现的覆盖缺口——研发版 `meritdata-platform-data-secret` 的 `SECRET_LEVEL` 字段规范 + `@EnableDataSecretFilter` 注解式启用。
-> **场景**：敏感字段（身份证 / 手机号 / 银行卡 / 薪资）按用户密级自动脱敏。
-> **来源**：研发版 `meritdata-platform-data-secret` v1.0.0 + dev-docs 10_三平台服务-3.4多系统集成+3.5数据密级 + dev-docs 23-24_1.17资源数据密级。
----
-## 一、`SECRET_LEVEL` 字段规范
-### 1.1 5 级密级定义
-| 级别 | 名称 | 说明 | 举例 |
-|:--:|------|------|------|
-| **1** | 公开 | 所有用户可见 | 用户名、状态 |
-| **2** | 内部 | 内部员工可见 | 工号、部门 |
-| **3** | 秘密 | 指定角色可见 | 邮箱、手机号 |
-| **4** | 机密 | 高级别角色可见 | 身份证、银行卡 |
-| **5** | 绝密 | 仅管理员可见 | 薪资、密钥 |
-### 1.2 Entity 加 `SECRET_LEVEL` 字段
-```java
-@Entity
-@Table(name = "T_USER")
-public class User {
-    private Long id;
-    private String phone;       // 敏感字段
-    /**
-     * 数据密级（1-5）
-     * 必须配合 @EnableDataSecretFilter 才生效
-     */
-    @Column(name = "SECRET_LEVEL")
-    private Integer secretLevel;
-}
-```
-### 1.3 建表 DDL
-```sql
-ALTER TABLE T_USER ADD COLUMN SECRET_LEVEL INT DEFAULT 1 COMMENT '数据密级（1-5）';
-```
----
-## 二、`@EnableDataSecretFilter` 启用
-### 2.1 应用启动类加注解
-```java
-@SpringBootApplication
-@EnableDataSecretFilter  // 启用平台数据密级过滤
-public class YourApplication { ... }
-```
-### 2.2 效果（按用户密级自动脱敏）
-| 用户密级 | 字段值 | 渲染结果 |
-|:-------:|--------|----------|
-| 1 | `13812341234` | `138****1234` |
-| 2 | `13812341234` | `138****1234` |
-| 3 | `13812341234` | `138****1234` |
-| 4 | `13812341234` | `138****1234`（需额外授权）|
-| 5 | `13812341234` | `13812341234`（原始值）|
-**核心规则**：用户密级 **<** 字段密级 → 脱敏；用户密级 **≥** 字段密级 → 原始。
-### 2.3 脱敏规则（平台默认）
-| 字段类型 | 脱敏规则 | 示例 |
-|---------|---------|------|
-| 手机号 | 保留前 3 后 4 | `138****1234` |
-| 身份证 | 保留前 6 后 4 | `110101****1234` |
-| 银行卡 | 保留前 4 后 4 | `6228****5678` |
-| 邮箱 | 保留前 2 + `***` + 域名 | `zh***@example.com` |
-| 姓名 | 保留姓 + `**` | `张**` |
-| 地址 | 仅显示省市 | `北京市朝阳区****` |
----
-## 三、1.17 平台接口（8 个子接口）
-### 3.1 接口速查
-| # | 接口 | 方法 | 路径 | 用途 |
-|:-:|------|:--:|------|------|
-| 1 | 密级范围 | GET | `/api/secret/range` | 获取 1-5 级密级定义 |
-| 2 | 密级字典 | GET | `/api/secret/dict` | 密级中文名映射 |
-| 3 | 资源密级关联 | GET | `/api/secret/resource` | 资源→密级映射 |
-| 4 | 设置资源密级 | POST | `/api/secret/resource/set` | 配置资源密级 |
-| 5 | 字段密级配置 | POST | `/api/secret/field/config` | 配置字段密级 |
-| 6 | 用户密级查询 | GET | `/api/secret/user/level` | 当前用户密级 |
-| 7 | 字段密级查询 | GET | `/api/secret/field/level` | 查询字段密级 |
-| 8 | 密级审计日志 | GET | `/api/secret/audit/log` | 密级访问日志 |
-### 3.2 Feign Client 模板
-```java
-@FeignClient(name = "cloud-system-manage")
-public interface SecretFeignClient {
-    @GetMapping("/api/secret/range")
-    ResultBody<List<SecretLevelVO>> getSecretRange();
-    @GetMapping("/api/secret/user/level")
-    ResultBody<Integer> getCurrentUserSecretLevel();
-    @GetMapping("/api/secret/field/level")
-    ResultBody<Integer> getFieldSecretLevel(@RequestParam String tableName,
-                                            @RequestParam String fieldName);
-}
-```
-### 3.3 与 Hibernate Filter 联动
-```java
-@Service
-public class UserQueryService {
-    @Autowired
-    private SecretFeignClient secretClient;
-    /**
-     * 查询用户（按当前用户密级自动过滤）
-     */
-    public List<UserVO> listUsers() {
-        // 1. 获取当前用户密级
-        Integer userLevel = secretClient.getCurrentUserSecretLevel().getData();
-        // 2. 查询（Hibernate Filter 自动按 userLevel 过滤敏感字段）
-        List<User> users = userRepository.findAll();
-        // 3. 字段已自动脱敏（无需手动处理）
-        return UserVO.from(users);
-    }
-}
-```
----
-## 四、行级 / 列级权限差异
-| 维度 | Hibernate Filter（`@EnableDataSecretFilter`）| DAM 权限 |
-|------|------------------------------------------|----------|
-| **粒度** | 列级（字段级脱敏）| 行级（数据可见范围）|
-| **机制** | 按用户密级过滤字段值 | 按角色过滤查询条件 |
-| **适用** | 身份证/手机号/银行卡 | "只能看本部门数据" |
-| **配置** | 字段加 `SECRET_LEVEL` | DAM 资源授权 |
-| **生效** | 自动（无需写代码）| 自动（无需写代码）|
-**两者互补**：
-- Hibernate Filter 管**字段值**（脱敏）
-- DAM 管**数据集**（行级）
-- 二开业务表**必须两者都启用**才完整
----
-## 五、典型场景
-### 5.1 用户表 + 密级字段
-```sql
-CREATE TABLE T_USER (
-    ID BIGINT PRIMARY KEY,
-    NAME VARCHAR(100),
-    PHONE VARCHAR(20),
-    ID_CARD VARCHAR(20),
-    SECRET_LEVEL INT DEFAULT 1
-);
-```
-```java
-@Entity
-@Table(name = "T_USER")
-public class User {
-    private Long id;
-    private String name;
-    @Column(name = "PHONE")
-    private String phone;       // 默认密级（由 Hibernate Filter 配置）
-    @Column(name = "ID_CARD")
-    private String idCard;      // 默认密级
-    @Column(name = "SECRET_LEVEL")
-    private Integer secretLevel;
-}
-```
-### 5.2 自定义字段密级（注解）
-```java
-public class FieldSecretLevelConfig {
-    /** phone 字段密级 = 3（秘密）*/
-    public static final Map<String, Integer> FIELD_LEVELS = Map.of(
-        "phone", 3,
-        "id_card", 4,
-        "email", 3
-    );
-}
-```
-### 5.3 跨服务携带密级
-```java
-@Service
-public class UserExportService {
-    @Autowired
-    private SecretFeignClient secretClient;
-    /**
-     * 导出用户（密级跟随 session 传递）
-     */
-    public byte[] exportUsers() {
-        Integer userLevel = secretClient.getCurrentUserSecretLevel().getData();
-        // 调用下游服务时，session 自动携带用户密级
-        // Feign interceptor 会把密级放到 header
-        return downstreamClient.exportUsers(userLevel);
-    }
-}
-```
----
-## 六、与其他 skill 的协作
-| 场景 | 协作 skill |
-|------|----------|
-| 字段脱敏（masking）通用规则 | `meritdata-platform-data-classification/references/masking.md` |
-| DAM 行级权限 | `meritdata-platform-data-classification/references/integration-with-dam.md` |
-| 平台资源权限点（IDamService）| `meritdata-platform-org-user-api` |
-| Feign 批量装配 + 跨服务密级传递 | `meritdata-platform-data-access/references/feign-guide.md` |
-| 多系统同步时携带密级 | 攻略-09（`masterdata-sync-攻略/INDEX.md`）|
----
-## 七、常见错误
-| 错误 | 后果 | 正确做法 |
-|------|------|---------|
-| 不用密级手动脱敏 | 漏字段 | `@EnableDataSecretFilter` |
-| 不加 `SECRET_LEVEL` | 字段全公开 | 业务表都加 |
-| 跨服务不带密级 | 越权访问 | Session 携带密级 |
-| 密级过大 | 数据全脱敏 | 按需最小化 |
-| Hibernate Filter 与 DAM 二选一 | 防护不完整 | 两者都启用 |
-| 密级配置不可见 | 业务方误用 | 在 1.17 平台接口统一管理 |
----
-**最后更新**：2026-09-08（v2.4.0 P1 补齐）
-**来源**：研发版 `meritdata-platform-data-secret` v1.0.0 + dev-docs 10 / 23-24
-**整合位置**：`meritdata-platform-data-classification/references/hibernate-filter.md`

package/skills/meritdata-platform-data-classification/references/integration-with-dam.md DELETED Viewed

@@ -1,206 +0,0 @@
-# 数据密级与 DAM 集成（data-classification）
-> DAM（Data Access Management）是平台统一的数据权限管理。密级策略最终落地到 DAM。
----
-## 1. DAM 资源模型
-```
-Resource: order:view            → 资源标识
-   ↓
-ScopeRule: org_id IN (...)      → 行级过滤规则
-FieldRule: cost, profit, ...   → 列级过滤规则
-   ↓
-Grant: ROLE_FINANCE → order:view:view
-```
-## 2. 行级权限
-### 2.1 在 DAM 中配置
-资源：`order:view`
-范围规则：
-```sql
--- 普通员工
-org_id = ${current_user_org_id}
--- 部门经理
-org_id IN (
-    SELECT id FROM t_org
-    WHERE path LIKE CONCAT(${current_user_org_path}, '%')
-)
--- 总经理
-1 = 1   -- 全部
-```
-### 2.2 业务代码无感知
-```java
-@GetMapping("/orders")
-public List<OrderVO> list() {
-    return orderService.list();
-}
-```
-平台通过 **MyBatis Interceptor** 自动追加 SQL：
-```sql
--- 业务代码写的是
-SELECT * FROM t_order WHERE status = "PAID"
--- 实际执行的是
-SELECT * FROM t_order
-WHERE status = "PAID"
-  AND org_id IN (子部门)
-```
-## 3. 列级权限
-### 3.1 在 DAM 中配置
-资源：`order.cost:view`
-授权：`ROLE_FINANCE`
-### 3.2 业务代码
-```java
-@Data
-public class OrderVO {
-    private String orderNo;
-    private BigDecimal amount;
-    @SensitiveField(resource = "order.cost:view")
-    private BigDecimal cost;  // 无权限 → null
-}
-```
-或查询时通过 `Projection`：
-```java
-public OrderVO toVO(Order order) {
-    OrderVO vo = new OrderVO();
-    vo.setOrderNo(order.getOrderNo());
-    vo.setAmount(order.getAmount());
-    if (hasPermission("order.cost:view")) {
-        vo.setCost(order.getCost());
-    }
-    return vo;
-}
-```
-## 4. 数据导出审计
-### 4.1 配置
-DAM 资源：`order:export`
-### 4.2 业务代码
-```java
-@PostMapping("/orders/export")
-@DamAudit(module = "ORDER", action = "EXPORT")
-public void export(@RequestBody ExportRequest req, HttpServletResponse response) {
-    // 平台自动记录：
-    // - 导出人 userId
-    // - 导出时间
-    // - 导出范围（按行级权限过滤后的数据量）
-    // - 敏感字段访问标记
-    List<OrderVO> orders = orderService.list(req);
-    EasyExcel.write(response.getOutputStream(), OrderVO.class).doWrite(orders);
-}
-```
-## 5. 权限冲突处理
-### 5.1 多个角色权限冲突
-DAM 支持多角色取并集/交集：
-| 策略 | 含义 |
-|------|------|
-| ANY（任一通过）| 用户任一角色有权限 → 通过 |
-| ALL（全部要求）| 用户所有角色都需要权限 → 通过 |
-### 5.2 权限继承
-```
-部门权限 → 子部门继承
-   ↓
-ROLE → 用户继承
-```
-## 6. 缓存与权限一致性
-### 6.1 问题
-用户 A 的权限变后，缓存仍是旧权限。
-### 6.2 方案
-| 方案 | 实现 |
-|------|------|
-| 权限变更广播 | DAM 发布事件，业务订阅清缓存 |
-| 短 TTL | 权限缓存 5 分钟 TTL（牺牲实时性换简单）|
-| 强制透传 | 关键操作不走权限缓存 |
-```java
-@Cacheable(value = "userPerms", key = "#userId")
-public List<String> getUserPermissions(String userId) {
-    return damClient.listPermissions(userId);
-}
-// DAM 权限变更事件
-@EventListener
-public void onPermissionChange(PermissionChangeEvent event) {
-    cacheManager.evict("userPerms", event.getUserId());
-}
-```
-## 7. ❌ 反模式
-### 7.1 ❌ 业务代码自己写行级过滤
-```java
-// ❌ 错
-@GetMapping("/orders")
-public List<Order> list() {
-    UserDTO user = SecurityUtils.getCurrentUser();
-    return orderRepository.findByOrgId(user.getOrgId());
-}
-```
-✅ 用 DAM 自动注入。
-### 7.2 ❌ DAM 资源和业务功能命名不一致
-```java
-// ❌ 错：业务用 order:list，资源配置用 order:view
-public List<Order> listOrders() {
-    damClient.checkPermission("order:list");  // 资源配置是 order:view → 失败
-}
-```
-✅ 业务和 DAM 资源命名保持一致。
-### 7.3 ❌ 在前端做权限控制
-```javascript
-// ❌ 错：前端判断权限
-if (user.hasPermission('order.cost:view')) {
-    showCostField();
-}
-```
-✅ 后端不返回字段。
-## 8. 关联阅读
-- [guide.md](guide.md) — 密级管理基础
-- [masking.md](masking.md) — 字段脱敏
-- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-data-classification/references/masking.md DELETED Viewed

@@ -1,214 +0,0 @@
-# 字段脱敏详解（data-classification）
-> 字段脱敏方案、自定义规则、脱敏与权限的区别。
----
-## 1. 脱敏策略
-### 1.1 显示脱敏
-**定义**：前端展示时脱敏，数据库存的是明文。
-**示例**：员工列表页面，手机号显示 "138****5678"。
-```java
-@Data
-public class UserVO {
-    @Sensitive(type = SensitiveType.MOBILE)
-    private String phone;  // 明文存储，显示脱敏
-}
-```
-### 1.2 存储脱敏
-**定义**：数据库存的是密文/脱敏值，明文不出现在 DB。
-**示例**：身份证号入库时直接加密存储。
-```java
-@EncryptedField(algorithm = "SM4")
-private String idCard;
-```
-**注意**：存储脱敏后无法直接检索（如 LIKE 查询）；需要做索引字段。
-### 1.3 传输脱敏
-**定义**：网络传输时加密（如 HTTPS），DB 存明文。
-**通常不需二开处理**：由平台统一 HTTPS 处理。
-## 2. 注解方式（推荐）
-### 2.1 内置脱敏类型
-| SensitiveType | 输入示例 | 输出示例 | 适用 |
-|---------------|---------|---------|------|
-| MOBILE | 13812345678 | 138****5678 | 手机号 |
-| ID_CARD | 110101199001011234 | 110101********1234 | 身份证 |
-| BANK_CARD | 6225123456781234 | 6225 **** **** 1234 | 银行卡 |
-| EMAIL | zhangsan@example.com | z****@example.com | 邮箱 |
-| NAME | 张三丰 | 张*丰 | 中文姓名 |
-| ADDRESS | 北京市朝阳区xx路100号 | 北京市朝阳区**** | 详细地址 |
-| PASSWORD | 任意 | ****** | 密码（建议不返回） |
-| CUSTOM | 自定义 | 自定义 | 见 §3 |
-### 2.2 用法
-```java
-@Data
-public class UserVO {
-    private String name;
-    @Sensitive(type = SensitiveType.MOBILE)
-    private String phone;
-    @Sensitive(type = SensitiveType.ID_CARD)
-    private String idCard;
-    @Sensitive(type = SensitiveType.BANK_CARD)
-    private String bankCard;
-    @Sensitive(type = SensitiveType.EMAIL)
-    private String email;
-}
-```
-### 2.3 序列化时生效
-脱敏在序列化（Jackson）时自动应用，业务代码无感知。
-```java
-User user = new User("张三", "13812345678", "110101199001011234");
-UserVO vo = UserVO.from(user);
-String json = objectMapper.writeValueAsString(vo);
-// {"name":"张三","phone":"138****5678","idCard":"110101********1234"}
-```
-## 3. 自定义脱敏
-### 3.1 实现 SensitiveStrategy
-```java
-@Component
-public class CarNumberStrategy implements SensitiveStrategy {
-    @Override
-    public SensitiveType getType() {
-        return SensitiveType.CUSTOM;
-    }
-    @Override
-    public String mask(String value) {
-        if (value == null || value.length() < 4) return value;
-        // 京A12345 → 京A***45
-        return value.substring(0, 2) + "***" + value.substring(value.length() - 2);
-    }
-}
-```
-### 3.2 使用自定义策略
-```java
-@Sensitive(type = SensitiveType.CUSTOM, strategy = CarNumberStrategy.class)
-private String carNumber;
-```
-## 4. 部分脱敏（按角色）
-### 4.1 场景
-财务可看完整银行卡号；其他角色看脱敏的。
-### 4.2 方案：列级权限 + 字段脱敏组合
-```java
-// 列权限：财务角色可见完整字段
-@SensitiveField(resource = "bankCard:full")
-private String bankCard;
-// 业务上：先判断权限，再决定输出
-public UserVO toVO(User user) {
-    UserVO vo = new UserVO();
-    if (hasPermission("bankCard:full")) {
-        vo.setBankCard(user.getBankCard());  // 完整
-    } else {
-        vo.setBankCard(user.getBankCard());  // 由 @Sensitive 脱敏
-    }
-    return vo;
-}
-```
-## 5. 列表脱敏（批量）
-```java
-@GetMapping("/users")
-public List<UserVO> list() {
-    return userRepository.findAll().stream()
-        .map(UserVO::from)
-        .collect(Collectors.toList());
-}
-```
-脱敏注解在 VO 上 → 整个列表序列化时自动脱敏。
-## 6. 导出脱敏
-### 6.1 场景
-导出 Excel 时也需脱敏（不能因为导出而泄露）。
-### 6.2 方案
-```java
-@GetMapping("/users/export")
-public void export(HttpServletResponse response) {
-    List<UserVO> users = userService.listForExport();
-    // UserVO 上有 @Sensitive 注解 → EasyExcel 自动脱敏
-    EasyExcel.write(response.getOutputStream(), UserVO.class)
-        .doWrite(users);
-}
-```
-平台已集成 EasyExcel 脱敏序列化器。
-## 7. ❌ 反模式
-### 7.1 ❌ 业务代码自己脱敏
-```java
-// ❌ 错：业务代码自己实现脱敏
-public String maskPhone(String phone) {
-    return phone.substring(0, 3) + "****" + phone.substring(7);
-}
-```
-✅ 用平台 `@Sensitive` 注解（统一规则）。
-### 7.2 ❌ 前端脱敏
-```javascript
-// ❌ 错：前端展示前自己截取
-function maskPhone(phone) {
-    return phone.substring(0, 3) + '****' + phone.substring(7);
-}
-```
-✅ 后端不返回完整字段，前端无字段可显示。
-### 7.3 ❌ 脱敏后还能反推
-```java
-// ❌ 错：脱敏后仍能反推（如脱敏规则泄露）
-@Sensitive(type = SensitiveType.CUSTOM)  // 客户自定义，但可反推
-```
-✅ 严格遵循行业标准脱敏规则。
-## 8. 关联阅读
-- [guide.md](guide.md) — 密级管理基础
-- [integration-with-dam.md](integration-with-dam.md) — 与 DAM 集成
-- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-domain-model/SKILL.md DELETED Viewed

@@ -1,41 +0,0 @@
----
-name: meritdata-platform-domain-model
-description: |
-  业务建模方法论。从需求识别实体 / 聚合根 / 一对多 / 多对多 / 树 / 跨模块引用 / 外部平台实体；按小写蛇形设计业务表、索引、外键策略、事务边界、QueryDSL 联表、DTO；把人员组织字典附件流程等平台语义路由到平台公共 Skill。
-  触发场景：新二开业务模块的数据库表设计、聚合根设计、多表关联、跨服务引用。
-  何时不用：纯加字段 / 改字段类型（用 data-boundary）；已有实体的查询改写（用 entities）。
-metadata:
-  version: "1.0.0"
-  author: petroleum+rd
-  source: petroleum+rd
-  date_added: "2026-09-07"
-  last_modified: "2026-09-07"
-  risk: medium
-  layer: L2
-  sub-layer: L2-M
-  stack: methodology
-allowed-tools: Read, Grep, Glob, Bash
----
-# 业务建模方法论（domain-model）
-## 触发
-- 新二开业务模块启动，需要先做数据库设计
-- 现有业务模块重构，需要重新划分聚合
-- 复杂查询场景，需要评估 DTO / 投影
-- 涉及人员/组织/角色/字典/附件/流程 6 大平台语义字段的实体设计
-## 不触发
-- 已完成建模，只做加字段 / 改类型 → 用 [rules/code-dev-rules.md §七](../../rules/code-dev-rules.md#七数据库设计) + data-boundary
-- 已有实体的查询改写 → 用 `meritdata-platform-entities`
-- 前端展示层设计 → 用 `meritdata-platform-frontend`
-## 前置约束
-- 4 条铁律见 [rules/code-dev-rules.md §8.2](../../rules/code-dev-rules.md#82-业务建模规则domain-model)
-- 边界判定：必须先调 `meritdata-platform-data-boundary` 判定表所有权
-## 路由
-- 反模式案例 + 正模式代码 → [references/anti-patterns.md](references/anti-patterns.md)
-- 关系模式选择（一对多 / 多对多 / 树 / 跨服务）→ [references/relationship-patterns.md](references/relationship-patterns.md)
-- review-checklist → [references/review-checklist.md](references/review-checklist.md)
-- CI 检测命令 → [references/validate-rules.md](references/validate-rules.md)