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

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 路径 | 路由 | 实际是（与你直觉相反）|

package/skills/meritdata-platform-menu-config/references/insert-menu-template.sql

@@ -0,0 +1,89 @@
+-- ============================================
+-- 美林平台 6.x 二开项目 菜单配置 SQL 模板（通用）
+-- 占位符 ${APP_NAME} ${MENU_ROOT_NAME} ${USER_ID} ${ROLE_CODE}
+-- 用法：sed 或编辑器替换占位符 → 直接跑
+-- ============================================
+
+-- ============================================
+-- 0. 前置：查有效 AUTHORITIES_ID（6.x 平台支持用户 ID 或角色 ID）
+-- ============================================
+-- 选项 A：绑到具体用户（6.x 平台 UI 默认行为，最常见）
+-- SELECT ID, NAME FROM pf_user_info WHERE LOGIN_NAME = '<你的用户名>';
+
+-- 选项 B：绑到角色（XTGLY=系统管理员, AQGLY=安全管理员, XTPTRY=普通用户, AQSJY=安全审计员）
+-- SELECT ID, NAME FROM pf_org_role WHERE NAME LIKE '%管理员%';
+
+-- ============================================
+-- 1. 顶级模块（PARENT_ID='-1'，SHOW_MENU='0' 表示显示，URI='0' 是占位）
+-- ============================================
+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'
+);
+
+-- ============================================
+-- 2. 三个子菜单
+-- ⚠️ URI = vue 路径（不带 .html，不带 http://）
+-- ⚠️ EMBED_URL = 完整 nginx 资源路径
+-- ⚠️ 两端不能有空格
+-- ============================================
+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'),
+('${APP_NAME}-list2', '子菜单2', '1', '${APP_NAME}-root', '0', 'select', 20,
+  '/${APP_NAME}/list2', '/${APP_NAME}/list2/index.html', '1', '1'),
+('${APP_NAME}-list3', '子菜单3', '1', '${APP_NAME}-root', '0', 'select', 30,
+  '/${APP_NAME}/list3', '/${APP_NAME}/list3/index.html', '1', '1');
+
+-- ============================================
+-- 3. 资源授权（v3 平台 AUTHORITIES_ID 可绑用户 ID 也可绑角色 ID）
+-- TYPE = '6' 必填（菜单分配）
+-- ============================================
+
+-- 方式 A：绑到具体用户（6.x 默认行为）
+-- 把 <USER_ID> 替换成从 pf_user_info / pf_org_user_role 查到的 ID
+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'),
+    (REPLACE(UUID(),'-',''), '<USER_ID>', '${APP_NAME}-list2', '6'),
+    (REPLACE(UUID(),'-',''), '<USER_ID>', '${APP_NAME}-list3', '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'),
+--     (REPLACE(UUID(),'-',''), 'XTGLY', '${APP_NAME}-list2', '6'),
+--     (REPLACE(UUID(),'-',''), 'XTGLY', '${APP_NAME}-list3', '6');
+
+-- ============================================
+-- 4. 验证（4 个必查）
+-- ============================================
+-- 4.1 URI 无空格
+-- SELECT ID, URI, LENGTH(URI) AS len, IF(URI = TRIM(URI),'OK','HAS_SPACE') AS space_check
+-- FROM pf_resource WHERE ID LIKE '${APP_NAME}-%';
+
+-- 4.2 SHOW_MENU=0 显示
+-- SELECT ID, NAME, SHOW_MENU, TYPE FROM pf_resource
+-- WHERE ID LIKE '${APP_NAME}-%';
+
+-- 4.3 AUTHORITIES_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 LIKE '${APP_NAME}-%';
+-- ROLE_NAME 为 NULL 但 AUTHORITIES_ID 是用户 ID 也 OK（6.x 兼容）
+
+-- 4.4 PARENT_ID 写真实父
+-- SELECT ID, PARENT_ID, NAME FROM pf_resource WHERE TYPE='1' AND APPLICATION_NAME='${APP_NAME}';
+
+-- ============================================
+-- 5. 如果发现 URI 有空格，修复：
+-- ============================================
+-- UPDATE pf_resource SET URI = TRIM(URI) WHERE ID LIKE '${APP_NAME}-%';

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

@@ -0,0 +1,177 @@
+# 6.x 平台菜单故障排查（5 大坑详解，通用）
+
+> v3 6.13.2 实测。**5 大坑** + 排错流程 + 历史时间线。
+> **通用**：任何美林 6.x 二开项目适用。
+
+## 坑 1：`SHOW_MENU` 语义反（菜单隐藏）
+
+**症状**：菜单完全不显示（其他应用菜单都显示，就你的不显示）
+
+**原因**：`SHOW_MENU='0'` 才是**显示**（6.x 平台反语义），`'1'` 是隐藏（实测确认）
+
+**修法**：
+```sql
+UPDATE pf_resource SET SHOW_MENU = '0' WHERE SHOW_MENU = '1' AND APPLICATION_NAME = '<你的 APP_NAME>';
+```
+
+**根因**：6.x 平台 SHOW_MENU 字段语义反直觉（v2 是 1=显示，v3 相反）。
+
+---
+
+## 坑 2：URI 字段写错（菜单点击跳 /noaccess）
+
+**症状**：菜单能显示但点跳 `/portal/#/noaccess`
+
+**原因**：URI 字段是 **vue 路径**（不带 .html，**不带** `http://`），不是完整 URL
+
+**修法**：
+```sql
+-- 错：完整 URL
+UPDATE pf_resource SET URI = SUBSTRING(URI, LOCATE('//', URI) + 1)  -- 错误示范
+WHERE URI LIKE 'http://%';
+
+-- 对：vue 路径（不带 .html 不带 http://）
+UPDATE pf_resource SET URI = '/<short-app>/list' WHERE ID = '<menu-id>';
+```
+
+**主 SPA 处理逻辑**（实测抓的代码片段）：
+```javascript
+function e(t, n) {
+  if (t.children && t.children.length > 0) {
+    for (var o = t.children, r = 0; r < o.length; r++) e(o[r], n);
+  } else if (n.push(t.uri), t.menuUrl) {        // 1. 第一次 push（URI 字段）
+    var a = t.menuUrl;
+    if (t.menuUrl.indexOf("http") > -1) {       // 2. 含 http 时剥协议取路径
+      var s = t.menuUrl.replace("https://"").replace("http://"");
+      a = s.substring(s.indexOf("/"));
+    }
+    n.push(a);                                  // 3. 第二次 push（处理后路径）
+  }
+}
+```
+
+**关键**：菜单点击触发**两次 vue-router.push()**——`URI` 字段走 vue 路径，`menuUrl`（= EMBED_URL）走完整 URL 但**也被 vue 路由 push**（不是 window.open）。**两次都找不到 → /noaccess**。
+
+---
+
+## 坑 3：URI 前后有空格（最隐蔽的坑）
+
+**症状**：3 个子菜单中**只有 1 个**跳 /noaccess（其它 2 个 work），最隐蔽
+
+**原因**：URI 字段最前面有 1 个空格（手抖输入），主 SPA vue-router 匹配路径失败
+
+**修法**：
+```sql
+-- 1. 找出有空格的资源
+SELECT ID, URI, LENGTH(URI) AS len, IF(URI = TRIM(URI),'OK','HAS_SPACE') AS space_check
+FROM pf_resource WHERE APPLICATION_NAME = '<你的 APP_NAME>';
+
+-- 2. trim 掉
+UPDATE pf_resource SET URI = TRIM(URI) WHERE APPLICATION_NAME = '<你的 APP_NAME>';
+```
+
+**教训**：UI 字段提交时前端应该 `.trim()` 一下，6.x 平台**没做**（实测踩坑）。
+
+---
+
+## 坑 4：PARENT_ID 字面字符串（菜单树挂载失败）
+
+**症状**：菜单**完全不显示**
+
+**原因**：PARENT_ID 写 `'ROOT_MENU'`（字面字符串，找不到父菜单）
+
+**修法**：
+```sql
+-- 顶级菜单
+UPDATE pf_resource SET PARENT_ID = '-1' WHERE PARENT_ID = 'ROOT_MENU' AND TYPE = '0';
+
+-- 子菜单
+UPDATE pf_resource SET PARENT_ID = '<实际父菜单 ID>' WHERE PARENT_ID = 'ROOT_MENU' AND TYPE = '1';
+```
+
+**根因**：6.x 平台PARENT_ID 写真实父菜单 ID（顶级是字面 `'-1'`），不是 `'ROOT_MENU'` 这种字面字符串。
+
+---
+
+## 坑 5：AUTHORITIES_ID 无效（菜单不显示）
+
+**症状**：菜单完全不显示（但 SELECT `pf_resource` 数据在）
+
+**原因**：`AUTHORITIES_ID` 必须有效：
+- 6.x 平台兼容：用户 ID **或** 角色 ID
+- 字段名是 `AUTHORITIES_ID`（误导，实际是用户/角色 ID）
+
+**修法**：
+```sql
+-- 查有效角色
+SELECT ID, NAME FROM pf_org_role;
+-- 常见：XTGLY=系统管理员, AQGLY=安全管理员, AQSJY=安全审计员
+
+-- 查用户
+SELECT ID, NAME FROM pf_user_info WHERE LOGIN_NAME = 'admin';
+```
+
+**坑 1**：`pf_resource_assign.AUTHORITIES_ID` 字段名是 `AUTHORITIES_ID`，但 6.x 实际可绑**用户 ID** 也可绑**角色 ID**。
+
+---
+
+## 排错流程（5 步走）
+
+```
+1. 菜单完全不显示
+   → 检查 SHOW_MENU 字段（应是 '0'）
+   → 检查 AUTHORITIES_ID 字段（应是有效用户 ID 或角色 ID）
+   → 检查 PARENT_ID 字段（应是 '-1' 或真实父 ID）
+   → 选 SELECT * FROM pf_org_user_role WHERE USER_ID = '<你的用户 ID>' 确认角色
+
+2. 菜单能显示但点跳 /noaccess
+   → 检查 URI 字段无前后空格（SELECT TRIM 检查）
+   → 检查 URI 是 vue 路径（不带 http:// 不带 .html）
+   → UPDATE pf_resource SET URI = TRIM(URI); -- 一键修复
+
+3. 菜单点跳新窗口（开了 popup blocker）
+   → URI 含 http:// 触发 window.open
+   → 改 URI 为 vue 路径
+
+4. 菜单点跳 404
+   → nginx 没配 location /<app>/ 块
+   → 或 index 路径写错（用 'index <sub>/index.html' 拼重复）
+   → 改 'index index.html' 不用 'index <sub>/index.html'
+
+5. 菜单点跳空白页
+   → nginx alias 路径错（apps/<app>/ 实际有 build 产物）
+   → 详见 meritdata-platform-frontend-deploy skill
+```
+
+## 关键 SQL 一键诊断（通用模板）
+
+```sql
+-- 1. 看 N 资源完整字段
+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. 看 N 资源分配
+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>-%';
+```
+
+## 5 大坑历史背景（通用化）
+
+**注**：以下是 实测时**任意 `${APP_NAME}` 项目上线**都可能踩过的 5 大坑历史背景（**时间点不通用**——只是说明 5 大坑是真实存在的，不是 demo 例子）。具体修复见上文各坑"修法"小节。
+
+| 现象 | 修复（精简）|
+|---|---|
+| `SHOW_MENU='1'` 菜单隐藏 | 改 `'0'` |
+| `PARENT_ID='ROOT_MENU'` 菜单树挂载失败 | 改 `'-1'` |
+| `URI='http://...'` 完整 URL vue 路由失败 | 改 vue 路径（不带 http://）|
+| 资源删除失败（已软删的资源）URI 前面 1 空格 | `UPDATE ... SET URI = TRIM(URI)` |
+| `index <子路径>/index.html` nginx 拼重复 | 改 `index index.html` |