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

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` |

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

@@ -0,0 +1,56 @@
+---
+name: meritdata-platform-messaging
+description: MeritData 消息通知专项。用于站内信、邮件、短信、企业微信、钉钉集成；消息模板与发送策略。
+metadata:
+  version: "1.0.0"
+  author: 技术平台部门架构组
+  source: company
+  date_added: "2026-09-01"
+  last_updated: "2026-09-01"
+  risk: low
+  allowed-tools: Read, Grep, Glob
+---
+
+## ⭐ MUST DO
+
+**消息发送异步化、幂等化；模板与发送分离；失败重试 + 死信队列。**
+
+## 触发条件 / 不适用
+
+**适用**：
+- 站内信
+- 邮件
+- 短信
+- 企业微信 / 钉钉
+
+**不适用**：
+- 平台内置通知接口 → `meritdata-platform-integration`
+
+## 主题路由
+
+### 公司级研发攻略（dev-docs 整合）
+
+| 攻略 | 内容 | 入口 |
+|------|------|------|
+| **攻略12：消息中心（5 章）** | 消息中心页面功能、接口功能、附件上传下载 | [`references/msg-center/攻略-12-消息中心-00_总览.md`](references/msg-center/攻略-12-消息中心-00_总览.md) |
+
+## 工作方式
+
+1. 消息模板预定义（带变量占位符）
+2. 业务触发 → 异步消息队列 → 实际发送
+3. 失败重试（指数退避）+ 死信队列
+4. 幂等键防止重复发送
+
+## 🚨 常见错误
+
+| 错误 | 后果 | 正确做法 |
+| --- | --- | --- |
+| 同步发送 | 阻塞业务 | 异步消息队列 |
+| 无幂等 | 重复发送 | 幂等键 |
+| 失败无重试 | 消息丢失 | 指数退避 |
+
+## 边界
+
+- **不在本 skill 范围的**：
+  - 平台通知接口 → `meritdata-platform-integration`
+- **强制要求**：异步 + 幂等 + 重试

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

@@ -0,0 +1,15 @@
+display_name: "MeritData 消息通知"
+short_description: "站内信、邮件、短信、企业微信集成"
+default_prompt: |
+  meritdata-platform-messaging 处理消息通知场景。
+
+  适用场景：
+  - 站内信
+  - 邮件
+  - 短信
+  - 企业微信 / 钉钉
+
+  强制约束：
+  - 异步发送
+  - 幂等键
+  - 失败重试 + 死信队列

package/skills/meritdata-platform-messaging/references/announcement-api.md

@@ -0,0 +1,258 @@
+# 消息中心 + 附件 API 速查（基于源码实测）
+
+> **来源**：`AnnouncementController`（位于 `cloud-system-manage-module/.../announcement/`）
+> **核实日期**：2026-09-10
+> **⚠️ 重要修正**：消息列表 HTTP 方法是 **POST** 不是 GET；分页参数是 `page/rows` 不是 `page/size`
+
+---
+
+## 消息中心 API（基于 AnnouncementController 21 个方法）
+
+### 1. 消息列表分页（POST）
+
+```
+POST /api/announcement/page
+Content-Type: application/json
+Body: {
+  "page": 1,
+  "rows": 20,
+  "parentId": "...",
+  "name": "...",
+  "type": "..."
+}
+```
+
+**入参**：
+- `page` 页码（默认 1）
+- `rows` 每页大小（默认 20）
+- `parentId` 父级 ID（可选）
+- `name` 消息名称（可选）
+- `type` 业务类型（可选）
+
+**响应**：`ResultBody<GridView<Announcement>>`
+
+---
+
+### 2. 消息统计（POST）
+
+```
+POST /api/announcement/getMessageCount
+```
+
+**响应**：
+```json
+{
+  "hasSendCount": 0,
+  "timerCount": 0,
+  "notReadTip": 3,
+  "messageCount": 3,
+  "messageCountTip": 3,
+  "notSendCount": 0,
+  "notRead": 3,
+  "hasRead": 0,
+  "modelCount": 0
+}
+```
+
+---
+
+### 3. 消息详情（POST）
+
+```
+POST /api/announcement/getMessageInfor?id=...
+```
+
+**响应**：`Announcement` 实体
+
+---
+
+### 4. PfMessage 详情（POST）
+
+```
+POST /api/announcement/getPfMessageInfor?id=...
+```
+
+**响应**：`PfMessage` 实体
+
+---
+
+### 5. PfMessage 关闭（POST）
+
+```
+POST /api/announcement/getPfMessageClose?id=...
+```
+
+**响应**：`PfMessage` 实体
+
+---
+
+### 6. 更新消息状态（POST）
+
+```
+POST /api/announcement/updateMessageStatus?code=...
+```
+
+**响应**：`boolean`
+
+---
+
+### 7. 保存草稿（POST）
+
+```
+POST /api/announcement/saveMessage
+Body: {
+  "receiverIds": "...",
+  "title": "...",
+  "url": "...",
+  "msgType": "...",
+  "detailContent": "...",
+  "senderId": "..."
+}
+```
+
+**响应**：`String`
+
+---
+
+### 8. 新增消息（POST）
+
+```
+POST /api/announcement/save
+Body: Announcement 实体
+```
+
+**响应**：`ResultBody`
+
+---
+
+### 9. 发送消息（POST/GET）
+
+```
+POST/GET /api/announcement/sendMessageNow?id=...
+```
+
+**响应**：`ResultBody`
+
+---
+
+### 10. 添加发送消息（POST/GET）
+
+```
+POST/GET /api/announcement/addSendMessage
+Body: Announcement 实体
+```
+
+**响应**：`ResultBody`
+
+---
+
+### 11. 添加发送消息并返回接收者（POST）
+
+```
+POST /api/announcement/addSendMessage-return-receiver
+Body: Announcement 实体
+```
+
+**响应**：`ResultBody`
+
+---
+
+### 12. 删除消息（POST/GET）
+
+```
+POST/GET /api/announcement/removeMsg
+Body: { "ids": [...] }
+```
+
+**响应**：`Boolean`
+
+---
+
+### 13. 删除公告（POST/GET）
+
+```
+POST/GET /api/announcement/removeAnnouncement
+Body: { "ids": [...] }
+```
+
+**响应**：`Boolean`
+
+---
+
+### 14. 告警分页（POST/GET）
+
+```
+POST/GET /api/announcement/warn/page
+Body: {
+  "page": 1,
+  "rows": 20,
+  "id": "...",
+  "warnType": "...",
+  "warnStatus": "...",
+  "timeStart": "...",
+  "timeEnd": "...",
+  "detailContent": "...",
+  "orderField": "...",
+  "order": "...",
+  "warnLevel": "..."
+}
+```
+
+---
+
+### 15. 告警已读（POST/GET）
+
+```
+POST/GET /api/announcement/warn/read
+Body: { "ids": "..." }
+```
+
+---
+
+### 16. BPM 触发的发送消息（POST）
+
+```
+POST /api/announcement/addbpmSendMessage
+Body: Announcement 实体
+```
+
+---
+
+### 17. 告警消息接口（特殊用途）
+
+| 方法 | HTTP | 用途 |
+|------|------|------|
+| `/api/announcement/addSendUnauthorizedMessage` | POST/GET | 越权告警 |
+| `/api/announcement/addSendTemperMessage` | POST/GET | 篡改告警 |
+| `/api/announcement/addSendLoginMessage` | POST/GET | 登录失败告警 |
+
+---
+
+## 附件 API
+
+> 附件 API 在 `cloud-system-manage` 模块下，与 messaging 相关但需另外核实
+
+| 操作 | 方法 | URL | Content-Type |
+|------|------|-----|---------------|
+| 上传 | POST | `/api/attachment/upload` | multipart/form-data |
+| 下载 | GET | `/api/attachment/download/{attachmentId}` | - |
+| 删除 | DELETE | `/api/attachment/delete/{attachmentId}` | - |
+
+---
+
+## ⚠️ 关键修正（与之前 skill 对比）
+
+| 之前声明 | 实测正确 | 修正 |
+|---------|---------|------|
+| `GET /api/announcement/list?page=1&size=20` | `POST /api/announcement/page`，Body 用 `Map<String,Object>` | HTTP 方法 + 参数结构 |
+| `size` 每页大小 | `rows` 每页大小 | 参数名 |
+| `startTime/endTime/unreadOnly` 等参数 | 无此参数 | 删除 |
+| `addSendMessage` 是发送 | `addSendMessage` 是新增草稿；`sendMessageNow` 才是发送 | 语义 |
+
+---
+
+## 🔗 相关文档
+
+- `feign-client.md`（CloudFeignMessageClient 5 方法实测）
+- `references/msg-center/`（消息中心 7 大攻略）
+- `dev-docs/21_1.11-1.15基础配置-消息与配置类.md`

package/skills/meritdata-platform-messaging/references/feign-client.md

@@ -0,0 +1,83 @@
+# CloudFeignMessageClient 5 方法速查（基于源码实测）
+
+> **来源**：`com.meritdata.cloud.feignclient.CloudFeignMessageClient`（位于 `cloud-module-mq` 模块）
+> **核实日期**：2026-09-10
+> **⚠️ 重要修正（2026-09-10）**：本节内容基于源码实测，之前 skill 中描述的方法名、路径、注解均不正确
+
+---
+
+## ⚠️ 关键差异说明（与之前 skill 声明对比）
+
+| 维度 | 之前 skill 声明 | 源码实测 |
+|------|---------------|---------|
+| `@FeignClient` 注解 | `@FeignClient("cloud-system-manage")` | ❌ **无 `@FeignClient` 注解**（plain interface） |
+| 接收方实现 | 调用 Feign 客户端 | 通过 `FeignMessageSenderService` 抽象方法返回，由 `FeignMessageSender` 实现 |
+| 注解机制 | Feign 远程调用 | **通过 `MeritdataCloudProperties.sendMessageUrl` 配置 URL，运行时调用** |
+
+---
+
+## 接口定义（实测）
+
+```java
+// 实际源码（基于 2026-09-10 实测）
+public interface CloudFeignMessageClient {
+    boolean sendAssignMessage(MessageBody messageBody);          // POST /api/send-assign-message
+    boolean sendResourceMessage(MessageBody messageBody);      // POST /api/send-resource-message
+    boolean sendRoleMessage(MessageBody messageBody);           // POST /api/send-role-message
+    boolean sendUserRoleMessage(MessageBody messageBody);      // POST /api/send-user-role-message
+    boolean sendUserAppMessage(MessageBody messageBody);       // POST /api/send-user-app-message
+}
+```
+
+### ⚠️ 5 方法名实测 vs skill 声明对比
+
+| # | skill 声明（错误） | 源码实测（正确） | HTTP |
+|---|---------|---------|-----|
+| 1 | `sendToRole(roleCode, msg)` 返回 `ResultBody<Void>` | **`sendRoleMessage(MessageBody)` 返回 `boolean`** | POST `/api/send-role-message` |
+| 2 | `sendToResource(resourceCode, msg)` 返回 `ResultBody<Void>` | **`sendResourceMessage(MessageBody)` 返回 `boolean`** | POST `/api/send-resource-message` |
+| 3 | `sendToUser(userIds, msg)` 返回 `ResultBody<Void>` | **`sendUserRoleMessage(MessageBody)` 返回 `boolean`** | POST `/api/send-user-user-role-message` |
+| 4 | `sendAssigned(userId, msg)` 返回 `ResultBody<Void>` | **`sendAssignMessage(MessageBody)` 返回 `boolean`** | POST `/api/send-assign-message` |
+| 5 | `sendToApp(appCode, msg)` 返回 `ResultBody<Void>` | **`sendUserAppMessage(MessageBody)` 返回 `boolean`** | POST `/api/send-user-app-message` |
+
+---
+
+## MessageBody 类型（替代之前错误的 MessageDTO）
+
+> ⚠️ `MessageDTO` 不存在，正确的入参类型是 `MessageBody`（`com.meritdata.cloud.base.message.entity.MessageBody`）
+> 字段定义需查 `MessageBody.java` 类本身（不复制源码）
+
+---
+
+## 调用方接入方式
+
+### 实际调用方模式
+
+```java
+// 在 cloud-system-manage 等业务模块中，通过 FeignMessageSenderService 抽象方法调用
+@Autowired
+private FeignMessageSenderService messageSender;
+
+// 实际调用（注意：方法名 + 入参类型 + 返回类型 与之前声明不同）
+MessageBody msg = new MessageBody();
+// ... 设置字段（参考 MessageBody 类）
+boolean success = messageSender.getSendMessageClient().sendRoleMessage(msg);
+```
+
+---
+
+## 关键澄清
+
+| 之前说法 | 实测真相 |
+|---------|---------|
+| CloudFeignMessageClient 是 Feign Client | 是 plain interface，被 `FeignMessageSender` 通过抽象方法返回 |
+| `@FeignClient("cloud-system-manage")` | 无该注解；URL 通过 `MeritdataCloudProperties.sendMessageUrl` 配置 |
+| `MessageDTO` 入参 | 实际为 `MessageBody` |
+| 返回 `ResultBody<Void>` | 返回 `boolean` |
+
+---
+
+## 🔗 相关文档
+
+- `announcement-api.md`（消息中心 API 速查）
+- `references/msg-center/`（消息中心 7 大攻略）
+- `dev-docs/21_1.11-1.15基础配置-消息与配置类.md`（消息中心接口契约）