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

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 批量装配

package/skills/meritdata-platform-entities/references/entity-catalog.md

@@ -0,0 +1,194 @@
+# 平台实体索引（Entity Catalog）
+
+> ⚠️ **重要提示**：本目录**不**包含平台实体 Java 源码（已迁移至 `.bak-entities/` 备份目录，仅供查阅）。
+>
+> **正确使用方式**：
+> 1. 通过 Maven 依赖 `cloud-module-base` 引入实体（`com.meritdata.cloud.base.entity.*`）
+> 2. 在二开代码中 `import com.meritdata.cloud.base.entity.XxxEntity;` 直接使用
+> 3. **禁止**复制本目录的历史 .java 源码到二开项目（违反 `.claude/rules/data-boundary-rules.md`）
+
+---
+
+## 一、基类（3 个）
+
+| 类名 | 父类 | 表 | 包路径 | 说明 |
+|------|------|------|--------|------|
+| `BaseEntity` | — | （基类，无表） | `com.meritdata.cloud.base.entity` | 平台实体根类 |
+| `CloudBaseEntity` | `BaseEntity` | （基类，无表） | `com.meritdata.cloud.base.entity` | **二开继承的实体基类**（自带 createTime/updateTime/creatorId/reviserId）|
+| `CloudEntity` | — | （基类，无表） | `com.meritdata.cloud.base.entity` | 另一基类（具体差异按需查源码）|
+
+## 二、核心实体（按业务域）
+
+### 2.1 组织/人员/角色
+
+| 类名 | 表 | 父类 | 业务域 | 关键说明 |
+|------|------|------|------|------|
+| `Organization` | `PF_ORG_DEPARTMENT` | `CloudBaseEntity` | 组织/部门 | 部门树 |
+| `Emp` | `PF_ORG_USER` | `CloudBaseEntity` | 人员 | 主人员表（含 A-Z 自定义字段）|
+| `DelEmp` | `PF_DEL_USER_INFO` | `CloudBaseEntity` | 已删人员 | 软删人员归档 |
+| `User` | `PF_USER_INFO` | `CloudBaseEntity` | 用户 | 系统登录账号 |
+| `UserPassHistory` | `PF_USER_PASS_HISTORY` | `CloudBaseEntity` | 用户密码历史 | 密码变更记录 |
+| `UserWorkGroup` | `PF_ORG_USER_WORKGROUP` | `BaseEntity` | 用户-工作组关联 | |
+| `Role` | `PF_ORG_ROLE` | `CloudBaseEntity` | 角色 | 系统角色定义 |
+| `OrgUserDept` | `PF_ORG_USER_DEPARTMENT` | — | 人员-部门关联 | |
+| `OrgUserRole` | `PF_ORG_USER_ROLE` | `BaseEntity` | 人员-角色关联 | |
+| `WorkGroup` | `PF_ORG_WORKGROUP` | `BaseEntity` | 工作组 | |
+| `Category` | `PF_ORG_CATEGORY` | `BaseEntity` | 人员分类 | |
+| `Lookup` | `PF_LOOKUP` | — | 数据字典 | 字典项（含 lookupType）|
+| `EmpData` | `PF_EMP_DATA` | — | 人员扩展数据 | |
+| `EmpResource` | `PF_EMP_RESOURCE` | — | 人员资源关联 | |
+
+### 2.2 资源/菜单
+
+| 类名 | 表 | 父类 | 业务域 | 关键说明 |
+|------|------|------|------|------|
+| `Resource` | `PF_RESOURCE` | — | 资源/菜单 | 菜单树 |
+| `ResExternal` | `PF_RESOURCE_EXTERNAL` | `CloudBaseEntity` | 外部资源 | 第三方应用资源 |
+| `ResExternalInfo` | — | — | 外部资源信息 | 非实体 |
+| `ResourceData` | `PF_RESOURCE_DATA` | — | 资源数据 | |
+| `Assign` | `PF_RESOURCE_ASSIGN` | — | 资源授权 | 角色-资源/用户-资源绑定 |
+| `SubResourceAssign` | `PF_RESOURCE_SUB_MANAGE` | — | 子资源授权 | |
+
+### 2.3 租户/产品/数据源
+
+| 类名 | 表 | 父类 | 业务域 | 关键说明 |
+|------|------|------|------|------|
+| `Tenancy` | `PF_TENANCY` | — | 租户 | 平台多租户 |
+| `CloudProduct` | — | — | 产品 | 产品授权（无表注解）|
+| `CloudProductModule` | — | — | 产品模块 | 产品-模块映射（无表注解）|
+| `DataSourceModel` | `PF_TEMPO_DATASOURCE` | — | 数据源 | Tempo 动态数据源 |
+| `SubData` | `PF_TEMPO_SUBDATA_ROLE` | `CloudBaseEntity` | 子数据源 | Tempo 子数据 |
+| `SubDataSourcePrivilege` | `PF_TEMPO_SUBSOURCE_PRIVILEGE` | — | 子数据源权限 | |
+
+### 2.4 工作台/主题/日志
+
+| 类名 | 表 | 父类 | 业务域 | 关键说明 |
+|------|------|------|------|------|
+| `WorkBench` | `PF_US_WORKBENCH` | `CloudBaseEntity` | 工作台 | 用户工作台 |
+| `WorkBenchAuth` | `PF_US_WORKBENCH_AUTH` | `CloudBaseEntity` | 工作台授权 | |
+| `WorkBenchMenu` | `PF_US_WORKBENCH_MENU` | `CloudBaseEntity` | 工作台菜单 | |
+| `Theme` | `PF_THEME` | `CloudBaseEntity` | 主题 | 平台主题 |
+| `Log` | `PF_LOG` | `CloudBaseEntity` | 日志 | 操作日志 |
+| `CloudSchemaHistory` | `PF_SCHEMA_HISTORY` | — | 模式变更历史 | |
+
+### 2.5 任务（辅助 DTO，非表实体）
+
+| 类名 | 表 | 父类 | 业务域 | 关键说明 |
+|------|------|------|------|------|
+| `TaskResult` | — | — | 异步任务结果 | |
+| `TaskVO` | — | — | 任务视图对象 | |
+
+---
+
+## 三、QueryDSL Q 类（31 个，全部继承 `EntityPathBase`）
+
+| Q 类 | 对应实体 | 触发场景 |
+|------|---------|---------|
+| `QAssign` | `Assign` | QueryDSL 资源授权查询 |
+| `QBaseEntity` | `BaseEntity` | 基类 Q |
+| `QCategory` | `Category` | QueryDSL 人员分类查询 |
+| `QCloudBaseEntity` | `CloudBaseEntity` | **二开继承的基类 Q** |
+| `QCloudEntity` | `CloudEntity` | 基类 Q |
+| `QCloudSchemaHistory` | `CloudSchemaHistory` | QueryDSL 模式历史 |
+| `QDataSourceModel` | `DataSourceModel` | QueryDSL 数据源查询 |
+| `QDelEmp` | `DelEmp` | QueryDSL 已删人员查询 |
+| `QEmp` | `Emp` | **QueryDSL 人员查询（高频）** |
+| `QEmpData` | `EmpData` | QueryDSL 人员扩展数据 |
+| `QEmpResource` | `EmpResource` | QueryDSL 人员资源 |
+| `QLog` | `Log` | QueryDSL 日志查询 |
+| `QLookup` | `Lookup` | QueryDSL 字典查询 |
+| `QOrgUserDept` | `OrgUserDept` | QueryDSL 人员部门 |
+| `QOrgUserRole` | `OrgUserRole` | QueryDSL 人员角色 |
+| `QOrganization` | `Organization` | **QueryDSL 组织查询（高频）** |
+| `QResExternal` | `ResExternal` | QueryDSL 外部资源 |
+| `QResource` | `Resource` | **QueryDSL 资源/菜单查询（高频）** |
+| `QResourceData` | `ResourceData` | QueryDSL 资源数据 |
+| `QRole` | `Role` | **QueryDSL 角色查询（高频）** |
+| `QSubData` | `SubData` | QueryDSL 子数据源 |
+| `QSubDataSourcePrivilege` | `SubDataSourcePrivilege` | QueryDSL 子数据源权限 |
+| `QSubResourceAssign` | `SubResourceAssign` | QueryDSL 子资源授权 |
+| `QTenancy` | `Tenancy` | QueryDSL 租户 |
+| `QTheme` | `Theme` | QueryDSL 主题 |
+| `QUser` | `User` | **QueryDSL 用户查询（高频）** |
+| `QUserPassHistory` | `UserPassHistory` | QueryDSL 密码历史 |
+| `QUserWorkGroup` | `UserWorkGroup` | QueryDSL 用户工作组 |
+| `QWorkBench` | `WorkBench` | QueryDSL 工作台 |
+| `QWorkBenchAuth` | `WorkBenchAuth` | QueryDSL 工作台授权 |
+| `QWorkBenchMenu` | `WorkBenchMenu` | QueryDSL 工作台菜单 |
+| `QWorkGroup` | `WorkGroup` | QueryDSL 工作组 |
+
+---
+
+## 四、二开继承基类的标准做法
+
+```java
+package com.meritdata.cloud.contract.entity;
+
+import com.meritdata.cloud.base.entity.CloudBaseEntity;
+import lombok.Data;
+import org.hibernate.annotations.GenericGenerator;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.GeneratedValue;
+import jakarta.persistence.Id;
+import jakarta.persistence.Table;
+
+/**
+ * 样例：二开业务实体继承 CloudBaseEntity
+ * 继承后自动获得：createTime/updateTime/creatorId/reviserId
+ */
+@Entity
+@Table(name = "T_CONTRACT")  // ⚠️ 注意大写（sql-naming 规范）
+@GenericGenerator(name = "jpa-uuid", strategy = "uuid")
+@Data
+public class Contract extends CloudBaseEntity {
+    @Id
+    @GeneratedValue(generator = "jpa-uuid")
+    @Column(name = "ID", length = 32)
+    private String id;
+
+    @Column(name = "NAME", length = 100)
+    private String name;
+    // ... 其他业务字段
+}
+```
+
+---
+
+## 五、二开常见错误（对照 data-boundary 铁律）
+
+| 错误做法 | 后果 | 正确做法 |
+|---------|------|---------|
+| ❌ 复制本目录 .java 到二开项目源码 | 平台升级时全部 break，违反数据边界铁律 | ✅ 通过 Maven 依赖引入 `cloud-module-base` |
+| ❌ 二开项目直连平台表（`PF_*`）| 数据库权限/事务边界混乱 | ✅ 二开业务表与平台表分离 |
+| ❌ 业务表与平台表跨库 JOIN | 跨库失败 | ✅ 应用层内存 join |
+| ❌ 在事务中调用 Feign 装配平台数据 | 锁等待 + 性能问题 | ✅ 批量装配 + 应用层 join |
+
+---
+
+## 六、文件清单（备份位置）
+
+完整 Java 源码备份在同目录 `.bak-entities/` 子目录（69 文件），仅供查阅字段细节。
+
+**结构**：
+```
+references/
+├── entity-catalog.md      ← 本文件（索引）
+└── .bak-entities/         ← 备份（仅供查阅，不作为开发引用）
+    ├── CloudBaseEntity.java
+    ├── BaseEntity.java
+    ├── Emp.java
+    ├── ...
+    └── Q*系列（31 个 QueryDSL Q 类）.java
+```
+
+---
+
+## 七、相关 Skill
+
+| Skill | 用途 |
+|-------|------|
+| `meritdata-platform-cloud-dev` | 加新模块 / 生成业务代码 |
+| `meritdata-platform-integration` | 跨 JVM Feign 装配（外部接口）|
+| `.claude/rules/data-boundary-rules.md` | 数据边界铁律 |