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

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

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

@@ -0,0 +1,206 @@
+# 数据密级与 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

@@ -0,0 +1,214 @@
+# 字段脱敏详解（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

@@ -0,0 +1,41 @@
+---
+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)