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

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

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

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

@@ -1,157 +0,0 @@
-# 同 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)