@alanwang-merit/meritdata-platform-skill-package 1.0.0

package/skills/meritdata-platform-menu-resource/references/guide.md

@@ -0,0 +1,156 @@
+# 菜单资源基础指南（menu-resource）
+
+> 菜单资源把"菜单"和"后端 API"绑定，实现接口级别的权限控制。
+
+---
+
+## 1. 资源模型
+
+```
+Resource (资源)
+├── code           -- 资源编码（如 "order:create"）
+├── name           -- 资源名称
+├── path           -- API 路径（Ant 风格）
+├── method         -- HTTP 方法（GET/POST/...）
+├── module         -- 所属模块
+└── description
+```
+
+## 2. @MenuResource 注解
+
+### 2.1 标注 Controller / 方法
+
+```java
+@RestController
+@RequestMapping("/api/v1/orders")
+@MenuResource(module = "ORDER", code = "order:module")
+public class OrderController {
+
+    @GetMapping
+    @MenuResource(code = "order:list", name = "订单列表")
+    public List<OrderDTO> list() { ... }
+
+    @PostMapping
+    @MenuResource(code = "order:create", name = "新建订单")
+    public Result create(@RequestBody OrderDTO order) { ... }
+
+    @DeleteMapping("/{id}")
+    @MenuResource(code = "order:delete", name = "删除订单")
+    public Result delete(@PathVariable String id) { ... }
+}
+```
+
+### 2.2 注解参数
+
+| 参数 | 必填 | 含义 |
+|------|------|------|
+| code | ✅ | 资源编码（全局唯一）|
+| name | 否 | 资源名称 |
+| module | 否 | 所属模块（便于管理）|
+| description | 否 | 资源描述 |
+
+## 3. 资源注册
+
+### 3.1 启动时扫描
+
+平台启动时扫描所有 `@MenuResource` 注解的资源，自动注册到资源表：
+
+```
+扫描 @MenuResource 注解
+   ↓
+对比数据库已有资源
+   ↓
+新增 / 更新 / 删除
+```
+
+### 3.2 二开资源
+
+二开项目的 Controller 上加 `@MenuResource` 注解即可，平台**自动扫描**（前提：纳入平台扫描范围）。
+
+## 4. 资源授权
+
+### 4.1 角色 → 资源
+
+```java
+@PostMapping("/admin/roles/{roleCode}/resources")
+public Result assignResources(@PathVariable String roleCode, @RequestBody List<String> resourceCodes) {
+    resourceService.assignToRole(roleCode, resourceCodes);
+    return Result.success();
+}
+```
+
+### 4.2 用户 → 资源（通过角色）
+
+```java
+public List<String> userResources(String userId) {
+    List<String> roleCodes = userClient.listRoleCodesByUser(userId);
+    Set<String> resources = new HashSet<>();
+    for (String roleCode : roleCodes) {
+        resources.addAll(resourceService.resourcesByRole(roleCode));
+    }
+    return new ArrayList<>(resources);
+}
+```
+
+## 5. 权限校验
+
+### 5.1 @PreAuthorize 注解
+
+```java
+@PostMapping
+@PreAuthorize("hasAuthority('order:create')")
+public Result create(@RequestBody OrderDTO order) { ... }
+```
+
+### 5.2 自动拦截
+
+平台通过 AOP 拦截所有 `@MenuResource` 注解的方法 → 自动校验 `code` 权限。
+
+```java
+// 不加 @PreAuthorize 也行，平台自动拦截
+@PostMapping
+@MenuResource(code = "order:create")
+public Result create(@RequestBody OrderDTO order) { ... }
+```
+
+### 5.3 自定义 SpEL
+
+```java
+@PreAuthorize("hasAuthority('order:approve') and #order.amount <= 10000")
+public Result approve(@RequestBody OrderDTO order) { ... }
+```
+
+## 6. ❌ 反模式
+
+### 6.1 ❌ 不注册资源，权限硬编码
+
+```java
+// ❌ 错：权限字符串硬编码
+@PreAuthorize("hasAuthority('order_special')")  // 没注册的资源
+```
+
+✅ 用 `@MenuResource` 注册过的 `code`。
+
+### 6.2 ❌ 路径用通配符全开
+
+```java
+// ❌ 错
+@MenuResource(code = "*", path = "/**")  // 所有接口
+```
+
+✅ 精确到具体接口。
+
+### 6.3 ❌ 不写 method
+
+```java
+// ❌ 错
+@MenuResource(path = "/orders/{id}/delete")  // 没 method
+```
+
+✅ 显式 method。
+
+## 7. 关联阅读
+
+- [auth-and-path.md](auth-and-path.md) — 资源授权 + 路径匹配
+- [scan-and-cache.md](scan-and-cache.md) — 资源扫描 + 缓存
+- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-menu-resource/references/scan-and-cache.md

@@ -0,0 +1,197 @@
+# 资源扫描与缓存（menu-resource）
+
+> @MenuResource 启动扫描；资源缓存；变更同步。
+
+---
+
+## 1. 启动扫描
+
+### 1.1 流程
+
+```
+应用启动
+   ↓
+扫描 @MenuResource 注解
+   ↓
+提取所有 (code, path, method)
+   ↓
+对比数据库资源表
+   ↓
+新增 / 更新 / 清理无效
+   ↓
+缓存到 Redis
+```
+
+### 1.2 自定义扫描
+
+```java
+@Component
+public class ResourceScanner implements ApplicationRunner {
+
+    @Autowired
+    private ResourceRepository resourceRepository;
+
+    @Override
+    public void run(ApplicationArguments args) {
+        List<Resource> scanned = scanFromAnnotations();
+        syncToDatabase(scanned);
+    }
+
+    private List<Resource> scanFromAnnotations() {
+        List<Resource> resources = new ArrayList<>();
+        for (Class<?> controller : scanControllers()) {
+            MenuResource classAnno = controller.getAnnotation(MenuResource.class);
+            for (Method method : controller.getDeclaredMethods()) {
+                MenuResource methodAnno = method.getAnnotation(MenuResource.class);
+                if (methodAnno != null) {
+                    resources.add(buildResource(classAnno, methodAnno, method));
+                }
+            }
+        }
+        return resources;
+    }
+}
+```
+
+### 1.3 增量扫描
+
+只扫描启动后变更的：
+
+```java
+@Scheduled(fixedDelay = 300_000)  // 5 分钟一次
+public void incrementalScan() {
+    List<Resource> recent = scanFromAnnotations();
+    Set<String> dbCodes = resourceRepository.findAllCodes();
+
+    for (Resource r : recent) {
+        if (!dbCodes.contains(r.getCode())) {
+            resourceRepository.save(r);  // 新增
+        } else {
+            resourceRepository.update(r); // 更新
+        }
+    }
+}
+```
+
+## 2. 资源缓存
+
+### 2.1 缓存结构
+
+```
+resource:all                                  所有资源
+resource:code:{code}                          按 code
+resource:path:{method}:{path}                 按 method+path
+role:resources:{roleCode}                     角色的资源
+user:resources:{userId}                       用户的资源
+```
+
+### 2.2 缓存策略
+
+| Key | TTL | 失效触发 |
+|-----|-----|---------|
+| resource:all | 30m | 启动扫描 |
+| role:resources:{role} | 30m | 角色授权变更 |
+| user:resources:{userId} | 5m | 角色变更 / 30m TTL |
+
+### 2.3 缓存预热
+
+```java
+@Component
+public class ResourceCacheWarmup implements ApplicationRunner {
+    @Override
+    public void run(ApplicationArguments args) {
+        // 预热所有资源
+        resourceService.allResources();
+    }
+}
+```
+
+## 3. 变更同步
+
+### 3.1 资源变更广播
+
+```java
+@EventListener
+public void onResourceChanged(ResourceChangedEvent event) {
+    cacheManager.evict("resource:all");
+    cacheManager.evict("resource:code:" + event.getCode());
+    cacheManager.evict("resource:path:*");  // 路径变化影响所有
+
+    // 受影响角色的资源缓存
+    List<String> roleCodes = resourceService.rolesByResource(event.getCode());
+    for (String roleCode : roleCodes) {
+        cacheManager.evict("role:resources:" + roleCode);
+    }
+}
+```
+
+### 3.2 角色授权变更
+
+```java
+@EventListener
+public void onRoleResourceChanged(RoleResourceChangedEvent event) {
+    // 清角色资源
+    cacheManager.evict("role:resources:" + event.getRoleCode());
+
+    // 清该角色下所有用户的资源
+    List<String> userIds = userClient.listUserIdsByRole(event.getRoleCode());
+    for (String userId : userIds) {
+        cacheManager.evict("user:resources:" + userId);
+    }
+}
+```
+
+## 4. 资源版本控制
+
+### 4.1 场景
+
+部署新版本 → 新增资源 → 旧缓存 5 分钟内没刷新 → 用户权限未生效。
+
+### 4.2 解决
+
+资源表加 `version` 字段，启动时自增；缓存 key 带版本：
+
+```
+resource:v1:all
+resource:v2:all    ← 新版本
+```
+
+部署时自动切版本 → 旧缓存自然失效。
+
+## 5. 监控指标
+
+```
+resource_scan_duration_ms        扫描耗时
+resource_scan_total              扫描到的资源数
+resource_cache_hit_ratio         资源缓存命中率
+resource_check_duration_ms       权限校验耗时
+```
+
+## 6. ❌ 反模式
+
+### 6.1 ❌ 启动时全量扫描后无变更机制
+
+```java
+// ❌ 错：启动扫一次就完事
+@Override
+public void run(ApplicationArguments args) {
+    scanAndSave();
+}
+```
+
+✅ 增量扫描 + 变更事件。
+
+### 6.2 ❌ 资源缓存无失效
+
+```java
+// ❌ 错：资源改了，缓存不变
+resourceRepository.update(resource);  // 没清缓存
+```
+
+✅ 触发缓存失效。
+
+## 7. 关联阅读
+
+- [guide.md](guide.md) — 资源基础
+- [auth-and-path.md](auth-and-path.md) — 资源授权
+- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-message-center/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: meritdata-platform-message-center
+description: |
+  消息中心。站内信 / 短信 / 邮件 / App 推送 / 钉钉企业微信；统一发送接口、模板管理、发送记录。
+  触发场景：业务需要发通知（订单审批结果、系统告警、待办提醒）；多通道统一接入；消息模板管理。
+  何时不用：纯 IM 聊天功能（点对点即时通信）；日志告警（Prometheus）。
+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
+---
+
+# 消息中心（message-center）
+
+## 触发
+- 业务事件需要主动通知用户（订单审批结果）
+- 多通道发送（站内信 + 短信 + 邮件）
+- 消息模板集中管理（多语言、变量替换）
+- 发送记录查询与统计
+
+## 不触发
+- 实时 IM 聊天 → 不归本 skill（用 IM SDK）
+- 系统告警 → 用 Prometheus / 钉钉告警机器人
+- 用户订阅 / 推送偏好设置 → 单独业务
+
+## 前置约束
+- 第三方短信/推送供应商配置在平台，二开不重写
+- 发送走异步队列，**禁止**阻塞业务流程
+- 模板变量严格校验，**禁止**未脱敏的用户数据进模板
+
+## 路由
+- 统一发送接口 + 模板 → [references/guide.md](references/guide.md)
+- 多通道（短信/邮件/推送）配置 → [references/channels.md](references/channels.md)
+- 发送记录 / 失败重试 / 统计 → [references/reliability.md](references/reliability.md)
+- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-message-center/references/channels.md

@@ -0,0 +1,222 @@
+# 消息通道配置（message-center）
+
+> 短信 / 邮件 / 推送 / 钉钉 / 企业微信 的供应商配置和故障转移。
+
+---
+
+## 1. 通道配置总览
+
+```yaml
+message:
+  channels:
+    sms:
+      providers:
+        - name: aliyun
+          weight: 70            # 权重
+          enabled: true
+        - name: tencent
+          weight: 30
+          enabled: true
+    email:
+      providers:
+        - name: smtp
+          enabled: true
+          host: smtp.example.com
+    push:
+      providers:
+        - name: getui
+          enabled: true
+        - name: jpush
+          enabled: false         # 暂时禁用
+```
+
+## 2. 短信通道
+
+### 2.1 多供应商配置
+
+```yaml
+sms:
+  providers:
+    - name: aliyun
+      access-key: ${ALIYUN_ACCESS_KEY}
+      secret-key: ${ALIYUN_SECRET_KEY}
+      sign-name: MeritData
+      template-id-mapping: ...
+      weight: 70
+      enabled: true
+    - name: tencent
+      app-id: ${TENCENT_APP_ID}
+      app-key: ${TENCENT_APP_KEY}
+      sign-name: MeritData
+      weight: 30
+      enabled: true
+```
+
+### 2.2 故障转移
+
+```
+发送短信
+   ↓
+阿里云（weight 70）
+   ↓ 失败
+腾讯云（weight 30）
+   ↓ 失败
+重试 + 告警
+```
+
+### 2.3 限流
+
+```yaml
+sms:
+  rate-limit:
+    per-user-per-minute: 1        # 单用户每分钟 1 条
+    per-user-per-day: 10          # 单用户每天 10 条
+    per-tenant-per-hour: 1000      # 单租户每小时 1000 条
+```
+
+## 3. 邮件通道
+
+### 3.1 SMTP 配置
+
+```yaml
+email:
+  provider: smtp
+  smtp:
+    host: smtp.example.com
+    port: 465
+    username: ${EMAIL_USERNAME}
+    password: ${EMAIL_PASSWORD}
+    ssl: true
+  from: noreply@meritdata.com
+  from-name: MeritData Platform
+```
+
+### 3.2 模板渲染
+
+```
+模板: WELCOME_EMAIL
+主题: 欢迎加入 MeritData
+正文: 尊敬的 ${userName}，您的账号已开通...
+```
+
+### 3.3 附件发送
+
+```java
+MessageDTO msg = MessageDTO.builder()
+    .type(MessageType.EMAIL)
+    .userId("10001")
+    .templateCode("ORDER_REPORT")
+    .params(params)
+    .attachment(new FileAttachment("月报.pdf", bytes))
+    .build();
+```
+
+## 4. App 推送
+
+### 4.1 个推配置
+
+```yaml
+push:
+  providers:
+    - name: getui
+      app-id: ${GETUI_APP_ID}
+      app-key: ${GETUI_APP_KEY}
+      master-secret: ${GETUI_MASTER_SECRET}
+```
+
+### 4.2 按设备类型路由
+
+```java
+MessageDTO msg = MessageDTO.builder()
+    .type(MessageType.PUSH)
+    .userId("10001")
+    .title("新消息")
+    .content("您有 1 条新消息")
+    .platform("android")         // 限定 android
+    .build();
+```
+
+### 4.3 点击跳转
+
+```java
+MessageDTO msg = MessageDTO.builder()
+    .type(MessageType.PUSH)
+    .userId("10001")
+    .title("新消息")
+    .content("您有 1 条新消息")
+    .clickAction(new ClickAction(
+        ClickActionType.URL,
+        "https://example.com/orders/ORD001"
+    ))
+    .build();
+```
+
+## 5. 钉钉 / 企业微信
+
+### 5.1 钉钉机器人
+
+```yaml
+dingtalk:
+  webhook: ${DINGTALK_WEBHOOK}
+  secret: ${DINGTALK_SECRET}
+```
+
+发送：
+
+```java
+messageService.sendByTemplate("DINGTALK_ALERT", params);
+// 模板配置：接收人=运维组，内容=markdown
+```
+
+### 5.2 企业微信应用
+
+```yaml
+wechat-work:
+  corp-id: ${WX_CORP_ID}
+  agent-id: ${WX_AGENT_ID}
+  secret: ${WX_APP_SECRET}
+```
+
+## 6. 通道选择策略
+
+```yaml
+message:
+  routing:
+    # 模板: 通道
+    default: [INNER]
+    ORDER_APPROVED: [INNER, EMAIL]
+    SYSTEM_ALERT: [INNER, DINGTALK, SMS]
+    PAYMENT_SUCCESS: [INNER, SMS]
+```
+
+## 7. ❌ 反模式
+
+### 7.1 ❌ 通道硬编码
+
+```java
+// ❌ 错
+if (type == SMS) {
+    aliyunSmsClient.send(...);
+} else if (type == EMAIL) {
+    javaMailSender.send(...);
+}
+```
+
+✅ 用平台统一接口。
+
+### 7.2 ❌ 单供应商无备份
+
+```yaml
+# ❌ 错：只有一个短信供应商
+sms:
+  providers:
+    - aliyun     # 阿里云挂了就废了
+```
+
+✅ 多供应商 + 故障转移。
+
+## 8. 关联阅读
+
+- [guide.md](guide.md) — 消息中心基础
+- [reliability.md](reliability.md) — 可靠性
+- [SKILL.md](../SKILL.md)