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

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

@@ -0,0 +1,164 @@
+# 菜单配置基础指南（menu-config）
+
+> 菜单由平台统一管理。二开新增菜单**必须**通过平台后台，不在代码里硬编码。
+
+---
+
+## 1. 菜单模型
+
+```
+Menu (菜单)
+├── id
+├── code            -- 菜单编码（如 "order.list"）
+├── name            -- 显示名称
+├── icon            -- 图标
+├── path            -- 路由路径（如 "/orders"）
+├── parent_id       -- 父菜单
+├── sort            -- 排序
+├── enabled          -- 启用
+├── hidden          -- 隐藏
+├── i18n_key        -- 多语言 key
+└── children
+```
+
+## 2. 菜单查询 API
+
+### 2.1 当前用户菜单
+
+```java
+@GetMapping("/menus/current")
+public List<MenuDTO> currentMenus() {
+    return menuService.currentMenus(SecurityUtils.getCurrentUserId());
+}
+```
+
+返回用户可见的所有菜单（按父子结构）。
+
+### 2.2 按角色查菜单
+
+```java
+@GetMapping("/admin/roles/{roleCode}/menus")
+public List<MenuDTO> menusByRole(@PathVariable String roleCode) {
+    return menuService.menusByRole(roleCode);
+}
+```
+
+### 2.3 单个菜单
+
+```java
+@GetMapping("/menus/{code}")
+public MenuDTO menuByCode(@PathVariable String code) {
+    return menuService.getByCode(code);
+}
+```
+
+## 3. 前端集成
+
+### 3.1 启动时拉取菜单
+
+```typescript
+// 前端代码（伪代码）
+const menus = await fetch('/api/v1/menus/current');
+const router = buildRouter(menus);
+```
+
+### 3.2 菜单数据格式
+
+```json
+[
+  {
+    "code": "order",
+    "name": "订单管理",
+    "icon": "icon-order",
+    "path": "/orders",
+    "children": [
+      {
+        "code": "order.list",
+        "name": "订单列表",
+        "path": "/orders/list"
+      },
+      {
+        "code": "order.approve",
+        "name": "订单审批",
+        "path": "/orders/approve"
+      }
+    ]
+  }
+]
+```
+
+## 4. 菜单管理
+
+### 4.1 通过平台后台
+
+平台提供菜单管理界面：
+
+- 菜单树维护
+- 菜单新增/修改/删除
+- 启用/隐藏
+- 排序（拖拽）
+- 多语言配置
+
+### 4.2 二开禁止的写法
+
+```java
+// ❌ 错：代码里硬编码菜单
+@Configuration
+public class MenuConfig {
+    @Bean
+    public Menu orderMenu() {
+        return Menu.of("order.list", "订单列表", "/orders");
+    }
+}
+```
+
+✅ 通过平台后台添加。
+
+## 5. 菜单与权限的关系
+
+| 维度 | 菜单权限 | 按钮权限 | API 权限 |
+|------|---------|---------|---------|
+| 粒度 | 页面级 | 按钮级 | 接口级 |
+| 实现 | 菜单显示/隐藏 | 按钮显示/隐藏 | 接口拦截 |
+| 配置 | 角色 → 菜单 | 角色 → 权限点 | 角色 → 资源 |
+| Skill | menu-config | permission | menu-resource |
+
+## 6. ❌ 反模式
+
+### 6.1 ❌ 前端硬编码菜单
+
+```typescript
+// ❌ 错
+const menus = [
+  { path: '/orders', name: '订单列表' },
+  { path: '/users', name: '用户列表' }
+];
+```
+
+✅ 后端动态菜单。
+
+### 6.2 ❌ 二开加菜单走代码
+
+```java
+// ❌ 错：二开项目里建菜单表 + 写代码维护
+@Entity @TableName("t_2nd_menu")
+public class Menu { ... }
+```
+
+✅ 平台统一菜单表。
+
+### 6.3 ❌ 菜单全量推送给前端
+
+```java
+// ❌ 错：返回所有菜单（即使无权限）
+@GetMapping("/menus/all")
+public List<MenuDTO> allMenus() { ... }
+```
+
+✅ 按用户权限过滤。
+
+## 7. 关联阅读
+
+- [role-and-tree.md](role-and-tree.md) — 角色授权 + 菜单树
+- [i18n-and-cache.md](i18n-and-cache.md) — 多语言 + 缓存
+- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-menu-config/references/i18n-and-cache.md

@@ -0,0 +1,180 @@
+# 菜单国际化与缓存（menu-config）
+
+> 菜单多语言 / 缓存策略 / 变更广播。
+
+---
+
+## 1. 菜单国际化
+
+### 1.1 多语言数据模型
+
+```sql
+CREATE TABLE t_menu (
+    id BIGINT PRIMARY KEY,
+    code VARCHAR(50) UNIQUE,
+    name_zh VARCHAR(100),        -- 中文
+    name_en VARCHAR(100),        -- 英文
+    name_ja VARCHAR(100),        -- 日文
+    path VARCHAR(200),
+    parent_id BIGINT,
+    ...
+);
+```
+
+### 1.2 按语言返回
+
+```java
+@GetMapping("/menus/current")
+public List<MenuDTO> currentMenus(@RequestHeader(defaultValue = "zh") String lang) {
+    return menuService.currentMenus(userId, lang);
+}
+```
+
+```json
+[
+  {"code": "order", "name": "订单管理", "nameEn": "Orders", "path": "/orders"},
+  {"code": "user", "name": "用户管理", "nameEn": "Users", "path": "/users"}
+]
+```
+
+### 1.3 Fallback 链
+
+```java
+public String getLocalizedName(MenuDTO menu, String lang) {
+    String name = menu.getLocalizedName(lang);
+    if (name == null) {
+        // 链式 fallback: zh-CN → zh → en
+        name = menu.getLocalizedName(lang.split("-")[0]);
+    }
+    if (name == null) {
+        name = menu.getName();
+    }
+    return name;
+}
+```
+
+### 1.4 前端处理
+
+前端按 `Accept-Language` 自动选：
+
+```typescript
+const userLang = navigator.language;  // "zh-CN" / "en-US"
+const name = menu[`name${userLang.split('-')[0].toUpperCase()}`] || menu.name;
+```
+
+## 2. 缓存策略
+
+### 2.1 多级缓存
+
+```
+L1: 本地缓存（Caffeine，5 分钟）
+   ↓ miss
+L2: Redis（30 分钟）
+   ↓ miss
+DB
+```
+
+### 2.2 缓存 key 设计
+
+```
+menu:user:{userId}             当前用户菜单
+menu:user:{userId}:lang:{lang} 多语言菜单
+menu:role:{roleCode}           角色菜单
+menu:all                       全量菜单（管理员用）
+```
+
+### 2.3 配置
+
+```yaml
+menu:
+  cache:
+    local:
+      expire-after-write: 5m
+      maximum-size: 10000
+    redis:
+      ttl: 30m
+      jitter: 5m
+```
+
+## 3. 变更广播
+
+### 3.1 平台事件
+
+```java
+@EventListener
+public void onMenuChanged(MenuChangedEvent event) {
+    switch (event.getChangeType()) {
+        case ADD:
+        case UPDATE:
+        case DELETE:
+            evictMenuCache(event.getMenuCode());
+            break;
+        case ROLE_MENU_CHANGED:
+            evictRoleMenuCache(event.getRoleCode());
+            break;
+    }
+}
+
+private void evictMenuCache(String menuCode) {
+    // 清本地下所有 menu:user:* 中含该菜单的缓存（用 tag）
+    // 清 Redis menu:role:*
+}
+```
+
+### 3.2 Pub/Sub
+
+```yaml
+menu:
+  cache:
+    broadcast-channel: menu:changed
+```
+
+## 4. 缓存预热
+
+```java
+@Component
+public class MenuWarmup implements ApplicationRunner {
+    @Override
+    public void run(ApplicationArguments args) {
+        // 加载全量菜单到缓存
+        menuService.allMenus();
+    }
+}
+```
+
+## 5. ❌ 反模式
+
+### 5.1 ❌ 菜单无缓存
+
+```java
+// ❌ 错：每次请求查 DB
+public List<MenuDTO> currentMenus(String userId) {
+    return menuRepository.findByUserId(userId);
+}
+```
+
+✅ 加缓存。
+
+### 5.2 ❌ 缓存不失效
+
+```java
+// ❌ 错：改了菜单不通知缓存
+menuRepository.save(menu);  // 用户看到旧菜单
+```
+
+✅ 发广播事件。
+
+### 5.3 ❌ 多语言字符串拼接
+
+```java
+// ❌ 错
+String name = (lang.equals("en") ? menu.getNameEn() : menu.getName());
+```
+
+✅ 用 `getLocalizedName(lang)` 统一处理 fallback。
+
+## 6. 关联阅读
+
+- [guide.md](guide.md) — 菜单基础
+- [role-and-tree.md](role-and-tree.md) — 角色授权
+- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-menu-config/references/role-and-tree.md

@@ -0,0 +1,170 @@
+# 角色授权与菜单树构建（menu-config）
+
+> 角色 → 菜单授权；用户 → 菜单计算；菜单树构建。
+
+---
+
+## 1. 角色授权
+
+### 1.1 给角色分配菜单
+
+```java
+@PostMapping("/admin/roles/{roleCode}/menus")
+@PreAuthorize("hasRole('ADMIN')")
+public Result assignMenus(@PathVariable String roleCode, @RequestBody List<String> menuCodes) {
+    menuService.assignMenus(roleCode, menuCodes);
+    return Result.success();
+}
+```
+
+### 1.2 角色已有菜单
+
+```java
+@GetMapping("/admin/roles/{roleCode}/menus")
+public List<MenuDTO> roleMenus(@PathVariable String roleCode) {
+    return menuService.menusByRole(roleCode);
+}
+```
+
+### 1.3 全量菜单（管理员视角）
+
+```java
+@GetMapping("/admin/menus/all")
+public List<MenuDTO> allMenus() {
+    return menuService.allMenus();
+}
+```
+
+## 2. 用户菜单计算
+
+### 2.1 用户的多角色合并
+
+```java
+// 用户可能有多个角色：ROLE_ADMIN + ROLE_FINANCE
+// 菜单取并集
+public List<MenuDTO> currentMenus(String userId) {
+    List<String> roleCodes = userClient.listRoleCodesByUser(userId);
+    Set<MenuDTO> menuSet = new HashSet<>();
+    for (String roleCode : roleCodes) {
+        menuSet.addAll(menuService.menusByRole(roleCode));
+    }
+    return new ArrayList<>(menuSet);
+}
+```
+
+### 2.2 排除隐藏菜单
+
+```java
+public List<MenuDTO> currentMenus(String userId) {
+    return calculate(userId).stream()
+        .filter(m -> !m.isHidden())
+        .filter(MenuDTO::isEnabled)
+        .collect(Collectors.toList());
+}
+```
+
+## 3. 菜单树构建
+
+### 3.1 平铺数据 → 树形
+
+```java
+public List<MenuDTO> buildTree(List<MenuDTO> flatMenus) {
+    Map<String, MenuDTO> map = flatMenus.stream()
+        .collect(Collectors.toMap(MenuDTO::getCode, Function.identity()));
+
+    List<MenuDTO> roots = new ArrayList<>();
+    for (MenuDTO menu : flatMenus) {
+        if (menu.getParentCode() == null) {
+            roots.add(menu);
+        } else {
+            MenuDTO parent = map.get(menu.getParentCode());
+            if (parent != null) {
+                parent.getChildren().add(menu);
+            }
+        }
+    }
+    // 排序
+    roots.forEach(this::sortRecursively);
+    return roots;
+}
+
+private void sortRecursively(MenuDTO menu) {
+    menu.getChildren().sort(Comparator.comparing(MenuDTO::getSort));
+    menu.getChildren().forEach(this::sortRecursively);
+}
+```
+
+### 3.2 按 sort + code 稳定排序
+
+```java
+Comparator<MenuDTO> comparator = Comparator
+    .comparing(MenuDTO::getSort, Comparator.nullsLast(Comparator.naturalOrder()))
+    .thenComparing(MenuDTO::getCode);
+
+roots.sort(comparator);
+```
+
+## 4. 父子菜单完整性
+
+### 4.1 问题
+
+父菜单被隐藏，子菜单可见 → 子菜单孤立显示。
+
+### 4.2 解决
+
+```java
+// 向上找所有祖先，直到全可见或到根
+private boolean isVisibleWithAncestors(MenuDTO menu, Set<String> visibleCodes) {
+    MenuDTO current = menu;
+    while (current != null) {
+        if (!visibleCodes.contains(current.getCode())) {
+            return false;
+        }
+        current = parentMap.get(current.getCode());
+    }
+    return true;
+}
+```
+
+## 5. 角色变更时缓存失效
+
+```java
+@EventListener
+public void onRoleMenuChanged(RoleMenuChangedEvent event) {
+    // 清所有受影响用户的菜单缓存
+    List<String> userIds = userClient.listUserIdsByRole(event.getRoleCode());
+    for (String userId : userIds) {
+        cacheManager.evict("userMenus", userId);
+    }
+}
+```
+
+## 6. ❌ 反模式
+
+### 6.1 ❌ 每次请求实时算菜单树
+
+```java
+// ❌ 错：每个请求重新算
+@GetMapping("/menus/current")
+public List<MenuDTO> currentMenus() {
+    List<MenuDTO> flat = menuService.flatByUser(userId);  // 查 DB
+    return buildTree(flat);  // 每次算
+}
+```
+
+✅ 加缓存。
+
+### 6.2 ❌ 角色菜单不排序
+
+```java
+// ❌ 错：菜单顺序乱
+roots.forEach(r -> r.getChildren().forEach(c -> ...));
+```
+
+✅ 按 sort 字段排序。
+
+## 7. 关联阅读
+
+- [guide.md](guide.md) — 菜单基础
+- [i18n-and-cache.md](i18n-and-cache.md) — 多语言 + 缓存
+- [SKILL.md](../SKILL.md)

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

@@ -0,0 +1,42 @@
+---
+name: meritdata-platform-menu-resource
+description: |
+  菜单资源。菜单与后端 API 资源映射 / 资源注册 / 资源授权 / 资源路径匹配。
+  触发场景：新增菜单需要绑定后端接口资源 / 资源注册（让平台扫描 API）/ 资源授权（角色绑定资源）/ 菜单资源对应关系维护。
+  何时不用：纯菜单查询 → 用 menu-config；纯按钮权限（前端）→ 用 permission。
+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-resource）
+
+## 触发
+- 新增菜单需要绑定后端接口资源（菜单权限 = 资源权限）
+- 资源自动注册（@MenuResource 注解扫描）
+- 资源授权（角色绑定具体资源）
+- 资源路径匹配（菜单 URL → 后端 API 路径）
+
+## 不触发
+- 仅查询菜单 → 用 `meritdata-platform-menu-config`
+- 仅按钮权限（前端显隐）→ 用 `meritdata-platform-permission`
+- 仅数据权限（行/列）→ 用 `meritdata-platform-data-classification`
+
+## 前置约束
+- 资源路径用 Ant 风格（`/api/v1/orders/**`）
+- 资源**必须**用 `@MenuResource` 注解注册
+- 二开资源**必须**走 DAM 授权
+
+## 路由
+- 资源注解 + 注册 → [references/guide.md](references/guide.md)
+- 资源授权 + 路径匹配 → [references/auth-and-path.md](references/auth-and-path.md)
+- 资源扫描 + 缓存 → [references/scan-and-cache.md](references/scan-and-cache.md)
+- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-menu-resource/references/auth-and-path.md

@@ -0,0 +1,166 @@
+# 资源授权与路径匹配（menu-resource）
+
+> 资源授权机制；Ant 路径匹配；多对多绑定。
+
+---
+
+## 1. 资源授权
+
+### 1.1 资源 → 角色（多对多）
+
+```
+order:create  →  ROLE_ADMIN, ROLE_ORDER_MANAGER
+order:delete  →  ROLE_ADMIN
+order:list    →  ROLE_ADMIN, ROLE_ORDER_MANAGER, ROLE_VIEWER
+```
+
+```java
+@PostMapping("/admin/resources/{code}/roles")
+public Result assignRoles(@PathVariable String code, @RequestBody List<String> roleCodes) {
+    resourceService.assignRoles(code, roleCodes);
+    return Result.success();
+}
+```
+
+### 1.2 角色 → 资源
+
+```java
+@PostMapping("/admin/roles/{roleCode}/resources")
+public Result assignResources(@PathVariable String roleCode, @RequestBody List<String> resourceCodes) {
+    resourceService.assignResources(roleCode, resourceCodes);
+    return Result.success();
+}
+```
+
+### 1.3 用户 → 资源（计算）
+
+```java
+public Set<String> userResources(String userId) {
+    Set<String> userRoles = userClient.listRoleCodes(userId);  // 多角色
+    return userRoles.stream()
+        .flatMap(role -> resourceService.resourcesByRole(role).stream())
+        .collect(Collectors.toSet());
+}
+```
+
+## 2. Ant 路径匹配
+
+### 2.1 通配符规则
+
+| 模式 | 含义 | 示例 |
+|------|------|------|
+| `?` | 单字符 | `/orders/?` → `/orders/1` |
+| `*` | 单段任意 | `/orders/*/detail` → `/orders/123/detail` |
+| `**` | 多段任意 | `/orders/**` → `/orders/123/detail/edit` |
+
+### 2.2 用法
+
+```java
+@MenuResource(
+    code = "order:view",
+    path = "/api/v1/orders/**",        // 匹配 /api/v1/orders 下所有路径
+    method = "GET"
+)
+```
+
+### 2.3 路径匹配器
+
+```java
+AntPathMatcher matcher = new AntPathMatcher();
+boolean match = matcher.match("/api/v1/orders/**", "/api/v1/orders/123");
+```
+
+### 2.4 优先级
+
+**精确路径 > 通配路径**：
+
+```
+GET /api/v1/orders/123       精确优先
+GET /api/v1/orders/*         次优
+GET /api/v1/orders/**        最后
+```
+
+## 3. 资源覆盖
+
+### 3.1 场景
+
+```
+order:list   GET  /api/v1/orders/**        → VIEWER 角色
+order:export GET  /api/v1/orders/export    → ADMIN 角色（更严格）
+```
+
+### 3.2 资源覆盖规则
+
+更具体的资源**优先**（精确 > 通配）。
+
+## 4. 资源查询
+
+### 4.1 按用户查资源
+
+```java
+@GetMapping("/resources/current")
+public List<ResourceDTO> currentUserResources() {
+    return resourceService.userResources(SecurityUtils.getCurrentUserId());
+}
+```
+
+### 4.2 按角色查资源
+
+```java
+@GetMapping("/admin/roles/{roleCode}/resources")
+public List<ResourceDTO> roleResources(@PathVariable String roleCode) {
+    return resourceService.resourcesByRole(roleCode);
+}
+```
+
+## 5. 资源校验流程
+
+```
+请求：GET /api/v1/orders/123
+   ↓
+1. 提取 token → userId
+   ↓
+2. 查用户资源（含 roleCode 合并）
+   ↓
+3. 匹配：路径 /api/v1/orders/123 + method GET
+   ↓
+4. 找到匹配资源 → 检查用户资源集合是否包含
+   ↓
+5. 包含 → 放行；不包含 → 403
+```
+
+## 6. ❌ 反模式
+
+### 6.1 ❌ 通配符泛滥
+
+```java
+// ❌ 错
+@MenuResource(code = "admin:all", path = "/**")
+```
+
+✅ 按业务精确到具体接口。
+
+### 6.2 ❌ 资源编码命名不一致
+
+```java
+// ❌ 错：同一个 order:create 在不同模块命名不同
+"order:create"   // 资源编码
+"order.create"   // 另一个资源
+```
+
+✅ 统一编码规则：`模块:动作`。
+
+### 6.3 ❌ 不区分 method
+
+```java
+// ❌ 错：GET 和 POST 都用 order:api
+@MenuResource(code = "order:api", path = "/api/v1/orders")
+```
+
+✅ 按 method 分别注册。
+
+## 7. 关联阅读
+
+- [guide.md](guide.md) — 资源基础
+- [scan-and-cache.md](scan-and-cache.md) — 资源扫描
+- [SKILL.md](../SKILL.md)