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

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

@@ -1,164 +0,0 @@
-# 菜单配置基础指南（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

@@ -1,180 +0,0 @@
-# 菜单国际化与缓存（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

@@ -1,170 +0,0 @@
-# 角色授权与菜单树构建（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

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

@@ -1,166 +0,0 @@
-# 资源授权与路径匹配（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)