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

package/skills/meritdata-platform-data-access/references/outbound/feign-guide.md

@@ -0,0 +1,229 @@
+# Feign Client 写法指南（feign-guide）
+
+> **铁律**：禁止分页循环逐条 Feign；禁止 `catch + return emptyList` 掩盖 Feign 失败。
+
+---
+
+## 1. Feign Client 定义
+
+### 1.1 基本结构
+
+```java
+@FeignClient(name = "cloud-system-manage", path = "/api/v1")
+public interface UserClient {
+
+    @GetMapping("/users/{id}")
+    ApiResponse<UserDTO> getById(@PathVariable("id") String userId);
+
+    @PostMapping("/users/list-by-ids")
+    ApiResponse<List<UserDTO>> listByIds(@RequestBody List<String> userIds);
+
+    @GetMapping("/users")
+    ApiResponse<PageResult<UserDTO>> page(@SpringQueryMap UserQuery query);
+}
+```
+
+### 1.2 统一响应包装
+
+```java
+public class ApiResponse<T> {
+    private Integer code;       // 200=成功
+    private T data;
+    private String message;
+
+    public T getData() {
+        if (code != 200) {
+            throw new BizException(code, message);
+        }
+        return data;
+    }
+}
+```
+
+---
+
+## 2. 超时配置
+
+### 2.1 application.yml
+
+```yaml
+feign:
+  client:
+    config:
+      default:
+        connectTimeout: 5000        # 连接超时 5s
+        readTimeout: 10000          # 读取超时 10s
+        loggerLevel: BASIC
+      cloud-system-manage:
+        connectTimeout: 3000        # 平台接口快一些
+        readTimeout: 5000
+```
+
+### 2.2 关键约定
+
+| 接口类型 | readTimeout |
+|---------|-------------|
+| 单条查询 | 3-5s |
+| 批量查询（≤100）| 5-10s |
+| 同步推送 | 5-15s |
+| 复杂报表 | 30-60s |
+
+---
+
+## 3. 降级处理
+
+### 3.1 Fallback 类
+
+```java
+@Component
+public class UserClientFallback implements UserClient {
+
+    @Override
+    public ApiResponse<UserDTO> getById(String userId) {
+        // ✅ 降级返回默认值，但**不掩盖**业务异常
+        return ApiResponse.success(UserDTO.builder()
+            .id(userId)
+            .name("用户信息暂不可用")
+            .build());
+    }
+
+    @Override
+    public ApiResponse<List<UserDTO>> listByIds(List<String> userIds) {
+        // ✅ 批量查询降级：返回空集合 + 上抛异常让上游感知
+        log.warn("UserClient.listByIds fallback, userIds={}", userIds);
+        throw new ServiceDegradedException("用户服务降级，请稍后重试");
+    }
+}
+```
+
+### 3.2 ❌ 反例：catch + emptyList 掩盖失败
+
+```java
+// ❌ 错：吞掉异常，返回空集合 → 上游不知道平台故障
+try {
+    return userClient.listByIds(userIds).getData();
+} catch (Exception e) {
+    log.error("Feign failed", e);
+    return Collections.emptyList();
+}
+```
+
+### 3.3 ✅ 正确：明确上抛异常
+
+```java
+public List<UserDTO> listByIdsSafe(List<String> userIds) {
+    try {
+        ApiResponse<List<UserDTO>> resp = userClient.listByIds(userIds);
+        return resp.getData();
+    } catch (FeignException.ServiceUnavailable e) {
+        // 平台服务不可用 → 上抛业务异常
+        throw new ServiceDegradedException("用户服务暂时不可用", e);
+    } catch (FeignException.BadRequest e) {
+        // 参数错误 → 上抛业务异常
+        throw new BizException("请求参数错误：" + e.getMessage(), e);
+    }
+    // 其他异常（超时/网络）由全局异常处理
+}
+```
+
+---
+
+## 4. 请求头传递（用户上下文）
+
+### 4.1 Feign 拦截器
+
+```java
+@Component
+public class FeignUserContextInterceptor implements RequestInterceptor {
+
+    @Override
+    public void apply(RequestTemplate template) {
+        // 传递用户 ID / Token 到下游
+        template.header("X-User-Id", SecurityUtils.getCurrentUserId());
+        template.header("X-Tenant-Id", SecurityUtils.getCurrentTenantId());
+        template.header("Authorization", "Bearer " + SecurityUtils.getCurrentToken());
+    }
+}
+```
+
+### 4.2 ❌ 反例：明文传密码/token 在 URL
+
+```java
+// ❌ 错
+@GetMapping("/users?token={token}")
+UserDTO getById(@PathVariable String id, @PathVariable String token);
+```
+
+---
+
+## 5. 文件上传 / 下载
+
+### 5.1 上传
+
+```java
+@FeignClient(name = "cloud-file")
+public interface FileClient {
+
+    @PostMapping(value = "/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
+    ApiResponse<String> upload(@RequestPart MultipartFile file);
+}
+```
+
+### 5.2 下载（大文件用 ResponseEntity<Resource>）
+
+```java
+@GetMapping("/download/{id}")
+ResponseEntity<Resource> download(@PathVariable String id);
+```
+
+---
+
+## 6. Feign + Hystrix / Sentinel
+
+### 6.1 Sentinel 配置（推荐）
+
+```yaml
+feign:
+  sentinel:
+    enabled: true
+
+spring:
+  cloud:
+    sentinel:
+      transport:
+        dashboard: localhost:8080
+```
+
+### 6.2 资源降级规则
+
+```java
+@SentinelResource(value = "userClient.listByIds", blockHandler = "listByIdsBlockHandler")
+public List<UserDTO> listByIds(List<String> userIds) {
+    return userClient.listByIds(userIds).getData();
+}
+
+public List<UserDTO> listByIdsBlockHandler(List<String> userIds, BlockException ex) {
+    log.warn("UserClient.listByIds blocked, userIds={}, rule={}", userIds, ex.getRule());
+    throw new ServiceDegradedException("用户服务限流");
+}
+```
+
+---
+
+## 7. ❌ 反模式汇总
+
+| 反模式 | 后果 | 正确 |
+|--------|------|------|
+| 循环 `getById` | N+1，性能差 | `listByIds` 批量 |
+| `catch + emptyList` | 掩盖故障 | 显式上抛 |
+| 超时不设置 | 长尾请求拖垮 | 按业务设超时 |
+| URL 传 token | 泄露 + 日志留痕 | Header 传 |
+| Fallback 返 null | NPE | 返默认值或上抛 |
+
+---
+
+## 8. 关联阅读
+
+- [batch-assembly.md](batch-assembly.md) — 批量装配模式
+- [third-party.md](third-party.md) — 第三方接口
+- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-data-access/references/outbound/querydsl-guide.md

@@ -0,0 +1,177 @@
+# QueryDSL Q 类查询指南（querydsl）
+
+> 用于构造动态查询条件，避免 SQL 拼接。Q 类由 APT 自动生成，对应实体类。
+
+---
+
+## 1. 基本用法
+
+### 1.1 注入 JPAQueryFactory
+
+```java
+@Autowired
+private JPAQueryFactory queryFactory;
+```
+
+### 1.2 单表查询
+
+```java
+QOrder q = QOrder.order;
+
+List<Order> orders = queryFactory
+    .selectFrom(q)
+    .where(q.status.eq("PENDING")
+        .and(q.createTime.goe(startTime))
+        .and(q.createTime.loe(endTime)))
+    .orderBy(q.createTime.desc())
+    .offset(page.getOffset())
+    .limit(page.getPageSize())
+    .fetch();
+```
+
+### 1.3 动态条件（BooleanExpression）
+
+```java
+public List<Order> findOrders(OrderQueryParam param) {
+    QOrder q = QOrder.order;
+    return queryFactory.selectFrom(q)
+        .where(
+            eqStatus(param.getStatus()),         // null 时自动跳过
+            geCreateTime(param.getStartTime()),
+            leCreateTime(param.getEndTime()),
+            likeOrderNo(param.getKeyword())
+        )
+        .fetch();
+}
+
+private BooleanExpression eqStatus(String status) {
+    return status == null ? null : QOrder.order.status.eq(status);
+}
+```
+
+**关键**：返回 `null` 时 QueryDSL 会自动跳过该条件。
+
+---
+
+## 2. 关联查询
+
+### 2.1 一对多 + join
+
+```java
+QOrder q = QOrder.order;
+QOrderItem qi = QOrder.orderItem;
+
+List<Order> orders = queryFactory
+    .selectFrom(q)
+    .leftJoin(q.items, qi).fetchJoin()       // fetchJoin 解决 N+1
+    .where(q.id.eq(orderId))
+    .fetch();
+```
+
+### 2.2 多对一（不推荐 join 平台表）
+
+```java
+// ❌ 错：join 平台用户表
+QOrder q = QOrder.order;
+QUserr u = QUser.user;  // 平台实体
+
+List<Order> result = queryFactory
+    .selectFrom(q)
+    .join(u).on(q.applicantUserId.eq(u.id))  // 跨库 JOIN，违反铁律
+    .fetch();
+```
+
+✅ **正确**：用 `UserDTO` + 内存 join（详见 [dto-catalog.md](dto-catalog.md) §3.1）。
+
+---
+
+## 3. 投影（DTO 直接接收）
+
+### 3.1 使用 Projections
+
+```java
+QOrder q = QOrder.order;
+
+List<OrderVO> vos = queryFactory
+    .select(Projections.constructor(OrderVO.class,
+        q.id, q.orderNo, q.status, q.createTime))
+    .from(q)
+    .where(q.status.eq("PENDING"))
+    .fetch();
+```
+
+### 3.2 使用 @QueryProjection（需要 DTO 加注解）
+
+```java
+public class OrderVO {
+    private Long id;
+    private String orderNo;
+    private String status;
+
+    @QueryProjection
+    public OrderVO(Long id, String orderNo, String status) {
+        this.id = id;
+        this.orderNo = orderNo;
+        this.status = status;
+    }
+}
+
+// APT 自动生成 QOrderVO
+List<OrderVO> vos = queryFactory
+    .select(new QOrderVO(q.id, q.orderNo, q.status))
+    .from(q)
+    .fetch();
+```
+
+---
+
+## 4. 聚合 / 分组
+
+```java
+QOrder q = QOrder.order;
+
+List<Tuple> result = queryFactory
+    .select(q.applicantUserId, q.count(), q.amount.sum())
+    .from(q)
+    .groupBy(q.applicantUserId)
+    .having(q.count().gt(5L))
+    .fetch();
+```
+
+---
+
+## 5. ❌ 反模式
+
+### 5.1 拼接 SQL 字符串
+
+```java
+// ❌ 错
+String sql = "SELECT * FROM t_order WHERE status = '" + status + "'";
+em.createNativeQuery(sql).getResultList();
+```
+
+### 5.2 在 Q 查询里混入平台实体
+
+```java
+// ❌ 错：QueryDSL 关联到平台 Q 类
+QUser qu = QUser.user;
+queryFactory.selectFrom(q).join(qu).on(...);
+```
+
+### 5.3 用 Q 类做删除/更新（业务代码）
+
+```java
+// ❌ 错：Q 类 delete 会绕过 @SQLDelete 软删除
+queryFactory.delete(q).where(q.id.eq(id)).execute();
+
+// ✅ 正确：走 Repository 自定义方法（保留软删除）
+orderRepository.softDeleteById(id);
+```
+
+---
+
+## 6. 关联阅读
+
+- [dto-catalog.md](dto-catalog.md) — 平台 DTO 清单
+- [dto-converter.md](dto-converter.md) — DTO 转换工具
+- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-data-access/references/outbound/same-jvm-detection.md

@@ -0,0 +1,157 @@
+# 同 JVM 判定方法（same-jvm-detection）
+
+> **核心问题**：哪些场景允许直接 `@Autowired IUserService`？哪些必须走 Feign？
+
+---
+
+## 1. 判定流程
+
+```
+你的二开模块是独立部署的 Spring Boot 应用？
+  ├─ YES → 必须 Feign，用 integration
+  └─ NO（与平台同 Spring Boot 应用）
+       └─ 检查 pom 是否引入 cloud-system-manage-module
+            ├─ YES → 同 JVM，可用 services
+            └─ NO → 不属于同 JVM，必须 Feign
+```
+
+---
+
+## 2. pom 判定（关键）
+
+### 2.1 检查当前模块的 pom
+
+```bash
+grep -A 2 "cloud-system-manage" pom.xml
+```
+
+### 2.2 ✅ 同 JVM 的标志
+
+```xml
+<dependency>
+    <groupId>com.meritdata.cloud</groupId>
+    <artifactId>cloud-system-manage-module</artifactId>
+    <version>${platform.version}</version>
+</dependency>
+```
+
+**注意**：
+- 版本必须与平台主版本一致（不能跨大版本混用）
+- 不能用 `provided` 作用域（必须 runtime 可用）
+
+### 2.3 ❌ 非同 JVM 的标志
+
+```xml
+<!-- 独立部署的二开服务 -->
+<dependency>
+    <groupId>com.meritdata.cloud</groupId>
+    <artifactId>cloud-system-manage-client</artifactId>  <!-- 只有 client，没有 module -->
+    <version>${platform.version}</version>
+</dependency>
+```
+
+`cloud-system-manage-client` 是 Feign Client 封装包，**不等于同 JVM**。
+
+---
+
+## 3. 部署形态判定
+
+### 3.1 同 JVM 部署形态
+
+```
+[Spring Boot App]
+  ├── cloud-system-manage-module（平台模块）
+  ├── your-2nd-module（你的二开模块）
+  └── cloud-other-modules
+```
+
+**特征**：
+- 一个进程（一个 java -jar）
+- 一个 application.yml
+- 共享 Spring 容器（@Autowired 跨模块可见）
+
+### 3.2 独立部署形态
+
+```
+[App A: cloud-system-manage]   ← 平台
+[App B: your-2nd-service]      ← 你的二开（独立服务）
+       ↓ Feign / HTTP
+```
+
+**特征**：
+- 两个进程
+- 两个 application.yml
+- 不共享 Spring 容器
+
+---
+
+## 4. 误判的后果
+
+### 4.1 非同 JVM 用 @Autowired IUserService
+
+**启动失败**：
+```
+***************************
+APPLICATION FAILED TO START
+***************************
+
+Parameter 0 of constructor in com.xxx.OrderService required a bean of type
+'com.meritdata.cloud.platform.service.IUserService' that could not be found.
+```
+
+### 4.2 同 JVM 用 Feign 调自己
+
+**性能浪费**：本地方法调用被包成 HTTP 请求，徒增 10-100ms 延迟。
+
+---
+
+## 5. 灰度场景：部分同 JVM
+
+### 5.1 场景描述
+
+二开模块 A 与平台同 JVM，二开模块 B 独立部署。
+
+### 5.2 处理方式
+
+| 模块 | 部署 | 用什么 |
+|------|------|--------|
+| A | 与平台同 JVM | 直接 @Autowired IUserService |
+| B | 独立部署 | Feign Client |
+
+### 5.3 共享代码怎么写
+
+业务代码（如 OrderService）不知道自己在哪个部署形态。**推荐**：
+
+```java
+// 二开代码统一通过 Feign 调，Feign 在同 JVM 时走本地实现
+@FeignClient(name = "cloud-system-manage", fallback = LocalUserServiceImpl.class)
+public interface UserClient {
+    @GetMapping("/api/v1/users/{id}")
+    UserDTO getById(@PathVariable String id);
+}
+
+// 同 JVM 时，Spring Cloud LoadBalancer 优先走本地 Bean
+// 独立部署时，走 HTTP
+```
+
+---
+
+## 6. 判定清单
+
+在写 `@Autowired IUserService` 之前，回答：
+
+- [ ] 我的二开模块是独立 Spring Boot 应用？（NO 才能继续）
+- [ ] pom 引入了 `cloud-system-manage-module`（不是 client）？
+- [ ] 部署时与平台同进程？
+- [ ] 与平台版本一致？
+
+**4 个都是 YES → 同 JVM，可直接注入**
+**任何一项 NO → 必须 Feign，用 `meritdata-platform-integration`**
+
+---
+
+## 7. 关联阅读
+
+- [service-catalog.md](service-catalog.md) — 平台 Service 清单
+- [usage-patterns.md](usage-patterns.md) — 典型用法
+- [SKILL.md](../SKILL.md)