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

package/skills/meritdata-platform-lookup-api/references/cache-strategy.md

@@ -0,0 +1,199 @@
+# 字典缓存策略（lookup-api）
+
+> 字典是读多写少，缓存策略至关重要。
+
+---
+
+## 1. 缓存架构
+
+```
+请求 → 查字典
+   ↓
+L1: 本地缓存（Caffeine，5 分钟 TTL）
+   ↓ 未命中
+L2: Redis（30 分钟 TTL）
+   ↓ 未命中
+L3: DB 查 lookup 表
+   ↓
+回填 L2 → L1
+```
+
+## 2. 本地缓存（Caffeine）
+
+### 2.1 配置
+
+```yaml
+lookup:
+  cache:
+    local:
+      enabled: true
+      expire-after-write: 5m     # 写后 5 分钟过期
+      maximum-size: 10000        # 最多 10000 个字典项
+    local-change-invalidate: true  # 字典变更广播到实例 → 清本地缓存
+```
+
+### 2.2 优势
+
+- 读延迟 < 1ms
+- 不占用 Redis 带宽
+- 自动失效（收到广播）
+
+## 3. Redis 缓存
+
+### 3.1 Key 设计
+
+```
+lookup:type:{typeCode}              字典类型的所有项
+lookup:type:{typeCode}:lang:{lang}  多语言
+lookup:item:{typeCode}:{itemCode}   单个字典项
+lookup:tree:{typeCode}              树形字典
+```
+
+### 3.2 TTL 策略
+
+```yaml
+lookup:
+  cache:
+    redis:
+      ttl: 30m
+      random-jitter: 5m    # TTL ± 5 分钟抖动，防止雪崩
+```
+
+## 4. 缓存失效
+
+### 4.1 字典变更广播
+
+```
+管理后台改字典
+   ↓
+平台事件: LookupChangedEvent
+   ↓
+Redis Pub/Sub: lookup:changed:{typeCode}
+   ↓
+所有实例收到 → 清本地缓存 + 删 Redis key
+```
+
+### 4.2 主动失效接口
+
+```java
+public void evictCache(String typeCode) {
+    // 清本地
+    localCache.invalidate(typeCode);
+    // 清 Redis
+    redis.delete("lookup:type:" + typeCode);
+    redis.delete("lookup:tree:" + typeCode);
+}
+```
+
+## 5. 缓存预热
+
+### 5.1 启动加载
+
+```java
+@Component
+public class LookupWarmup implements ApplicationRunner {
+    @Override
+    public void run(ApplicationArguments args) {
+        for (String typeCode : lookupService.listAllTypes()) {
+            lookupService.listByType(typeCode);  // 加载到缓存
+        }
+    }
+}
+```
+
+### 5.2 定时刷新
+
+```java
+@Scheduled(cron = "0 0 * * * ?")  // 每小时
+public void refresh() {
+    for (String typeCode : lookupService.listAllTypes()) {
+        lookupService.evictCache(typeCode);
+        lookupService.listByType(typeCode);  // 重新加载
+    }
+}
+```
+
+## 6. 监控指标
+
+```
+lookup_cache_hit_ratio      缓存命中率
+lookup_cache_local_size     本地缓存大小
+lookup_load_duration_ms     字典加载耗时
+lookup_change_event_total   字典变更事件数
+```
+
+## 7. 字典量大时的策略
+
+### 7.1 问题
+
+某字典有 10 万项 → 缓存大、查询慢。
+
+### 7.2 方案
+
+#### 方案 1：按需加载
+
+```java
+// 不预加载，用到时再加载
+public LookupItem getByCode(String type, String code) {
+    return lookupService.getByCode(type, code);  // 单项加载
+}
+```
+
+#### 方案 2：分页加载
+
+```java
+// 大字典分页查
+public List<LookupItem> listByType(String type, int page, int size) {
+    return lookupService.listPage(type, page, size);
+}
+```
+
+#### 方案 3：字典分类拆分
+
+```
+原本 1 个字典 10 万项
+   ↓
+按业务拆 10 个字典
+   ↓
+每个字典 1 万项
+```
+
+## 8. ❌ 反模式
+
+### 8.1 ❌ 字典无缓存
+
+```java
+// ❌ 错：每次都查 DB
+public LookupItem getByCode(String type, String code) {
+    return lookupRepository.findByCode(type, code);
+}
+```
+
+✅ 加缓存。
+
+### 8.2 ❌ 字典变更不失效缓存
+
+```java
+// ❌ 错：改了字典，缓存不变 → 用户看到旧值
+lookupRepository.update(item);  // 没清缓存
+```
+
+✅ 发广播事件 → 清缓存。
+
+### 8.3 ❌ 缓存无 TTL
+
+```yaml
+# ❌ 错：永久缓存
+lookup:
+  cache:
+    redis:
+      ttl: 99999d
+```
+
+✅ 合理 TTL（30 分钟）+ 变更广播。
+
+## 9. 关联阅读
+
+- [guide.md](guide.md) — 字典基础
+- [tree-and-i18n.md](tree-and-i18n.md) — 树形与多语言
+- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-lookup-api/references/guide.md

@@ -0,0 +1,179 @@
+# 字典 API 基础指南（lookup-api）
+
+> ILookupService 查字典、翻译、缓存。
+
+---
+
+## 1. 核心接口
+
+```java
+@Resource
+private ILookupService lookupService;
+
+// 按类型查字典项
+List<LookupItem> listByType(String type);
+
+// 按 code 查单个字典项
+LookupItem getByCode(String type, String code);
+
+// 把 code 翻译成中文名
+String translate(String type, String code);
+
+// 批量翻译（避免 N+1）
+Map<String, String> translateBatch(String type, List<String> codes);
+```
+
+## 2. 数据模型
+
+```
+LookupType (字典类型)
+   ├── code: ORDER_STATUS       (唯一编码)
+   ├── name: 订单状态
+   ├── description: 描述
+   └── items: [LookupItem]
+
+LookupItem (字典项)
+   ├── code: PAID               (唯一编码)
+   ├── name: 已支付
+   ├── sort: 1
+   ├── enabled: true
+   └── ext: {color: green, ...}  (扩展属性)
+```
+
+## 3. 基本用法
+
+### 3.1 查所有字典项
+
+```java
+@GetMapping("/dict/ORDER_STATUS")
+public List<LookupItem> orderStatus() {
+    return lookupService.listByType("ORDER_STATUS");
+}
+```
+
+响应：
+
+```json
+[
+  {"code": "PENDING", "name": "待支付", "sort": 1},
+  {"code": "PAID", "name": "已支付", "sort": 2},
+  {"code": "SHIPPED", "name": "已发货", "sort": 3}
+]
+```
+
+### 3.2 翻译单个 code
+
+```java
+// "PAID" → "已支付"
+String statusName = lookupService.translate("ORDER_STATUS", "PAID");
+```
+
+### 3.3 批量翻译
+
+```java
+// ❌ 反例：循环翻译（N+1）
+for (OrderDTO order : orders) {
+    String name = lookupService.translate("ORDER_STATUS", order.getStatus());  // N 次查询
+    order.setStatusName(name);
+}
+
+// ✅ 正确：批量翻译
+List<String> codes = orders.stream()
+    .map(OrderDTO::getStatus)
+    .distinct()
+    .collect(Collectors.toList());
+
+Map<String, String> translations = lookupService.translateBatch("ORDER_STATUS", codes);
+
+orders.forEach(order ->
+    order.setStatusName(translations.get(order.getStatus()))
+);
+```
+
+## 4. 在 VO 中使用
+
+### 4.1 @LookupTranslate 注解
+
+```java
+@Data
+public class OrderVO {
+    private String orderNo;
+
+    @LookupTranslate(type = "ORDER_STATUS", source = "status")
+    private String statusName;        // 自动从 status 翻译
+
+    private String status;             // 原始 code
+}
+```
+
+### 4.2 @LookupBatchTranslate（列表场景）
+
+```java
+public class OrderListVO {
+    @LookupBatchTranslate(type = "ORDER_STATUS", sourceField = "statusList")
+    private Map<String, String> statusNameMap;
+}
+```
+
+## 5. 字典管理
+
+### 5.1 后台管理
+
+平台提供字典管理界面：
+
+- 字典类型增删改
+- 字典项增删改
+- 启用/禁用
+- 排序
+- 扩展属性
+
+### 5.2 数据来源
+
+| 来源 | 场景 |
+|------|------|
+| 平台字典 | 通用字典（订单状态、用户类型）|
+| 业务字典 | 业务专属字典（设备类型）|
+| 外部字典 | 同步自外部系统（行政区划）|
+
+## 6. ❌ 反模式
+
+### 6.1 ❌ 二开建自己的字典表
+
+```java
+// ❌ 错：业务库建 t_dict_type 表
+@Entity
+@TableName("t_dict_type")
+public class DictType { ... }
+```
+
+✅ 用平台 lookup 表。
+
+### 6.2 ❌ 循环翻译（N+1）
+
+```java
+// ❌ 错
+for (Order o : orders) {
+    o.setStatusName(lookupService.translate("ORDER_STATUS", o.getStatus()));
+}
+```
+
+✅ `translateBatch`。
+
+### 6.3 ❌ 字典项硬编码
+
+```java
+// ❌ 错
+if ("PAID".equals(order.getStatus())) {
+    return "已支付";
+} else if ("PENDING".equals(order.getStatus())) {
+    return "待支付";
+}
+```
+
+✅ `lookupService.translate`。
+
+## 7. 关联阅读
+
+- [tree-and-i18n.md](tree-and-i18n.md) — 树形字典与多语言
+- [cache-strategy.md](cache-strategy.md) — 字典缓存
+- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-lookup-api/references/tree-and-i18n.md

@@ -0,0 +1,198 @@
+# 树形字典与多语言（lookup-api）
+
+> 行政区划 / 组织树 / 多语言字典项。
+
+---
+
+## 1. 树形字典
+
+### 1.1 场景
+
+- 行政区划（省/市/区/街道）
+- 组织架构（公司/部门/小组）
+- 行业分类（大类/中类/小类）
+
+### 1.2 数据模型
+
+```java
+public class LookupTreeNode {
+    private String code;            // 编码
+    private String name;            // 名称
+    private String parentCode;      // 父级 code
+    private int level;              // 层级
+    private List<LookupTreeNode> children;
+}
+```
+
+### 1.3 查整棵树
+
+```java
+@GetMapping("/dict/REGION/tree")
+public List<LookupTreeNode> regionTree() {
+    return lookupService.listTree("REGION");
+}
+```
+
+### 1.4 查子节点
+
+```java
+@GetMapping("/dict/REGION/children")
+public List<LookupTreeNode> regionChildren(@RequestParam String parentCode) {
+    return lookupService.listChildren("REGION", parentCode);
+}
+```
+
+### 1.5 查祖先链
+
+```java
+// 110105（北京朝阳区）→ [110000, 110100, 110105]
+@GetMapping("/dict/REGION/{code}/ancestors")
+public List<LookupTreeNode> regionAncestors(@PathVariable String code) {
+    return lookupService.listAncestors("REGION", code);
+}
+```
+
+## 2. 多语言字典
+
+### 2.1 场景
+
+国际用户：英文 / 中文 / 日文 不同显示。
+
+### 2.2 数据模型
+
+```sql
+CREATE TABLE t_lookup_item (
+    id BIGINT PRIMARY KEY,
+    type_code VARCHAR(50),
+    item_code VARCHAR(50),
+    name_zh VARCHAR(100),       -- 中文
+    name_en VARCHAR(100),       -- 英文
+    name_ja VARCHAR(100),       -- 日文
+    ...
+);
+```
+
+### 2.3 查询（按语言）
+
+```java
+@GetMapping("/dict/ORDER_STATUS")
+public List<LookupItem> orderStatus(@RequestHeader(defaultValue = "zh") String lang) {
+    return lookupService.listByType("ORDER_STATUS", lang);
+}
+```
+
+```json
+[
+  {"code": "PAID", "name": "已支付", "nameEn": "Paid", "nameJa": "支払い済み"},
+  {"code": "PENDING", "name": "待支付", "nameEn": "Pending", "nameJa": "保留中"}
+]
+```
+
+前端按 `Accept-Language` 自动选择。
+
+### 2.4 默认 fallback
+
+```java
+// zh-CN 查不到 → zh → en（按 fallback chain）
+String name = lookupService.translate("ORDER_STATUS", "PAID", List.of("zh-CN", "zh", "en"));
+```
+
+## 3. 字典变更广播
+
+### 3.1 场景
+
+管理员改了字典 → 所有服务实例缓存失效。
+
+### 3.2 平台机制
+
+平台用 Redis Pub/Sub 广播字典变更：
+
+```
+修改字典
+   ↓
+平台发消息到 Redis 频道: lookup:changed
+   ↓
+所有实例订阅，收到后清缓存
+```
+
+业务代码**无需处理**。
+
+### 3.3 自定义处理
+
+```java
+@EventListener
+public void onLookupChanged(LookupChangedEvent event) {
+    if (event.getTypeCode().equals("ORDER_STATUS")) {
+        // 重新加载
+        loadOrderStatus();
+    }
+}
+```
+
+## 4. 字典导入导出
+
+### 4.1 导入
+
+```java
+@PostMapping("/admin/dict/import")
+public Result importDict(@RequestParam("file") MultipartFile file) {
+    lookupService.importItems(fileType);
+    return Result.success();
+}
+```
+
+### 4.2 导出
+
+```java
+@GetMapping("/admin/dict/export")
+public void export(@RequestParam String typeCode, HttpServletResponse response) {
+    List<LookupItem> items = lookupService.listByType(typeCode);
+    EasyExcel.write(response.getOutputStream(), LookupItem.class).doWrite(items);
+}
+```
+
+## 5. ❌ 反模式
+
+### 5.1 ❌ 树形字典用循环查询
+
+```java
+// ❌ 错：循环查子节点
+public List<LookupTreeNode> getTree(String type) {
+    List<LookupTreeNode> roots = lookupService.listByParent(type, null);
+    for (LookupTreeNode root : roots) {
+        root.setChildren(lookupService.listByParent(type, root.getCode()));  // N 次查询
+        // 递归...
+    }
+}
+```
+
+✅ 一次性查全量 + 内存构树。
+
+```java
+// ✅ 正确
+public List<LookupTreeNode> getTree(String type) {
+    List<LookupTreeNode> all = lookupService.listAll(type);
+    return TreeUtils.buildTree(all, "code", "parentCode");
+}
+```
+
+### 5.2 ❌ 多语言字典存多行
+
+```sql
+-- ❌ 错：每语言一行（关联困难）
+CREATE TABLE t_lookup_item_lang (
+    type_code VARCHAR(50),
+    item_code VARCHAR(50),
+    lang VARCHAR(10),
+    name VARCHAR(100),
+    PRIMARY KEY (type_code, item_code, lang)
+);
+```
+
+✅ 同一行多语言列（横向扩展更简单）。
+
+## 6. 关联阅读
+
+- [guide.md](guide.md) — 字典基础
+- [cache-strategy.md](cache-strategy.md) — 字典缓存
+- [SKILL.md](../SKILL.md)

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

@@ -0,0 +1,42 @@
+---
+name: meritdata-platform-menu-config
+description: |
+  菜单配置。菜单树 / 角色菜单 / 用户菜单 / 菜单权限 / 菜单国际化。
+  触发场景：前端动态菜单 / 角色授权菜单 / 按用户查菜单 / 菜单新增修改 / 菜单排序隐藏。
+  何时不用：按钮级别权限 → 用 meritdata-platform-permission；API 资源权限 → 用 meritdata-platform-menu-resource。
+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-config）
+
+## 触发
+- 前端根据用户权限动态生成菜单
+- 角色授权菜单（管理员给某个角色分配可见菜单）
+- 菜单 CRUD（新增/修改/隐藏/排序）
+- 菜单国际化（多语言菜单名）
+
+## 不触发
+- 按钮权限（页面内 button 显隐）→ 用 `meritdata-platform-permission`
+- API 资源权限（后端接口权限）→ 用 `meritdata-platform-menu-resource`
+- 数据权限（行级/列级）→ 用 `meritdata-platform-data-classification`
+
+## 前置约束
+- 菜单是平台统一管理资源，二开不重写菜单管理
+- 菜单数据走缓存（变更广播清缓存）
+- 二开新增菜单**必须**通过平台后台添加（不在代码里硬编码菜单）
+
+## 路由
+- 菜单查询 + 用户菜单 → [references/guide.md](references/guide.md)
+- 角色授权 + 菜单树构建 → [references/role-and-tree.md](references/role-and-tree.md)
+- 国际化 + 缓存 → [references/i18n-and-cache.md](references/i18n-and-cache.md)
+- [SKILL.md](../SKILL.md)