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

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

@@ -1,156 +0,0 @@
-# 菜单资源基础指南（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

@@ -1,197 +0,0 @@
-# 资源扫描与缓存（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

@@ -1,42 +0,0 @@
----
-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

@@ -1,222 +0,0 @@
-# 消息通道配置（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)