@alanwang-merit/meritdata-platform-skill-package 1.0.10 → 1.0.12

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

@@ -1,199 +0,0 @@
-# 字典缓存策略（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

@@ -1,179 +0,0 @@
-# 字典 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

@@ -1,198 +0,0 @@
-# 树形字典与多语言（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)