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

package/skills/meritdata-platform-data-secret/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: meritdata-platform-data-secret
+description: MeritData 数据密级。用于密级标签、行级权限、数据脱敏展示。
+metadata:
+  version: "1.0.0"
+  author: 技术平台部门架构组
+  source: company
+  date_added: "2026-09-01"
+  last_updated: "2026-09-01"
+  risk: high
+  allowed-tools: Read, Grep, Glob
+---
+
+## ⭐ MUST DO
+
+**密级字段在 DB、API、日志、前端全链路显式标注；特权访问必须审计。**
+
+## 触发条件 / 不适用
+
+**适用**：
+- 字段密级标签（公开/内部/秘密/机密）
+- 行级权限过滤
+- 密级降级展示
+
+**不适用**：
+- 通用数据边界 → `.claude/rules/data-boundary-rules.md`
+- 国密算法 → `meritdata-platform-crypto-gm`
+
+## 工作方式
+
+1. 实体继承 `CloudBaseEntity`（自带 `dataSecret` 字段，5 级 10/20/30/40/50）
+2. 方法级启用：`@EnableDataSecretFilter`（**实测 jar 中存在**，非 `@DataSecret`）
+3. API 层：方法标注后 `DataSecretInterceptor` 自动生效
+4. 全工程开关：Nacos `use-platform-secret` / `emp-data-secret` / `resource-data-secret`（任一为 false 跳过）
+5. 前端：根据用户密级脱敏展示
+
+## 🚨 常见错误
+
+| 错误 | 后果 | 正确做法 |
+| --- | --- | --- |
+| 漏标密级字段 | 数据泄露 | 全部显式标注 |
+| 特权访问无审计 | 无法追溯 | 强制审计日志 |
+
+## 边界
+
+- **不在本 skill 范围的**：
+  - 数据边界硬门禁 → `.claude/rules/data-boundary-rules.md`
+  - 国密算法 → `meritdata-platform-crypto-gm`
+- **强制要求**：密级标签必须全链路标注

package/skills/meritdata-platform-data-secret/agents/openai.yaml

@@ -0,0 +1,13 @@
+display_name: "MeritData 数据密级"
+short_description: "密级标签、行级权限、数据脱敏"
+default_prompt: |
+  meritdata-platform-data-secret 处理数据密级场景。
+
+  适用场景：
+  - 字段密级标签
+  - 行级权限过滤
+  - 密级降级展示
+
+  强制约束：
+  - 密级字段全链路标注（DB/API/日志/前端）
+  - 特权访问必须审计

package/skills/meritdata-platform-data-secret/references/data-secret.md

@@ -0,0 +1,89 @@
+## 前置条件
+
+> ⚠️ 本规范已修订（2026-09-10 第二轮）：
+> - 唯一方法级注解：`@EnableDataSecretFilter` / `@EnableSecretFilter`（**均标在方法上**，不是启动类）
+> - ~~`@DataSecret`~~ 注解**不存在**于 cloud-module-base 的 base/tenancy/ 包下，已删除
+> - 全工程开关：Nacos `use-platform-secret` / `emp-data-secret` / `resource-data-secret`（任一为 false 时 DataSecretInterceptor 跳过）
+> - 实测 DataSecretInterceptor 是请求级 Servlet Filter
+> - 字段名 DATA_SECRET（不是 SECRET_LEVEL），类型 BIGINT（不是 INT），值 10/20/30/40/50（不是 1/2/3/4/5）
+> - 详见 references/secret-level-spec.md
+
+
+Maven 依赖已包含在 `cloud-starter-core` 基础包中，二开项目继承平台脚手架后自动引入，无需额外配置。
+
+## 原理
+
+基于 Hibernate `@Filter` 实现。只有目标项目已注册相应拦截器、当前会话带有密级信息且查询路径启用了过滤时，`@EnableDataSecretFilter` 才能生效。
+
+**过滤规则**: 用户只能看到**低于或等于**其自身密级的数据，高于用户密级的数据被自动拦截。
+
+---
+
+## 使用方式
+
+### 方法级 `@EnableDataSecretFilter` 标注（实测 DataSecretInterceptor 是请求级 Servlet Filter）
+
+在需要过滤的查询方法上添加 `@EnableDataSecretFilter`：**标在方法上，不是启动类**：
+
+```java
+@LogOperation(type = "select")
+@EnableDataSecretFilter
+public List<Emp> selectEmpList() {
+    return empRepository.findAll();
+}
+```
+
+### 使用前验证
+
+先查看目标项目中 `@EnableDataSecretFilter` 的已有用法，确认该版本支持的方法或类型目标。不要仅根据实体上的 `@FilterDef` 假定运行时过滤已启用。
+
+---
+
+## 完整包路径（基于 2026-09-10 源码实测）
+
+| 类/注解 | 完整路径 | 所在模块 |
+|---------|------|---------|
+| `@EnableDataSecretFilter` | `com.meritdata.cloud.base.tenancy.EnableDataSecretFilter` | `cloud-module-base`（注解）|
+| `@EnableSecretFilter` | `com.meritdata.cloud.base.tenancy.EnableSecretFilter` | `cloud-module-base`（注解）|
+| `DataSecretInterceptor` | `com.meritdata.cloud.secret.interceptor.DataSecretInterceptor` | **`cloud-starter-core`**（⚠️ 不在 cloud-module-base）|
+| `SecretInfoDTO` | `com.meritdata.cloud.base.dto.SecretInfoDTO` | `cloud-module-base` |
+| `SecretConstEnum` | `com.meritdata.cloud.system.manager.basic.secret.util.SecretConstEnum` | `cloud-system-manage-module` |
+
+> ⚠️ **模块归属说明**：`DataSecretInterceptor` 实际位于 `cloud-starter-core` 模块（不是 `cloud-module-base`），包路径前缀是 `com.meritdata.cloud.secret.interceptor`（不是 `com.meritdata.cloud.base.tenancy`）。
+> 但 `@EnableDataSecretFilter` 注解仍在 `cloud-module-base` 模块的 `base.tenancy` 包下——两者在不同模块。
+
+---
+
+## 密级过滤注意事项
+
+1. 数据密级过滤只在查询时生效，**不阻止手动写入高密级数据**
+2. 依赖当前用户会话中的密级信息，确保 SessionUtils 正常工作
+3. 不得通过省略注解作为通用绕过方式；特权查看必须走已授权、可审计的独立路径。
+4. 至少验证一个允许访问和一个拒绝访问的密级用例。
+
+## ⚠️ 不存在的 SessionUtils 方法（AI 防错警示，2026-09-12 更新）
+
+> **核实警告**：以下方法名**在 `com.meritdata.cloud.utils.SessionUtils` 源码中不存在**——AI 或二开工程师可能编造这些方法名：
+> - ❌ `getUserDataSecret()`（**不存在**）
+> - ❌ `getUserSecret()`（**不存在**）
+> - ❌ `getDataSecret()`（**不存在**）
+> - ❌ `getCurrentDataSecret()`（**不存在**）
+> - ❌ `getSecretLevel()`（**不存在**）
+>
+> SessionUtils 实际 28 个 public 方法（与 `meritdata-platform-session` 技能描述一致）：
+>
+> | 类别 | 方法 |
+> |------|------|
+> | 用户相关 | `getUserId` / `getUserName` / `getEmpId` / `getEmp` / `getEmpName` / `getEmpCode` / `getCurrentUserName` / `getPrincipal` |
+> | 部门/组织 | `getDeptId` / `getDeptCode` / `getDept` / `getDeptName` / `getOrgId` / `getOrg` / `getOrgName` / `getOrgDlevelCode` / `getRootOrgId` / `getRootOrg` / `getAllDepts` / `getAllOrgs` |
+> | 角色/权限 | `getSysRoleCodes` / `getRoleCodes` / `getRoleNames` / `getRoleIds` / `getAuthoritiesIds` / `getWorkGroupIds` |
+> | 会话 | `getTenantId` / `getCurrentLoginIp` |
+>
+> **数据密级实际接口**：
+> 1. **HTTP 跨 JVM**：调用 `cloud-system-manage` 服务的 `POST /certificate/get-secret-relation`
+> 2. **同 JVM 内部**：`@Autowired CertificateController` → `getSecretRelation(request)` 返回 `SecretInfoDTO`（**完整 9 字段**）
+> 3. **数据访问层**：`sessionUtils.getEmp().getGrade()` + `QEmpData` / `QResourceData`
+>
+> **详见 `references/secret-level-spec.md`**（含 SecretInfoDTO 完整 9 字段 + 7 个密级接口 + 3 种获取方式 + 集成示例）
+
+---

package/skills/meritdata-platform-data-secret/references/secret-api.md

@@ -0,0 +1,35 @@
+# 数据密级 1.17 接口速查
+
+## 8 个子接口
+
+| 接口 | 方法 | 路径 |
+|------|------|------|
+| 密级范围 | GET | `/api/base/secret/range` |
+| 密级字典 | GET | `/api/base/secret/dict` |
+| 资源密级配置 | GET | `/api/base/secret/resource?resourceCode=xxx` |
+| 用户密级配置 | GET | `/api/base/secret/user?userId=xxx` |
+| 资源密级关联 | GET | `/api/base/secret/resourceRelation` |
+| 字段密级配置 | GET | `/api/base/secret/field?tableName=xxx&column=xxx` |
+| 设置资源密级 | POST | `/api/base/secret/resource/set` |
+| 设置字段密级 | POST | `/api/base/secret/field/set` |
+
+## 密级字典示例
+
+```json
+{
+  "code": 200,
+  "data": [
+    {"level": 1, "name": "公开", "color": "green"},
+    {"level": 2, "name": "内部", "color": "blue"},
+    {"level": 3, "name": "秘密", "color": "yellow"},
+    {"level": 4, "name": "机密", "color": "orange"},
+    {"level": 5, "name": "绝密", "color": "red"}
+  ]
+}
+```
+
+## 平台信息 1.5
+
+| 接口 | 路径 |
+|------|------|
+| 获取平台密级信息 | `/api/base/secret/info` |

package/skills/meritdata-platform-data-secret/references/secret-level-spec.md

@@ -0,0 +1,231 @@
+# 平台数据密级完整规范（基于源码实测，2026-09-12）
+
+> **来源**：
+> - `com.meritdata.cloud.base.dto.SecretInfoDTO`（位于 `cloud-module-base`）
+> - `com.meritdata.cloud.system.manager.controller.CertificateController`（位于 `cloud-system-manage-module`，含 `getSecretRelation` 等 7 个密级相关接口）
+
+---
+
+## 一、`SecretInfoDTO` 完整字段（9 个，基于源码实测）
+
+| # | 字段 | Java 类型 | 含义 | 备注 |
+|---|------|----------|------|------|
+| 1 | `usePlatformSecret` | `boolean` | 是否使用平台密级 | true=启用 |
+| 2 | `platformSecret` | `String` | 平台密级编码 | |
+| 3 | `platformSecretName` | `String` | 平台密级名称 | |
+| 4 | `empDataSecret` | `boolean` | 人员数据密级开关 | |
+| 5 | `resourceDataSecret` | `boolean` | 资源数据密级开关 | |
+| 6 | `dataSecretCode` | `String` | **数据密级编码**（最常用）| 数值越小密级越低 |
+| 7 | `dataSecretName` | `String` | 数据密级名称 | |
+| 8 | `secretConfig` | `LableSecretConfig` | 标签密级配置（前端用）| 含 fileLabelFlag/labelPositon/lableRuleArray |
+| 9 | `enableSecretConfig` | `Boolean` | 是否启用密级配置 | |
+
+> **⚠️ 重要**：之前我误以为 `getSecretRelation` 接口"只能取到 DataSecretCode"——**不对**。该接口返回**完整 `SecretInfoDTO` 对象**，包含全部 9 个字段。
+
+---
+
+## 二、CertificateController 密级相关 7 个接口（基于源码实测）
+
+| # | URL | HTTP | 方法 | 用途 | 返回 |
+|---|-----|------|------|------|------|
+| 1 | `/certificate/get-secret-relation` | POST | `getSecretRelation(request)` | **数据密级配置**（⭐ 核心）| `SecretInfoDTO`（9 字段）|
+| 2 | `/certificate/get-anon-secret-relation` | POST | `getAnonSecretRelation(request, userName)` | 数据密级配置（按用户名）| `SecretInfoDTO` |
+| 3 | `/certificate/get-secret-info-relation` | 默认 | `getSecretInfoRelation(request)` | 资源/人员/数据密级关联关系 | `Map`（含 empResourceList/empDataList/resourceDataList）|
+| 4 | `/certificate/get-lookup-secret-info` | 默认 | `getLookupSecretInfo(request)` | 密级字典（gradeList/resourceSecretList/dataSecretList）| `Map` |
+| 5 | `/certificate/get-secret-info` | POST | `getSecretInfo()` | 获取平台密级信息（含 secretLableShow 等）| `ResultBody` |
+| 6 | `/certificate/get-secret-lable-show` | 默认 | `getSecretLableShow()` | 获取密级标签显示开关 | `ResultBody<Boolean>` |
+| 7 | `/certificate/get-secret-data` | 默认 | `getSecretInfos()` | 获取密级标签展示（k-v 列表）| `ResultBody` |
+
+---
+
+## 三、3 种正确获取数据密级的方式
+
+### 方式 1：HTTP 跨 JVM 调用（最常用）
+
+```bash
+# 调用 cloud-system-manage 服务
+POST http://gateway/cloud-system-manage/certificate/get-secret-relation
+Headers:
+  resourceId: <资源ID>
+  resourceSecretCode: <资源密级编码>
+```
+
+**返回** `SecretInfoDTO` 完整对象，可获取全部 9 个字段。
+
+### 方式 2：同 JVM 内部 Feign 调用（同 JVM 推荐）
+
+```java
+@Autowired
+private CertificateController certificateController;
+
+SecretInfoDTO secret = (SecretInfoDTO) certificateController.getSecretRelation(request).getData();
+// 直接访问 9 个字段
+String dataSecretCode = secret.getDataSecretCode();    // 数据密级编码
+boolean empDataSecret = secret.isEmpDataSecret();      // 人员数据密级开关
+boolean resourceDataSecret = secret.isResourceDataSecret();
+String platformSecret = secret.getPlatformSecret();
+```
+
+### 方式 3：同 JVM 直接数据库访问（最底层）
+
+```java
+// 1. 获取当前用户的密级
+Emp currentEmp = sessionUtils.getEmp();
+String userSecret = currentEmp.getGrade();  // ⭐ 实际从 Emp.grade 字段
+
+// 2. 查 emp_data 表
+QEmpData empData = QEmpData.empData;
+String dataD = jpaQueryFactory.select(empData.dataSecret)
+    .from(empData)
+    .where(empData.empSecret.eq(userSecret))
+    .fetchOne();
+
+// 3. 查 resource_data 表（资源密级）
+QResourceData resourceData = QResourceData.resourceData;
+String dataS = jpaQueryFactory.select(resourceData.dataSecret)
+    .from(resourceData)
+    .where(resourceData.resourceSecret.eq(resource.getSecretCode()))
+    .fetchOne();
+
+// 4. 取较小值
+if (StrUtil.isNotBlank(dataS) && StrUtil.isNotBlank(dataD)) {
+    dataS = Integer.parseInt(dataS) > Integer.parseInt(dataD) ? dataD : dataS;
+}
+
+// 5. 查 lookup 表得到密级名称
+Lookup dataSecret = lookupService.findByPidAndCode(
+    SecretConstEnum.DATA_SECERT_PID.getValue(), dataS);
+```
+
+---
+
+## 四、`getSecretRelation` 完整逻辑（基于源码实测）
+
+```java
+@PostMapping("get-secret-relation")
+public ResultBody getSecretRelation(HttpServletRequest request) {
+    String resourceId = request.getHeader(RESOURCE_ID);
+    String resourceSecretCode = request.getHeader("resourceSecretCode");
+
+    // 1. 检查平台密级总开关
+    if (meritdataCloudProperties.getUsePlatformSecret() && !enableTenancy) {
+        // 2. 资源密级（从 resource_data 表查）
+        if (meritdataCloudProperties.isResourceDataSecret() && resource != null) {
+            // 查 resource_data 表 → dataSecret
+        }
+        // 3. 人员密级（从 emp_data 表查）
+        if (meritdataCloudProperties.isEmpDataSecret()) {
+            String userSecret = sessionUtils.getEmp().getGrade();
+            // 查 emp_data 表 → dataSecret
+        }
+        // 4. 取资源/人员密级的较小值（更安全）
+    }
+
+    // 5. 返回完整 SecretInfoDTO（含 9 字段）
+    return ResultBody.success(secretInfo);
+}
+```
+
+**关键点**：
+- 输入仅 2 个 header（`resourceId` + `resourceSecretCode`）
+- 输出是**完整 SecretInfoDTO**（9 字段全填）
+- 中间逻辑：比较 resourceDataSecret 和 empDataSecret 取较小值
+
+---
+
+## 五、配套表
+
+| 表名 | 用途 | 关键字段 |
+|------|------|---------|
+| `PF_RESOURCE` | 资源表 | `secret_code`（资源密级编码）|
+| `PF_RESOURCE_DATA` | 资源密级配置 | `resource_secret` / `data_secret` |
+| `PF_EMP` | 人员表 | `grade`（人员密级）|
+| `PF_EMP_DATA` | 人员密级配置 | `emp_secret` / `data_secret` |
+| `PF_LOOKUP` | 字典 | `pid` / `code` / `name`（密级字典）|
+
+---
+
+## 六、二开集成示例
+
+### 场景 A：前端 Vue 页面获取当前用户密级
+
+```javascript
+// 方式 1：通过 axios 调用平台接口
+this.$http.default.post('/cloud-system-manage/certificate/get-secret-relation', null, {
+  headers: {
+    resourceId: '...',
+    resourceSecretCode: '...'
+  }
+}).then(res => {
+  const secret = res.data;  // SecretInfoDTO
+  console.log(secret.dataSecretCode);  // 数据密级编码
+  console.log(secret.platformSecret);   // 平台密级
+});
+```
+
+### 场景 B：后端 Java 获取密级并应用行级权限
+
+```java
+@RestController
+@RequestMapping("/api/your-module")
+public class YourController {
+
+    @Autowired
+    private SessionUtils sessionUtils;
+
+    @Autowired
+    private JPAQueryFactory jpaQueryFactory;
+
+    public ResultBody<List<YourEntity>> list() {
+        // 1. 获取当前用户的密级
+        Emp currentEmp = sessionUtils.getEmp();
+        String userSecret = currentEmp.getGrade();
+
+        // 2. 查 QEmpData 获取 data_secret
+        QEmpData empData = QEmpData.empData;
+        Integer dataSecret = jpaQueryFactory.select(empData.dataSecret)
+            .from(empData)
+            .where(empData.empSecret.eq(userSecret))
+            .fetchOne();
+
+        // 3. 用 dataSecret 过滤查询（只查数据密级 ≤ 用户密级 的数据）
+        // 实际场景：用 DataSecretInterceptor + @EnableDataSecretFilter 自动过滤
+        return ResultBody.success(yourEntityRepository.findAll());
+    }
+}
+```
+
+### 场景 C：调用完整 9 字段
+
+```java
+@Autowired
+private CertificateController certificateController;  // 同 JVM 内部调用
+
+@GetMapping("/api/your/current-secret")
+public SecretInfoDTO getCurrentSecret(HttpServletRequest request) {
+    return (SecretInfoDTO) certificateController.getSecretRelation(request).getData();
+}
+```
+
+---
+
+## 七、⚠️ AI 防错警示（不存在的 SessionUtils 方法）
+
+> **2026-09-12 警告**：以下方法名**在 SessionUtils 源码中不存在**——不要调用：
+> - ❌ `sessionUtils.getUserDataSecret()`（**不存在**——这是 LLM 幻觉方法）
+> - ❌ `sessionUtils.getUserSecret()`（**不存在**）
+> - ❌ `sessionUtils.getDataSecret()`（**不存在**）
+> - ❌ `sessionUtils.getCurrentDataSecret()`（**不存在**）
+> - ❌ `sessionUtils.getSecretLevel()`（**不存在**）
+>
+> **正确方式**：调用 `CertificateController.getSecretRelation(request)`，从返回的 `SecretInfoDTO` 获取 9 个字段（包括 `dataSecretCode`）。
+
+---
+
+## 八、相关 skill
+
+| Skill | 用途 |
+|-------|------|
+| `meritdata-platform-data-secret` | 本 skill——密级注解/拦截器/配置 |
+| `meritdata-platform-session` | SessionUtils 完整 28 个方法（不含任何 Secret 方法）|
+| `meritdata-platform-integration` | 跨 JVM Feign 调用 cloud-system-manage 服务 |

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

@@ -0,0 +1,73 @@
+---
+name: meritdata-platform-deploy
+description: MeritData 项目部署（合并 backend-deploy 与 frontend-deploy），用于 Spring Boot 后端打包与部署、Vue 前端构建与发布、Nginx 网关配置、CI/CD 流水线设计。
+metadata:
+  version: "1.0.0"
+  author: 技术平台部门架构组
+  source: company
+  date_added: "2026-09-01"
+  last_updated: "2026-09-01"
+  risk: medium
+  allowed-tools: Read, Grep, Glob, Bash
+---
+
+## ⭐ MUST DO
+
+**部署脚本必须显式支持回滚，配置文件走 Nacos 配置中心而非本地硬编码，Nginx 路径含网关前缀。**
+
+## 触发条件 / 不适用
+
+**适用**：
+- Spring Boot 后端打包（mvn package / docker build）
+- Vue 前端构建（npm run build）
+- Nginx 网关配置
+- CI/CD 流水线设计（Jenkins / GitLab CI）
+
+**不适用**：
+- 开发期本地启动 → `meritdata-platform-cloud-dev`
+- 生产环境运维告警（不属于本 skill）
+
+## 主题路由
+
+| 任务 | 优先读取 |
+| --- | --- |
+
+## 工作方式（Step 1/2/3/4）
+
+### Step 1：环境检查
+
+- 确认目标环境（dev / test / prod）
+- 确认部署方式（物理机 / 容器 / K8s）
+- 确认依赖服务（数据库、Redis、Nacos）
+
+### Step 2：构建产物
+
+- 后端：`mvn clean package -DskipTests`，产出 `target/*.jar`
+- 前端：`npm run build`，产出 `dist/`
+
+### Step 3：配置注入
+
+- 通过环境变量注入数据库密码、Nacos 地址等
+- 通过 Nacos 配置中心加载业务配置
+
+### Step 4：部署 + 回滚
+
+- 蓝绿发布或或
+- 保留上一版本备份，支持快速回滚
+
+## 🚨 常见错误
+
+| 错误 | 后果 | 正确做法 |
+| --- | --- | --- |
+| 配置文件硬编码密码 | 安全风险 | 环境变量注入 |
+| 漏掉回滚脚本 | 故障恢复时间长 | 保留备份版本 |
+| Nginx 路径缺前缀 | 请求 404 | 含 gatewayPrefix |
+| 本地配置覆盖远程 | 配置不一致 | Nacos 中心化 |
+
+## 边界
+
+- **不在本 skill 范围的**：
+  - 应用开发 → `meritdata-platform-cloud-dev`
+  - 后端基础设施 → `meritdata-platform-core`
+  - 数据边界 → `.claude/rules/data-boundary-rules.md`
+- **强制要求**：所有部署脚本必须有回滚方案

package/skills/meritdata-platform-deploy/agents/openai.yaml

@@ -0,0 +1,27 @@
+display_name: "MeritData 部署"
+short_description: "后端打包、前端构建、Nginx 网关、CI/CD 流水线"
+default_prompt: |
+  meritdata-platform-deploy 处理 MeritData 项目部署。
+
+  适用场景：
+  - Spring Boot 后端打包与部署
+  - Vue 前端构建与发布
+  - Nginx 网关代理配置
+  - CI/CD 流水线设计
+
+  使用方式：
+  ```
+  meritdata-platform-deploy <部署需求>
+  ```
+
+  工作方式：
+  1. 确认环境（dev/test/prod）+ 部署方式（物理机/容器/K8s）
+  2. 构建产物：mvn package / npm run build
+  3. 通过环境变量注入敏感配置，Nacos 加载业务配置
+  4. 蓝绿发布或滚动升级
+  5. 保留回滚版本和脚本
+
+  强制约束：
+  - 配置文件走配置中心（Nacos），本地硬编码密码禁止
+  - Nginx 路径必须含 gatewayPrefix
+  - 部署脚本必须有回滚方案

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

@@ -0,0 +1,81 @@
+---
+name: meritdata-platform-entities
+description: 平台内置 JPA 实体与 QueryDSL Q 类索引。提供人员/组织/角色/资源/字典/租户/数据源等历史实体定义；仅在同 JVM 项目使用平台实体时触发，独立业务服务应通过 Feign/API 访问。
+metadata:
+  version: "1.0.0"
+  author: 技术平台部门架构组
+  source: company
+  date_added: "2026-09-01"
+  last_updated: "2026-09-01"
+  risk: medium
+  allowed-tools: Read, Grep, Glob
+---
+
+## ⭐ MUST DO
+
+**独立业务服务禁止直接 import 平台 Entity；必须通过 Feign/API 批量装配（详见 `.claude/rules/data-boundary-rules.md`）。**
+
+## 触发条件 / 不适用
+
+**适用**：
+- 同 JVM 平台模块内查询人员/组织/角色/资源/字典/租户/数据源
+- 关联实体字段核验
+- QueryDSL Q 类索引
+
+**不适用**：
+- 跨 JVM 业务服务的数据访问 → `.claude/rules/data-boundary-rules.md`
+- 平台 Entity 复制到二开库（禁止）
+
+## 主题路由
+
+| 任务 | 优先读取 |
+| --- | --- |
+| 查看实体索引（类名 / 表名 / 父类 / 业务域） | [`references/entity-catalog.md`](references/entity-catalog.md) |
+| 查看具体字段定义（仅供查阅） | `references/.bak-entities/*.java` 备份目录 |
+| 人员/用户（Emp/User/DelEmp/UserPassHistory） | catalog "组织/人员/角色" 章节 |
+| 组织/角色（Organization/OrgUserDept/OrgUserRole/WorkGroup） | catalog 同章节 |
+| 字典（Lookup/Category） | catalog "组织/人员/角色" 章节 |
+| 租户/数据源（Tenancy/DataSourceModel） | catalog "租户/产品/数据源" 章节 |
+| QueryDSL Q 类索引（31 个） | catalog "QueryDSL Q 类" 章节 |
+
+## 工作方式（Step 1/2/3）
+
+### Step 1：判定 JVM 关系
+
+- 调用方与平台模块同 JVM → 允许本地 Bean（直接 `import` 平台实体）
+- 跨 JVM 业务服务 → 必须 Feign/API（**禁止**复制平台实体）
+
+### Step 2：查阅实体
+
+通过 [`references/entity-catalog.md`](references/entity-catalog.md) 查看：
+- 67 个实体类名 + 表名 + 父类 + 业务域分类
+- 31 个 QueryDSL Q 类映射
+- 二开继承 `CloudBaseEntity` 的标准代码模板
+- 4 条数据边界铁律的常见错误对照
+
+⚠️ 历史 .java 源码已迁移至 `references/.bak-entities/` 备份目录（仅供查阅字段细节，**禁止**复制到二开项目）。
+
+### Step 3：构建查询
+
+- 使用 QueryDSL Q 类（`QEmp`、`QUser`、`QOrganization` 等，索引见 catalog）
+- 业务表与平台表禁止 JOIN（参见 data-boundary）
+
+### Step 3：构建查询
+
+- 使用 QueryDSL Q 类（`QEmp`、`QUser`、`QOrganization` 等）
+- 业务表与平台表禁止 JOIN（参见 data-boundary）
+
+## 🚨 常见错误
+
+| 错误 | 后果 | 正确做法 |
+| --- | --- | --- |
+| 跨 JVM 直接 import 平台 Entity | 序列化失败 | 用 DTO + Feign |
+| 复制 Entity 到二开库 | 版本不同步 | 通过 API |
+| 业务表 JOIN 平台表 | 跨库失败 | Feign 批量装配 + 内存 join |
+
+## 边界
+
+- **不在本 skill 范围的**：
+  - 跨 JVM 业务服务 → `.claude/rules/data-boundary-rules.md`
+  - 平台开放接口 → `meritdata-platform-integration`
+- **强制要求**：跨 JVM 服务禁止复制 Entity

package/skills/meritdata-platform-entities/agents/openai.yaml

@@ -0,0 +1,34 @@
+display_name: "MeritData 平台实体"
+short_description: "平台内置 JPA 实体与 QueryDSL Q 类索引（Emp/User/Org/Role 等）"
+default_prompt: |
+  meritdata-platform-entities 处理平台内置 JPA 实体与 Q 类查询。
+
+  适用场景：
+  - 同 JVM 平台模块查人员（Emp/User）
+  - 组织/角色/资源关联查询
+  - 字典/租户/数据源字段核验
+  - QueryDSL Q 类索引
+
+  使用方式：
+  ```
+  meritdata-platform-entities <实体查询需求>
+  ```
+
+  工作方式：
+  1. 判定 JVM 关系（同 JVM 允许，跨 JVM 转 data-boundary）
+  2. 从 references/entity-catalog.md 查找实体索引（类名/表名/父类）
+  3. 如需字段细节查阅 references/.bak-entities/*.java 备份（仅供查阅，不复制）
+  4. 识别字段、关联、审计字段
+  5. 使用 QueryDSL Q 类构建查询
+
+  references/entity-catalog.md 包含 67 个实体 + 31 个 Q 类索引（按业务域分类）：
+  - 组织/人员/角色（Emp / User / Organization / Role / Lookup 等）
+  - 资源/菜单（Resource / ResExternal / Assign）
+  - 租户/产品/数据源（Tenancy / DataSourceModel / CloudProduct）
+  - 工作台/主题/日志（WorkBench / Theme / Log）
+  - QueryDSL Q 类（QEmp / QUser / QOrganization 等 31 个）
+
+  强制约束：
+  - 跨 JVM 业务服务禁止 import 平台 Entity
+  - 业务表与平台表禁止 JOIN
+  - 必须通过 Feign/API 批量装配