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

package/skills/meritdata-platform-logging/references/logging.md

@@ -0,0 +1,256 @@
+## 前置条件
+
+Maven 依赖已包含在 `cloud-starter-core` 基础包中，二开项目继承平台脚手架后自动引入。
+
+**服务调用方式**: Feign 远程调用，服务名 `cloud-system-manage`，基础路径 `/api/basic/log`。
+
+引入 Feign 依赖后注入使用：
+
+```java
+@Autowired
+private ILogPostService logPostService;
+```
+
+**完整包路径**: `com.meritdata.cloud.log.service.ILogPostService`
+
+---
+
+## 快速开始：新增日志
+
+```java
+Message msg = new Message(
+    Message.TYPE_OPT,          // 日志类型：0-操作日志
+    "组织机构",                  // 业务模块
+    "人员维护",                  // 功能模块
+    "新增人员",                  // 操作描述
+    "新增人员[张三]",            // 日志内容
+    Message.STATUS_SUCESS       // 状态：1-成功
+);
+logPostService.postLog(msg);
+```
+
+输出日志：`[用户1:user1] 新增人员[张三]`
+
+---
+
+## 日志类型
+
+| 常量 | 值 | 说明 |
+|------|-----|------|
+| `Message.TYPE_OPT` | 0 | 操作日志 |
+| `Message.TYPE_VISIT` | 1 | 访问日志 |
+| `Message.TYPE_LOGIN` | 2 | 登录日志 |
+| `Message.TYPE_ERROR` | 3 | 错误日志 |
+| `Message.TYPE_SAFE` | 5 | 安全日志 |
+| `Message.TYPE_SERVER` | 6 | 服务日志 |
+| `Message.TYPE_LOGOUT` | 7 | 登出日志 |
+
+---
+
+## Message 对象
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| type | String | 是 | 日志类型 |
+| bmodule | String | 是 | 业务模块 |
+| fmodule | String | 是 | 功能模块 |
+| operation | String | 是 | 操作描述 |
+| message | String | 否 | 日志内容/变更详情 |
+| status | String | 是 | 操作状态：1-成功 |
+
+可选字段：`ip`, `fullname`, `userid`, `tenantId`, `grade`, `code`, `operationType`, `startTime`, `endTime`, `executeTime`
+
+---
+
+## 日志模板配置
+
+在 `src/main/resources/logs/{module}.logs.properties` 中配置：
+
+```properties
+# 业务模块
+ou.org.bmodule=组织机构
+# 功能模块
+ou.emp.fmodule=人员维护
+# 操作描述
+ou.emp.create=新增人员
+# 操作信息模板（{}为占位符）
+ou.emp.create.message=新增人员[{}]
+ou.emp.update=编辑人员
+ou.emp.delete=删除人员
+ou.emp.delete.message=删除人员{}
+```
+
+读取配置：
+
+```java
+LogPattenUtils.getProperty("ou.org.bmodule")
+```
+
+---
+
+## @LogDesc — 实体字段注解
+
+**完整包路径**: `com.meritdata.cloud.base.LogDesc`
+
+注解在实体类上，配合 `CompareUtils` 自动生成变更日志。
+
+```java
+@LogDesc(value = "人员", keyField = "name")  // 类注解：实体描述 + 日志主键字段
+@Entity
+public class Emp extends CloudBaseEntity {
+
+    @LogDesc("姓名")        // 普通字段：变更显示"姓名"由[旧值]变更为[新值]
+    @DelDesc               // 删除时记录此字段
+    @AddDesc               // 新增时记录此字段
+    private String name;
+
+    @LogDesc(value = "性别", lookupType = "sex")  // lookupType 自动转换数据字典
+    private Integer sex;
+
+    @LogDesc(value = "手机号", changeFlag = true)  // changeFlag=true 显示"手机号变更"
+    private String handset;
+}
+```
+
+| 属性 | 说明 |
+|------|------|
+| `value` | 字段中文描述 |
+| `keyField` | 日志前缀字段名（类上使用） |
+| `lookupType` | 数据字典类型，自动转换编码为中文 |
+| `changeFlag` | true → 打印"XX变更"，不显示具体值（敏感信息） |
+| `booleanFlag` | 布尔类型转换 |
+
+**配套注解**：
+- `@AddDesc` — 标记新增时记录此字段
+- `@DelDesc` — 标记删除时记录此字段
+
+---
+
+## CompareUtils — 自动变更日志
+
+**完整包路径**: `com.meritdata.cloud.log.compare.CompareUtils`
+
+```java
+Emp empDb = service.getEmpById(emp.getId());
+// 自动生成："姓名"由[张三]变更为[李四], "性别"由[男]变更为[女], "手机号"变更
+String compareLog = CompareUtils.getCompareLog(empDb, emp);
+```
+
+---
+
+## 完整 CRUD 日志示例
+
+### 新增
+
+```java
+@LogOperation(type = "add")
+public boolean create(Emp emp) {
+    boolean flag = service.insertEmp(emp);
+    if (flag) {
+        Message msg = new Message(Message.TYPE_OPT,
+            LogPattenUtils.getProperty("ou.org.bmodule"),
+            LogPattenUtils.getProperty("ou.emp.fmodule"),
+            LogPattenUtils.getProperty("ou.emp.create"),
+            StrUtil.format(LogPattenUtils.getProperty("ou.emp.create.message"), emp.getName()),
+            Message.STATUS_SUCESS);
+        logPostService.postLog(msg);
+    }
+    return flag;
+}
+```
+
+### 编辑
+
+```java
+@LogOperation(type = "edit")
+public boolean update(Emp emp) {
+    Emp empDb = service.getEmpById(emp.getId());
+    String compareLog = CompareUtils.getCompareLog(empDb, emp);
+    boolean flag = service.updateEmp(emp);
+    if (flag && StrUtil.isNotBlank(compareLog)) {
+        Message msg = new Message(Message.TYPE_OPT,
+            LogPattenUtils.getProperty("ou.org.bmodule"),
+            LogPattenUtils.getProperty("ou.emp.fmodule"),
+            LogPattenUtils.getProperty("ou.emp.update"),
+            compareLog,
+            Message.STATUS_SUCESS);
+        logPostService.postLog(msg);
+    }
+    return flag;
+}
+```
+
+### 删除
+
+删除日志必须在删除前或删除结果中取得已删除对象的可审计摘要。不要复制使用未定义变量的“完整示例”；沿用目标项目已存在的删除日志实现，并避免记录密码、令牌或完整敏感字段。
+
+---
+
+## @LogOperation — 方法注解
+
+**完整包路径**: `com.meritdata.cloud.log.aspect.LogOperation`
+
+标记方法操作类型，框架自动记录操作时间。
+
+| type 值 | 说明 |
+|---------|------|
+| `add` | 新增 |
+| `edit` | 修改 |
+| `delete` | 删除 |
+| `select` | 查询 |
+| `visit` | 访问 |
+| `loginIn` | 登录 |
+| `loginOut` | 登出 |
+| `import` | 导入 |
+| `export` | 导出 |
+| `download` | 下载 |
+| `upload` | 上传 |
+| `assign` | 分配/变更 |
+
+```java
+@LogOperation(type = "add")
+public ReturnT<String> add(@Valid CloudJobInfo jobInfo) {
+    Message msg = new Message(...);
+    msg.setStartTime(System.currentTimeMillis());
+    msg.setEndTime(System.currentTimeMillis());
+    logPostService.postLog(msg);
+    return CloudJobService.add(jobInfo);
+}
+```
+
+---
+
+## 自定义日志 (postDiyLog)
+
+**接口**: `POST /post-diy`
+
+```java
+private void postLoginLog(User user, Long startTime) {
+    Long executeTime = System.currentTimeMillis() - startTime;
+    Message msg = new Message(Message.TYPE_LOGOUT,
+        LogPattenUtils.getProperty("common.basic.bmodule"),
+        LogPattenUtils.getProperty("common.logout.fmodule"),
+        LogPattenUtils.getProperty("common.logout.fmodule"),
+        StrUtil.format(LogPattenUtils.getProperty("common.loginout.user")),
+        Message.STATUS_SUCESS);
+    msg.setIp(user.getLoginIp());
+    msg.setFullname(user.getUsername());
+    msg.setUserid(user.getUserId());
+    msg.setTenantId(user.getTenantId());
+    msg.setCode(user.getCode());
+    msg.setOperationType("loginOut");
+    msg.setExecuteTime(executeTime);
+    logPostService.postDiyLog(msg);
+}
+```
+
+---
+
+## 日志注意事项
+
+1. 日志服务是 Feign 远程调用，需要确保 `cloud-system-manage` 服务可用
+2. 日志模板文件必须放在 `src/main/resources/logs/` 目录
+3. `@LogDesc` 的 `changeFlag=true` 用于敏感字段，不暴露具体值
+4. `@LogOperation` 不自动记录日志内容，只辅助记录时间和类型
+
+---

package/skills/meritdata-platform-menu-config/SKILL.md

@@ -1,42 +1,221 @@
 ---
 name: meritdata-platform-menu-config
-description: |
-  菜单配置。菜单树 / 角色菜单 / 用户菜单 / 菜单权限 / 菜单国际化。
-  触发场景：前端动态菜单 / 角色授权菜单 / 按用户查菜单 / 菜单新增修改 / 菜单排序隐藏。
-  何时不用：按钮级别权限 → 用 meritdata-platform-permission；API 资源权限 → 用 meritdata-platform-menu-resource。
+description: 美林数据「微服务应用开发平台 6.x 二开工程的菜单/资源配置 —— 在 cloud 库 pf_resource + pf_resource_assign 两张表插 SQL。通用 skill，适用任何二开项目（合同/HR/项目/订单等），不仅限于合同系统。Use when configuring menus via SQL on MeritData platform 6.x（v3 实测）, troubleshooting "menu not showing" or "click jumps to /noaccess" (5 known pitfalls include SHOW_MENU semantics inverted, URI field is vue path not full URL, AUTHORITIES_ID supports both user ID and role ID, PARENT_ID='-1' not 'ROOT_MENU', and URI leading/trailing whitespace breaks the route).
 metadata:
-  version: "1.0.0"
-  author: petroleum+rd
-  source: petroleum+rd
-  date_added: "2026-09-07"
-  last_modified: "2026-09-07"
-  risk: medium
-  layer: L3
-  sub-layer: L3-C
-  stack: java
-allowed-tools: Read, Grep, Glob, Bash
----
-
-# 菜单配置（menu-config）
-
-## 触发
-- 前端根据用户权限动态生成菜单
-- 角色授权菜单（管理员给某个角色分配可见菜单）
-- 菜单 CRUD（新增/修改/隐藏/排序）
-- 菜单国际化（多语言菜单名）
-
-## 不触发
-- 按钮权限（页面内 button 显隐）→ 用 `meritdata-platform-permission`
-- API 资源权限（后端接口权限）→ 用 `meritdata-platform-menu-resource`
-- 数据权限（行级/列级）→ 用 `meritdata-platform-data-classification`
-
-## 前置约束
-- 菜单是平台统一管理资源，二开不重写菜单管理
-- 菜单数据走缓存（变更广播清缓存）
-- 二开新增菜单**必须**通过平台后台添加（不在代码里硬编码菜单）
-
-## 路由
-- 菜单查询 + 用户菜单 → [references/guide.md](references/guide.md)
-- 角色授权 + 菜单树构建 → [references/role-and-tree.md](references/role-and-tree.md)
-- 国际化 + 缓存 → [references/i18n-and-cache.md](references/i18n-and-cache.md)
-- [SKILL.md](../SKILL.md)
+  type: reference
+---
+
+# 美林平台 6.x 菜单配置（pf_resource + pf_resource_assign）
+
+> **关键陷阱**：`pf_resource_assign.AUTHORITIES_ID` 必须**有效存在**于 `pf_org_role.ID` **或** `pf_user_info.ID`（6.x 平台两者都支持），否则菜单即使 `SHOW_MENU='1'` 也不显示。
+
+---
+
+## 适用本 skill
+
+**适用场景**：
+- 在美林平台 6.x 上为二开项目配置菜单
+- 批量初始菜单数据
+- 排查菜单"看不见"或"点了跳 /noaccess"
+
+**占位符**（本 skill 通用）：
+- `${APP_NAME}` = 你二开项目的应用名（对应 `spring.application.name` = pom `artifactId`）
+- `${MENU_ROOT_NAME}` = 顶级菜单显示名（如 `<项目名>管理` / `HR管理` / `订单中心`，根据你的项目命名）
+- `${USER_ID}` = 当前登录用户的 ID（从 `pf_user_info` 查）
+- `${ROLE_CODE}` = 角色编码（XTGLY=系统管理员 / AQGLY=安全管理员 / XTPTRY=普通用户）
+
+---
+
+## 背景
+
+6.x 平台菜单 = 2 张表（`cloud` 库）：
+
+| 表 | 作用 | 关键字段 |
+|---|---|---|
+| `pf_resource` | 资源定义（菜单/按钮/API）| `ID`, `NAME`, `URI`, `EMBED_URL`, `TYPE`, `PARENT_ID`, `SHOW_MENU`, `SHOW_TYPE`, `SORT`, `ISENTRANCE`, `SYS_RESOURCE`, `APPLICATION_NAME` |
+| `pf_resource_assign` | 资源 → 用户/角色 分配 | `ID`, `AUTHORITIES_ID`, `PRIV_ID`, `TYPE` (=`6` 菜单分配) |
+
+**注意**：`pf_resource` 表 80+ 列，**全 `varchar/int` 可空**，除 `ID` 外**无强制字段**——意味着 UI 配菜单时**只填你懂的字段，其他让系统默认值即可**。
+
+---
+
+## 6.x 平台菜单**5 大坑**（不踩 100% 跳 /noaccess）
+
+| # | 坑 | 错 | 对 |
+|---|----|----|----|
+| 1 | **`SHOW_MENU` 语义反** | `'1'`（**隐藏**）| **`'0'`**（显示） |
+| 2 | **`URI` 字段** | 完整 URL `http://...` | **vue 路径** `/<short-app>/list`（**不带** `http://`，**不带** `.html`）|
+| 3 | **`EMBED_URL` 字段** | vue 路径 | **完整 nginx 资源路径** `/<app>/list/index.html` |
+| 4 | **`PARENT_ID` 字面字符串** | `'ROOT_MENU'` | **`'-1'`**（顶级）/ 写真实父菜单 id（子菜单）|
+| 5 | **URI 前后空格** | `' /<app>/list'`（前 1 空格 → 主 SPA vue 路由匹配失败 → 跳 /noaccess）| **`'/<app>/list'`**（trim 关键） |
+
+---
+
+## 步骤 1：先 SELECT 看平台真实结构
+
+**永远先看真实数据**（6.x 平台 `pf_resource` 表 80+ 列有默认值，UI 配的字段你可能漏看）：
+
+```sql
+-- 1. 找 1 个已 work 的应用（bpm 流程管理、schedule 调度编排等平台自带子系统）作参考
+SELECT ID, NAME, TYPE, PARENT_ID, SHOW_MENU, SHOW_TYPE, SORT,
+       IFNULL(URI,'') URI, IFNULL(EMBED_URL,'') EMBED_URL,
+       IFNULL(ISENTRANCE,'') ISE, IFNULL(SYS_RESOURCE,'') SYS,
+       IFNULL(APPLICATION_NAME,'') APP, IFNULL(PRODUCT_NAME,'') PROD
+FROM pf_resource
+WHERE APPLICATION_NAME IN ('cloud-system-bpm','cloud-system-schedule')
+ORDER BY TYPE, SORT LIMIT 5;
+
+-- 2. 找有效角色
+SELECT ID, NAME FROM pf_org_role;
+-- 常见：XTGLY=系统管理员, XTPTRY=普通用户, AQGLY=安全管理员
+
+-- 3. 找当前登录账号 + 角色（看用户 id 是什么）
+SELECT ID, NAME FROM pf_user_info WHERE LOGIN_NAME = 'admin' LIMIT 1\G
+SELECT * FROM pf_org_user_role WHERE USER_ID = '<用户 id>';
+```
+
+**关键发现**：
+
+- `AUTHORITIES_ID` 字段名是 `AUTHORITIES_ID`（误导），**实际可以是用户 ID 也可是角色 ID**（（6.x 兼容）
+- `APPLICATION_NAME` 字段可空（你 UI 配的空也能 work）
+- `PRODUCT_NAME` / `GROUP_ID` 字段可空
+
+---
+
+## 步骤 2：插资源（用通用 SQL 模板）
+
+参考 `references/insert-menu-template.sql` 完整模板。**关键字段**：
+
+```sql
+-- 顶级模块
+INSERT INTO pf_resource (ID, NAME, TYPE, PARENT_ID, SHOW_MENU, SHOW_TYPE, SORT, URI, EMBED_URL, ISENTRANCE, SYS_RESOURCE) VALUES
+('${APP_NAME}-root', '${MENU_ROOT_NAME}', '0', '-1', '0', 'select', 100, '0', '', '1', '1');
+
+-- 子菜单（注意 URI 和 EMBED_URL 字段不要混，URI 是 vue 路径）
+INSERT INTO pf_resource (ID, NAME, TYPE, PARENT_ID, SHOW_MENU, SHOW_TYPE, SORT, URI, EMBED_URL, ISENTRANCE, SYS_RESOURCE) VALUES
+('${APP_NAME}-list1', '子菜单1', '1', '${APP_NAME}-root', '0', 'select', 10,
+  '/${APP_NAME}/list1', '/${APP_NAME}/list1/index.html', '1', '1');
+```
+
+---
+
+## 步骤 3：插资源分配（6.x 支持用户 ID 也支持角色 ID）
+
+```sql
+-- 选项 A：绑到具体用户（6.x 平台最常见，UI 默认行为）
+INSERT INTO pf_resource_assign (ID, AUTHORITIES_ID, PRIV_ID, TYPE) VALUES
+    (REPLACE(UUID(),'-',''), '${USER_ID}', '${APP_NAME}-root', '6'),
+    (REPLACE(UUID(),'-',''), '${USER_ID}', '${APP_NAME}-list1', '6');
+
+-- 选项 B：绑到角色（XTGLY = 系统管理员）
+INSERT INTO pf_resource_assign (ID, AUTHORITIES_ID, PRIV_ID, TYPE) VALUES
+    (REPLACE(UUID(),'-',''), 'XTGLY', '${APP_NAME}-root', '6'),
+    (REPLACE(UUID(),'-',''), 'XTGLY', '${APP_NAME}-list1', '6');
+
+-- TYPE = '6' 必填（菜单分配）
+```
+
+---
+
+## 步骤 4：验证（4 个必查）
+
+```sql
+-- 1. URI 无空格（关键！空格导致 /noaccess）
+SELECT ID, URI, LENGTH(URI) AS len, IF(URI = TRIM(URI),'OK','HAS_SPACE') AS space_check
+FROM pf_resource WHERE ID IN ('${APP_NAME}-root','${APP_NAME}-list1');
+
+-- 2. SHOW_MENU=0 显示（不是 1）
+SELECT ID, NAME, SHOW_MENU, TYPE FROM pf_resource
+WHERE ID IN ('${APP_NAME}-root','${APP_NAME}-list1');
+
+-- 3. AUTHORITIES_ID 有效（6.x 兼容用户 ID 和角色 ID）
+SELECT pra.AUTHORITIES_ID, pra.PRIV_ID, pra.TYPE, r.NAME AS ROLE_NAME
+FROM pf_resource_assign pra
+LEFT JOIN pf_org_role r ON pra.AUTHORITIES_ID = r.ID
+WHERE pra.PRIV_ID IN ('${APP_NAME}-root','${APP_NAME}-list1');
+-- ROLE_NAME 为 NULL 但 AUTHORITIES_ID 是用户 ID 也 OK（（6.x 兼容）
+
+-- 4. PARENT_ID 写真实父（不能写 'ROOT_MENU'）
+SELECT ID, PARENT_ID, NAME FROM pf_resource WHERE TYPE='1' AND APPLICATION_NAME='${APP_NAME}';
+```
+
+---
+
+## 步骤 5：浏览器验证（端到端）
+
+```
+1. 登录平台（admin / BigData.2018v6）
+2. 看左侧菜单 → 应看到「${MENU_ROOT_NAME}」
+3. 点子菜单 → 应直接打开（不跳 /noaccess）
+4. 如果跳 /noaccess → 回去查 § "5 大坑" 表
+```
+
+**关键**：用 `TRIM(URI)` 跑一次保险，**空格是最隐蔽的坑**。
+
+---
+
+## 排错流程
+
+| 症状 | 第一检查 | 第二检查 | 第三检查 |
+|------|----------|---------|---------|
+| 菜单完全不显示 | `AUTHORITIES_ID` 有效（6.x 兼容用户/角色）| `SHOW_MENU='0'` | `PARENT_ID` 不为空 |
+| 点菜单跳 `/noaccess` | `URI` 字段**无空格**（`TRIM(URI)`）| `URI` 是 vue 路径（**不带** `http://`）| `URI` 写真实父 |
+| 点菜单跳新窗口 | `URI` 含 `http://` 触发 window.open | — | — |
+| 点菜单 404 | nginx 没配 `location /<app>/` 块 | `index` 路径（用 `'index.html'` 不要 `'index <sub>/index.html'`）| 详见 `meritdata-platform-deploy` skill |
+| 菜单显示但页面空白 | nginx alias 路径错 | `apps/<app>/` 实际有 build 产物 | — |
+
+---
+
+## 通用 SQL 一键诊断（替换 `${APP_NAME}`）
+
+```sql
+-- 1. 看 4 资源完整字段
+SELECT ID, NAME, TYPE, PARENT_ID, SHOW_MENU, IFNULL(URI,'') URI,
+       IFNULL(EMBED_URL,'') EMBED_URL, ISENTRANCE, SYS_RESOURCE
+FROM pf_resource
+WHERE ID LIKE '${APP_NAME}-%' OR APPLICATION_NAME = '${APP_NAME}'
+ORDER BY TYPE, SORT;
+
+-- 2. 看 4 资源分配
+SELECT pra.AUTHORITIES_ID, pra.PRIV_ID, pra.TYPE, r.NAME AS ROLE_NAME
+FROM pf_resource_assign pra
+LEFT JOIN pf_resource r ON pra.PRIV_ID = r.ID
+WHERE r.ID LIKE '${APP_NAME}-%' OR r.APPLICATION_NAME = '${APP_NAME}';
+
+-- 3. 一键检查空格
+SELECT ID, URI, IF(URI = TRIM(URI),'OK','HAS_SPACE') AS space_check
+FROM pf_resource WHERE ID LIKE '${APP_NAME}-%';
+```
+
+---
+
+## 常见坑
+
+| 问题 | 原因 | 解决 |
+|------|------|------|
+| 菜单完全不显示 | `AUTHORITIES_ID` 无效 | 查 `pf_org_role` / `pf_user_info` 找有效 id |
+| 菜单完全不显示 | `SHOW_MENU='1'` 隐藏 | 改 `'0'` |
+| 菜单显示但点击 404 | nginx 没配 location 块 | 配 nginx 静态资源 |
+| 菜单点进去空白 | nginx alias 路径错 | 检查 alias 是否指向实际 build 产物 |
+| 菜单点跳 /noaccess | 6.x 平台 vue 路由匹配不到 | 见 § 5 大坑 |
+
+---
+
+## 关联（本 skill 自包含）
+
+- `references/insert-menu-template.sql` — **通用** SQL 模板（替换 `${APP_NAME}` 直接复用）
+- `references/environment.md` — MySQL 连接变量
+- `references/field-mapping.md` — 6.x 平台 UI 字段 ↔ DB 字段映射（`URI`/`EMBED_URL` 对应关系颠倒）
+- `references/troubleshooting.md` — 5 大坑详解 + 排错流程
+
+> **设计原则**：本 skill **自包含**（所有路径/DB 变量在 `references/environment.md`），**不依赖** `meritdata-platform-deploy` 等其他 skill。独立安装即可使用。
+
+## 🔗 相关 skill
+
+| 何时用 | skill |
+|------|------|
+| 创建新二开项目 | `meritdata-platform-bootstrap-2nd-dev` |
+| 导入 Nacos 配置 | `meritdata-platform-nacos-importer` |
+| 部署前端（含 nginx 配置）| `meritdata-platform-deploy` |
+| 资源码 + URL 按钮权限 | `meritdata-platform-resource-auth` |
+| 数据密级 / 行级权限 | `meritdata-platform-data-secret` |

package/skills/meritdata-platform-menu-config/agents/openai.yaml

@@ -0,0 +1,22 @@
+display_name: "菜单 SQL 配置"
+short_description: "6.x 平台 pf_resource + pf_resource_assign 菜单配置（5 大坑详解）"
+default_prompt: |
+  meritdata-platform-menu-config 处理美林平台 6.x 菜单/资源配置。
+
+  适用场景：
+  - 新增业务模块后挂菜单
+  - 批量初始菜单数据
+  - 排查菜单不显示或跳 /noaccess
+
+  使用方式：
+  ```
+  $meritdata-platform-menu-config <项目名>
+  ```
+
+  工作方式：
+  1. 先 SELECT 看平台真实结构（pf_resource / pf_org_role）
+  2. 插资源（pf_resource）+ 资源分配（pf_resource_assign）
+
+  强制约束：
+  - SHOW_MENU=0 表示显示（不是 1）
+  - AUTHORITIES_ID 必须是用户 ID 或角色 ID 有效值

package/skills/meritdata-platform-menu-config/references/README.md

@@ -0,0 +1,10 @@
+# meritdata-platform-menu-config References
+
+暂无独立参考文档。详细使用方式见 [SKILL.md](../SKILL.md)。
+
+## 关联资源
+
+- `references/insert-menu-template.sql` — 通用 SQL 模板（待补）
+- `references/environment.md` — MySQL 连接变量（待补）
+- `references/field-mapping.md` — UI ↔ DB 字段映射（待补）
+- `references/troubleshooting.md` — 5 大坑详解（待补）

package/skills/meritdata-platform-menu-config/references/environment.md

@@ -0,0 +1,32 @@
+# 平台环境配置（菜单 SQL 用）
+
+本 skill **自包含**，不依赖其他 skill。
+
+## 数据库（menu-config 需要）
+
+| 变量 | 默认值（本地 Windows） | 说明 |
+|---|---|---|
+| `${MYSQL_HOST}` | `127.0.0.1` | 平台主库 host |
+| `${MYSQL_PORT}` | `3337` | 平台主库 port |
+| `${MYSQL_USER}` | `root` | 平台主库用户 |
+| `${MYSQL_PASSWORD}` | `BigData.2018v6` | 平台主库密码（**生产环境必须改**）|
+| `${MYSQL_DATABASE}` | `cloud` | 平台主库（含 `pf_resource` / `pf_resource_assign` / `pf_org_role` 等）|
+
+## 平台版本
+
+| 变量 | 默认值 |
+|---|---|
+| `${APP_NAME}` | 你的后端应用名（对应 `spring.application.name`）|
+| `${PLATFORM_VERSION}` | `6.x`（你的平台版本号，如 `6.13.2`，与 `pom.xml` 一致）|
+
+## 关联表
+
+- `pf_resource` / `pf_resource_assign` — 资源定义 + 资源分配
+- `pf_org_role` — 角色（`AUTHORITIES_ID` 引用这里）
+- `pf_org_user_role` — 用户-角色关联（确认用户能拿到该角色）
+- `pf_user_info` — 用户（admin / 你的用户 id）
+
+## 跨平台说明
+
+- **Windows**：路径 `D:\...`；MySQL 客户端 `mysql.exe` 或 `mysql -h ...`
+- **macOS / Linux**：路径 `/opt/...` 或 `~/...`；MySQL 客户端 `mysql`

package/skills/meritdata-platform-menu-config/references/field-mapping.md

@@ -0,0 +1,64 @@
+^# 6.x 平台 UI 字段 ↔ 数据库字段映射（通用）
+
+> 实测背景。**通用**：适用任何美林 6.x 二开项目（合同/HR/订单/项目等）。
+> **容易记反**，重点是这张表。
+
+## pf_resource 表字段（平台资源维护 UI → 数据库）
+
+| UI 字段（资源维护页面）| DB 字段 | 类型 | 必填 | 备注 |
+|---|---|---|:---:|---|
+| 资源名称 | `NAME` | varchar(200) | ✅ | |
+| 资源类型（菜单/按钮/其他）| `TYPE` | varchar(32) | ✅ | `'0'` 顶级模块 / `'1'` 菜单 / `'2'` 按钮 |
+| 资源属性（内部/外部）| `ISENTRANCE` | varchar(255) | ⚠️ | `'1'`=内部（勾选"显示为右侧快捷入口"）|
+| 所属应用名 | `APPLICATION_NAME` | varchar(200) | ❌ | 留空也 work |
+| **实际菜单地址** | **`EMBED_URL`** | varchar(1800) | ✅ | **完整 URL / nginx 资源路径**（可带 .html）|
+| **路由地址** | **`URI`** | varchar(600) | ✅ | **vue 路径**（不带 .html，**不带** `http://`）|
+| 排序号 | `SORT` | int | ❌ | 默认 0 |
+| 图标 | `ICON_PATH` | varchar(200) | ❌ | |
+| 显示为右侧快捷入口 | `ISENTRANCE` | varchar(255) | ⚠️ | 与"资源属性"同字段，勾选 = `'1'` |
+
+**两个易错配对**（6.x 平台特有）：
+
+```
+❌ 错：URI = 实际菜单地址 / EMBED_URL = 路由地址
+✅ 对：URI = 路由地址（vue 路径）/ EMBED_URL = 实际菜单地址
+```
+
+参考证据（bpm 二级菜单实际值）：
+```
+URI:       /bpm/procdesigner/index        (vue 路径)
+EMBED_URL: /bpm/procdesigner/index.html   (完整 nginx 资源)
+```
+
+## pf_resource_assign 表字段
+
+| UI 字段（资源授权页面）| DB 字段 | 必填 | 备注 |
+|---|---|:---:|---|
+| 用户 / 角色 | `AUTHORITIES_ID` | ✅ | 6.x 兼容：可填**用户 ID** 也可填**角色 ID** |
+| 资源 | `PRIV_ID` | ✅ | 对应 `pf_resource.ID` |
+| 类型 | `TYPE` | ✅ | **`'6'` 必填**（菜单分配） |
+
+**关键发现**：`AUTHORITIES_ID` 字段名是 `AUTHORITIES_ID`（"authorities"），但 6.x 平台**实际是用户 ID 或角色 ID**——这是最反直觉的字段命名坑。
+
+**用户 ID 来源**：
+```sql
+-- 找当前登录用户
+SELECT ID, NAME FROM pf_user_info WHERE LOGIN_NAME = 'admin';
+-- 用户的角色（如果用角色授权）
+SELECT USER_ID, AUTHORITIES_ID FROM pf_org_user_role WHERE USER_ID = '<用户 id>';
+```
+
+**角色 ID 来源**：
+```sql
+SELECT ID, NAME FROM pf_org_role WHERE NAME LIKE '%管理员%';
+-- 常见：XTGLY=系统管理员, AQGLY=安全管理员, AQSJY=安全审计员
+```
+
+## 字段语义反直觉的 4 个点
+
+| # | 字段 | 你的直觉 | 实际语义 |
+|---|---|---|---|
+| 1 | `SHOW_MENU='0'` | 不显示 | **显示**（6.x 平台反语义） |
+| 2 | `SHOW_MENU='1'` | 显示 | **隐藏** |
+| 3 | `URI` 完整 URL | 实际菜单 | **vue 路径**（主 SPA 用 vue-router.push） |
+| 4 | `URI` vue 路径 | 路由 | 实际是（与你直觉相反）|