@nebula-skills/nebula-code-standards 0.1.0

package/skill/framework-standards.md

@@ -0,0 +1,610 @@
+# 框架工具使用规范
+
+> 本文档来源于真实开发过程中发现的问题，归纳为规范沉淀。适用于所有基于 Nebula 框架的业务开发与框架扩展工作。
+
+---
+
+## 一、框架工具类优先使用原则
+
+**核心原则：Nebula 已封装的工具，禁止绕过直接使用底层开源 API。**
+
+Nebula 对常用基础能力做了统一封装，封装目的是：
+1. 保证配置一致性（如 Jackson 的日期格式、时区等）
+2. 统一错误处理和日志输出
+3. 屏蔽第三方 API 变更影响
+
+---
+
+## 二、JSON 工具：必须使用 `JsonUtils`
+
+**模块：** `nebula-framework-core`  
+**类名：** `com.huida.nebula.core.json.JsonUtils`
+
+### ✅ 正确用法
+
+```java
+// 对象 → JSON 字符串
+String json = JsonUtils.toJsonString(obj);
+
+// JSON 字符串 → 对象
+MyParam param = JsonUtils.parseObject(json, MyParam.class);
+
+// JSON 字符串 → List
+List<MyParam> list = JsonUtils.parseArray(json, MyParam.class);
+
+// 需要个性化配置时，获取全局单例
+ObjectMapper mapper = JsonUtils.getObjectMapper();
+```
+
+### ❌ 禁止用法
+
+```java
+// 禁止：每次 new 一个 ObjectMapper，配置不一致（日期格式、模块等会缺失）
+new ObjectMapper().readValue(json, MyClass.class);
+new ObjectMapper().writeValueAsString(obj);
+```
+
+### 适用场景
+
+| 场景 | 用法 |
+|------|------|
+| 任务参数 JSON 反序列化 | `JsonUtils.parseObject(ctx.getRawParams(), XxxParam.class)` |
+| 外部 API 响应解析 | `JsonUtils.parseObject(responseBody, ResultDTO.class)` |
+| 日志打印对象 | `JsonUtils.toJsonStringOrEmpty(obj)`（静默模式，不抛异常） |
+| Spring 注入 `ObjectMapper` | 可通过 Bean 注入，但不允许 `new ObjectMapper()` |
+
+---
+
+## 三、分布式锁：优先使用 `NebulaLockHelper` 或 `RedissonClient`
+
+**模块：** `nebula-boot-starter-redis`  
+**类名：** `com.huida.nebula.boot.autoconfigure.redis.NebulaLockHelper`
+
+### ✅ 正确用法
+
+```java
+// 方式一：tryLock + Runnable（推荐，自动释放，抢不到直接返回 false）
+boolean success = lockHelper.tryLock("order:create:" + orderId, () -> {
+    orderService.create(dto);
+});
+
+// 方式二：tryLock + Supplier（有返回值）
+String result = lockHelper.tryLock("pay:" + payId, () -> payService.execute(payId));
+
+// 方式三：框架层（无法注入 Starter 层时）直接使用 RedissonClient
+RLock lock = redissonClient.getLock("nebula:schedule:lock:" + taskCode);
+boolean acquired = lock.tryLock(0, lockTimeoutSeconds, TimeUnit.SECONDS);
+try {
+    if (acquired) { /* 执行任务 */ }
+} finally {
+    if (acquired && lock.isHeldByCurrentThread()) lock.unlock();
+}
+```
+
+### ❌ 禁止用法
+
+```java
+// 禁止：StringRedisTemplate.setIfAbsent 实现分布式锁
+// 问题：释放时需手动 delete，有误删他人锁的风险；非原子性操作
+Boolean locked = redisTemplate.opsForValue()
+        .setIfAbsent(lockKey, "1", Duration.ofSeconds(timeout));
+// ...
+redisTemplate.delete(lockKey); // 可能误删其他节点的锁！
+```
+
+### 选型说明
+
+| 场景 | 推荐方案 |
+|------|---------|
+| 业务层（Service）防重入 | `NebulaLockHelper.tryLock()` |
+| 定时任务多节点互斥 | `RedissonClient.getLock().tryLock(waitTime=0, leaseTime=N)` |
+| 声明式锁（方法级） | `@DistributedLock`（AOP 切面，由 `nebula-boot-starter-redis` 提供） |
+
+> **架构约束：** `NebulaLockHelper` 在 Starter 层，Framework 层模块（如 `nebula-framework-task`）不可反向依赖 Starter 层。Framework 层需要分布式锁时，直接注入 `RedissonClient`（以 `compileOnly` 形式声明依赖）。
+
+---
+
+## 三-B、Redis 缓存工具：`NebulaCacheHelper`
+
+**模块：** `nebula-boot-starter-redis`  
+**类名：** `com.huida.nebula.boot.autoconfigure.redis.NebulaCacheHelper`
+
+### ✅ 正确用法
+
+```java
+// 存对象（自动 JSON 序列化 + Key 前缀）
+cacheHelper.set("file:meta:" + fileId, metaDO, Duration.ofHours(24));
+
+// 取对象
+FileMetaDO meta = cacheHelper.get("file:meta:" + fileId, FileMetaDO.class);
+
+// 取泛型集合
+List<FileMetaDO> list = cacheHelper.get("file:list", new TypeReference<List<FileMetaDO>>(){});
+
+// Hash 字段操作
+cacheHelper.hashSet("mpart:" + uploadId + ":etags", partNumber, etag);
+String etag = cacheHelper.hashGet("mpart:" + uploadId + ":etags", "1");
+
+// Set 操作
+cacheHelper.setAdd("mpart:" + uploadId + ":parts", String.valueOf(partNumber));
+Set<String> parts = cacheHelper.setMembers("mpart:" + uploadId + ":parts");
+
+// 过期时间
+cacheHelper.expire("mpart:" + uploadId + ":parts", Duration.ofHours(24));
+
+// 删除多个 Key
+cacheHelper.deleteAll(List.of("key1", "key2", "key3"));
+```
+
+### ⚠️ `NebulaCacheHelper` 没有 `hashGetAll` 方法
+
+当需要读取整个 Hash（所有字段）时，**不要**切换回 `StringRedisTemplate`，而是改用 JSON 字符串存储：
+
+```java
+// ❌ 错误：为了 hashGetAll 降级回 StringRedisTemplate
+Map<String, String> all = stringRedisTemplate.opsForHash().entries(key); // 违反工具封装规范
+
+// ✅ 正确：整体读写的对象改用 JSON 字符串存储
+// 写：
+cacheHelper.set("mpart:" + uploadId + ":meta", metaMap, Duration.ofHours(24));
+// 读：
+Map<String, String> meta = cacheHelper.get("mpart:" + uploadId + ":meta",
+                                            new TypeReference<Map<String, String>>(){});
+```
+
+### ❌ 禁止直接使用 `StringRedisTemplate`
+
+```java
+// 禁止：绕过 NebulaCacheHelper 直接用 StringRedisTemplate
+stringRedisTemplate.opsForHash().putAll(key, map);
+stringRedisTemplate.opsForSet().add(key, values);
+```
+
+---
+
+## 三-C、跨服务 RPC 接口开发规范（三件套）
+
+微服务之间通过 Feign 调用时，必须按以下「三件套」模式实现，**参考 `nebula-system` 的 `IdGenRpcService` + `SystemConstants`**：
+
+### 三件套组成
+
+| 组件 | 位置 | 作用 |
+|------|------|------|
+| `{域}Constants` | `{业务模块}-api` 的 `constant/` | 统一维护服务名、RPC URI 前缀、业务常量 |
+| `I{业务名}RpcService`（Feign Client） | `{业务模块}-api` 的 `provider/` | 调用方只依赖此接口，`primary = false` 避免 LocalStub 冲突 |
+| `{业务名}RpcServiceLocalStub` | `{业务模块}-core` 的 `feign/local/` | 聚合部署时 `@Primary` 短路，直接调用本地 Service |
+
+### `{域}Constants` 规范
+
+```java
+// 位置：{业务模块}-api/.../api/constant/{域名}Constants.java
+public final class FsmConstants {
+    private FsmConstants() {}
+
+    /** 服务名（Feign Client name + Nacos 注册名） */
+    public static final String SERVICE_NAME = "nebula-fsm";
+
+    /** RPC 路径前缀：CommonConstants.RPC_URI_PREFIX + "/{业务域路径}" */
+    public static final String URI_PREFIX = CommonConstants.RPC_URI_PREFIX + "/nebula/fsm";
+
+    // 业务枚举值（调用方也可能需要判断，所以放在 api 模块）
+    public static final String ACCESS_POLICY_PUBLIC  = "PUBLIC";
+    public static final String ACCESS_POLICY_PRIVATE = "PRIVATE";
+    public static final String UPLOAD_STATUS_COMPLETE  = "COMPLETE";
+}
+```
+
+### Feign Client 接口规范
+
+```java
+// 位置：{业务模块}-api/.../api/provider/I{业务名}RpcService.java
+@FeignClient(
+    name = FsmConstants.SERVICE_NAME,
+    path = FsmConstants.URI_PREFIX + "/file",
+    primary = false   // 必须，避免 LocalStub(@Primary) 与 Feign 代理冲突
+)
+public interface IFileRpcService {
+    @GetMapping("/{id}")
+    R<FileMetaDTO> getFileMeta(@PathVariable("id") Long id);
+
+    @PostMapping("/batch")
+    R<List<FileMetaDTO>> batchGetFileMeta(@RequestBody List<Long> ids);
+}
+```
+
+### RPC Controller 规范
+
+```java
+// 位置：{业务模块}-core/.../controller/{业务名}RpcController.java
+@Hidden                            // 隐藏在 Swagger 文档中，仅供内部调用
+@RestController
+@RequestMapping(FsmConstants.URI_PREFIX + "/file")  // 与 Feign Client path 一致
+@RequiredArgsConstructor
+public class FileRpcController implements IFileRpcService {
+    private final ISysFileMetaService fileMetaService;
+    // 实现接口方法...
+}
+```
+
+### LocalStub（聚合部署短路）规范
+
+```java
+// 位置：{业务模块}-core/.../feign/local/{业务名}RpcServiceLocalStub.java
+@Slf4j
+@Primary       // 聚合部署时优先于 Feign HTTP 代理
+@Component
+@RequiredArgsConstructor
+public class FileRpcServiceLocalStub implements IFileRpcService {
+    private final ISysFileMetaService fileMetaService;  // 直接调用本地 Service
+
+    @Override
+    public R<FileMetaDTO> getFileMeta(Long id) {
+        log.debug("[LocalStub] getFileMeta id={}", id);
+        return R.ok(SysFileMetaConvert.INSTANCE.doToDTO(fileMetaService.getByIdOrThrow(id)));
+    }
+}
+```
+
+### 部署模式说明
+
+| 部署模式 | 生效 Bean | 调用链路 |
+|---------|---------|---------|
+| 聚合部署（同 JVM） | `LocalStub`（`@Primary`） | 业务调用 → LocalStub → 本地 Service |
+| 独立部署（不同 JVM） | Feign HTTP 代理 | 业务调用 → Feign Client → HTTP → RPC Controller → Service |
+
+> 调用方只需要依赖 `{业务模块}-api`（含 Feign 接口和 LocalStub），无需关心部署模式。
+
+---
+
+## 三-D、多表联动 Service 协作规范
+
+当一次业务操作需要同时写入多张表（如文件物理层 `sys_file_content` + 业务引用层 `sys_file_meta`），必须遵循以下规范：
+
+### 通过 Service 接口协作，禁止跨模块注入 Mapper
+
+```java
+// ✅ 正确：通过对方 Service 接口完成跨表写入
+@RequiredArgsConstructor
+public class ExcelFileAccessorImpl implements ExcelFileAccessor {
+    private final ISysFileMetaService  fileMetaService;    // 注入 Service 接口
+    private final ISysFileContentService fileContentService; // 注入 Service 接口
+
+    public Long upload(File file, String originalName) {
+        // ...
+        fileContentService.save(contentDO);  // 通过 Service
+        fileMetaService.save(metaDO);        // 通过 Service
+        return metaDO.getId();
+    }
+}
+
+// ❌ 错误：绕过 Service 直接注入另一业务域的 Mapper
+@RequiredArgsConstructor
+public class ExcelFileAccessorImpl implements ExcelFileAccessor {
+    private final SysFileMetaMapper  fileMetaMapper;     // 直接注入 Mapper ❌
+    private final SysFileContentMapper fileContentMapper; // 直接注入 Mapper ❌
+}
+```
+
+### 跨表写操作的事务边界
+
+多表写操作必须放在同一个 `@Transactional` 方法内，且事务方法归属于**调用链最顶端的 Service**，不在 Impl 之间重复嵌套事务：
+
+```java
+// ✅ 正确：事务边界在调用者的 Service 方法上
+@Transactional(rollbackFor = Exception.class)
+public FileMetaRespVO upload(MultipartFile file, ...) {
+    // 1. 写物理文件记录
+    fileContentService.save(contentDO);           // 不需要事务注解（参与外层事务）
+    // 2. 写业务引用记录
+    save(metaDO);                                  // 同上
+    // 3. 原子递增引用计数
+    fileContentService.incrementRefCount(contentId);
+    return vo;
+}
+```
+
+### 引用计数 + 延迟删除模式（防误删共享资源）
+
+当多条业务记录可能指向同一物理资源时，使用引用计数 + 延迟删除模式，保证任何一方删除自身记录时不影响其他引用方：
+
+```
+删除业务记录时：
+  1. 软删除业务引用记录（delete_flag = 1）
+  2. 物理资源 ref_count - 1（原子 SQL：ref_count = GREATEST(ref_count - 1, 0)）
+  3. ref_count 降为 0 时：同步标记 storage_status = PENDING_DELETE
+  4. 后台清理任务定期扫描 storage_status = PENDING_DELETE 的记录，执行真正的物理删除
+```
+
+> **核心原则**：物理资源的真实删除必须异步延迟执行，不在同步删除链路中完成，避免事务过长和误删。
+
+---
+
+## 三-E、日志与链路追踪规范
+
+### 1. 日志框架：Log4j2（不是 Logback）
+
+Nebula 服务端使用 **Log4j2**，配置文件通过 `logging.config` 指定：
+
+```yaml
+# application-dev.yaml
+logging:
+  config: classpath:log4j/log4j2-dev.xml
+```
+
+**Log4j2 与 Logback 的关键语法差异（混淆会导致字段无值）：**
+
+| 功能 | ❌ Logback 写法 | ✅ Log4j2 写法 |
+|------|---------------|--------------|
+| MDC 取值（无默认值） | `%X{traceId:-}` | `%X{traceId}` |
+| MDC 取值（有默认值） | `%X{traceId:-unknown}` | `%X{traceId}{unknown}` |
+| 进程 ID | `${PID}` | `%processId` |
+
+> **典型错误**：`%X{traceId:-}` 在 Log4j2 中，`traceId:-` 整体被当作 Key 名查找，永远为空。正确写法是 `%X{traceId}`。
+
+> **`${PID}` 无值原因**：`${PID}` 是 Spring Boot 的占位符，只有 Spring 处理日志配置时才生效。独立加载的 Log4j2 XML 无法解析，必须改用 Log4j2 原生的 `%processId`。
+
+### 2. 多环境日志配置规范
+
+每个服务维护三份 Log4j2 配置，放在 `src/main/resources/log4j/` 目录：
+
+| 文件 | 环境 | 特点 |
+|------|------|------|
+| `log4j2-dev.xml` | 本地开发 | 仅控制台，带 ANSI 颜色，业务包 DEBUG，响应体截断 2000 字符 |
+| `log4j2-uat.xml` | UAT | 控制台 + 文本文件 + ELK JSON 文件，异步写入 |
+| `log4j2-prod.xml` | 生产 | 控制台仅 WARN+，文本文件 + ELK JSON 文件 + 独立 ERROR 文件，关闭 SQL 日志 |
+
+各环境 profile YAML 中分别指定对应配置（`application-dev.yaml`、`application-uat.yaml`、`application-prod.yaml`）。
+
+### 3. 标准日志格式
+
+控制台/文本文件（Log4j2 语法）：
+
+```
+%d{yyyy-MM-dd HH:mm:ss.SSS} [%X{traceId}] [%5p] %processId --- [%15.15t] %-50.50c{1.} : %m%n%xEx
+```
+
+关键占位符说明：
+
+- `%X{traceId}` —— MDC 中的链路追踪 ID（由 TraceFilter/ScheduledTraceAspect/TraceConsumerContextSetup 写入）
+- `%processId` —— 进程 ID（Log4j2 原生，不依赖 Spring）
+- `%-50.50c{1.}` —— Logger 名缩写（包路径首字母，类名/方法名保留全名），固定宽度 50 字符
+
+ELK JSON 格式遵循 ECS（Elastic Common Schema），字段命名：`@timestamp`、`log.level`、`trace.id`、`tenant.code`、`service.name`、`message`、`error.stack`。
+
+### 4. traceId 链路追踪覆盖规范
+
+Nebula 框架已自动处理三种场景的 traceId 注入，**业务代码无需手动操作**，前提是引入 `nebula-boot-starter-trace`：
+
+| 执行场景 | 处理机制 | traceId 来源 |
+|---------|---------|------------|
+| HTTP 请求 | `TraceFilter`（自动注册） | 上游 Header 透传，或本服务新生成（链路起点） |
+| `@Scheduled` 定时任务 | `ScheduledTraceAspect`（自动注册，需 AOP） | 每次触发生成全新 traceId（独立链路起点） |
+| RocketMQ 消费 | `TraceConsumerContextSetup`（自动注册） | 消息 Header（Producer 透传），无 Header 时自动生成 |
+| 异步线程池 | `TraceTaskDecorator`（注入线程池） | 从父线程 MDC 快照传播 |
+
+**引入步骤（一次性配置）：**
+
+```groovy
+// build.gradle（{服务}-starter 模块）
+implementation "com.huida.nebula.boot:nebula-boot-starter-trace:${nebulaBootVersion}"
+```
+
+**不需要做：**
+
+- ❌ 不需要在 Controller、Service、MQ Listener 中手动 `MDC.put("traceId", ...)`
+- ❌ 不需要在 `@Scheduled` 方法内手动生成 traceId
+- ❌ 不需要在线程池的 `Runnable` 中手动传递 MDC
+
+### 5. `R<T>` 响应体自动携带 traceId
+
+`R.ok()` / `R.fail()` 的构造器内部通过 `MDC.get("traceId")` 自动注入，**调用方无需任何额外操作**：
+
+```json
+// 每个接口响应自动包含 traceId
+{
+  "code": 0,
+  "message": "操作成功",
+  "traceId": "2036344300517855232",
+  "data": { ... }
+}
+```
+
+**实现原理**：Controller 方法调用 `R.ok(data)` 时，`TraceFilter` 已将 traceId 写入 MDC（同一线程），构造器读取时必然有值。
+
+**为什么用 `MDC.get()` 而非 `TraceContextHolder.getTraceId()`**：
+
+`R` 类位于 `nebula-framework-core`（纯 Java 工具层，不引入 Spring），`TraceContextHolder` 位于 `nebula-framework-trace`，引入会产生循环依赖风险。`slf4j-api` 已是 `nebula-framework-core` 现有依赖，通过 `MDC.get()` 读取效果完全等价。
+
+---
+
+## 四、模块分层依赖规则
+
+Nebula 框架的模块分为 4 层，**禁止逆向依赖**：
+
+```
+nebula-boot-project/
+├── nebula-framework-*     # 框架层：核心能力抽象，不依赖 Starter 层
+│   ├── nebula-framework-core
+│   ├── nebula-framework-task
+│   ├── nebula-framework-excel
+│   └── nebula-framework-file
+└── nebula-starters/
+    ├── nebula-boot-starter-*  # Starter 层：自动配置，可依赖 Framework 层
+    │   ├── nebula-boot-starter-redis   （含 NebulaLockHelper、NebulaCacheHelper）
+    │   ├── nebula-boot-starter-task
+    │   └── nebula-boot-starter-excel
+```
+
+| 依赖方向 | 是否允许 |
+|---------|---------|
+| Framework 层 → Framework 层 | ✅ |
+| Starter 层 → Framework 层 | ✅ |
+| Framework 层 → Starter 层 | ❌ 禁止（循环依赖风险） |
+| 业务模块 → Starter 层 | ✅（通过 `api` 传递依赖） |
+
+**Framework 层依赖可选中间件的正确方式：**
+
+```groovy
+// build.gradle：使用 compileOnly，运行时由 Starter 层/业务方提供
+compileOnly 'org.redisson:redisson-spring-boot-starter'
+compileOnly 'com.lmax:disruptor'
+compileOnly 'org.apache.rocketmq:rocketmq-spring-boot-starter'
+```
+
+---
+
+## 五、第三方依赖版本管理规范
+
+**所有第三方依赖的版本号必须在 `nebula-support-dependencies` 的 BOM 中统一管理，业务模块和框架模块不写死版本号。**
+
+### 版本声明位置
+
+| 文件 | 作用 |
+|------|------|
+| `nebula-support/gradle.properties` | 定义版本变量（如 `easyexcelVersion=4.0.3`） |
+| `nebula-support/nebula-support-dependencies/build.gradle` | 在 `constraints` 块中声明 `api "groupId:artifactId:${version}"` |
+
+### ✅ 正确用法
+
+```groovy
+// nebula-support/gradle.properties
+easyexcelVersion=4.0.3
+minioVersion=8.5.17
+disruptorVersion=4.0.0
+
+// nebula-support-dependencies/build.gradle（constraints 块内）
+api "com.alibaba:easyexcel:${easyexcelVersion}"
+api "io.minio:minio:${minioVersion}"
+api "com.lmax:disruptor:${disruptorVersion}"
+
+// 业务模块/框架模块 build.gradle（不写版本号，从 BOM 继承）
+api 'com.alibaba:easyexcel'
+compileOnly 'io.minio:minio'
+```
+
+### ❌ 禁止用法
+
+```groovy
+// 禁止：在模块 build.gradle 中硬编码版本号
+implementation 'com.alibaba:easyexcel:3.3.2'
+```
+
+### 当前已管理的新增依赖
+
+| 分类 | 依赖 | 版本变量 |
+|------|------|---------|
+| Excel | `com.alibaba:easyexcel` | `easyexcelVersion` |
+| 文件存储 | `io.minio:minio` | `minioVersion` |
+| 文件存储 | `com.aliyun.oss:aliyun-sdk-oss` | `aliyunOssVersion` |
+| 文件存储 | `com.qcloud:cos_api` | `tencentCosVersion` |
+| 文件存储 | `com.huaweicloud:esdk-obs-java-bundle` | `huaweiObsVersion` |
+| 文件存储 | `com.qiniu:qiniu-java-sdk` | `qiniuSdkVersion` |
+| 文件存储 | `software.amazon.awssdk:s3` | `awsS3Version` |
+| 并发 | `com.lmax:disruptor` | `disruptorVersion` |
+
+---
+
+## 六、包结构与文件放置规范
+
+### Service 实现类必须在 `service/impl/` 目录
+
+| 类型 | 正确位置 | 错误位置 |
+|------|---------|---------|
+| Service 接口 | `service/I{业务名}Service.java` | — |
+| Service 实现 | `service/impl/{业务名}ServiceImpl.java` | `service/{业务名}ServiceImpl.java` ❌ |
+| SPI 实现类 | `service/impl/{SPI名}Impl.java` | `service/{SPI名}Impl.java` ❌ |
+
+> **典型错误：** `ExcelTemplateRegistryImpl` 实现了框架 SPI `ExcelTemplateRegistry`，应放在 `service/impl/` 目录，而不是与接口平级的 `service/` 目录。
+
+### 泛型参数数量必须匹配接口定义
+
+```java
+// TaskHandler<P> 只有 1 个泛型参数
+// ✅ 正确
+Map<String, TaskHandler<?>> registry;
+List<TaskHandler<?>> handlers;
+public <P> TaskHandler<P> get(String taskCode) { ... }
+
+// ❌ 错误：写成了 2 个泛型参数
+Map<String, TaskHandler<?, ?>> registry;
+public <P, R> TaskHandler<P, R> get(String taskCode) { ... }
+```
+
+---
+
+## 七、框架工具速查表
+
+| 需求 | 禁止用法 | Nebula 推荐工具 | 模块 |
+|------|---------|---------------|------|
+| JSON 序列化/反序列化 | `new ObjectMapper()` | `JsonUtils` | `nebula-framework-core` |
+| 分布式锁（业务层） | `StringRedisTemplate.setIfAbsent` | `NebulaLockHelper` | `nebula-boot-starter-redis` |
+| 分布式锁（框架层） | `StringRedisTemplate.setIfAbsent` | `RedissonClient.getLock()` | `redisson`（compileOnly） |
+| 声明式分布式锁 | 手动加锁逻辑 | `@DistributedLock` | `nebula-boot-starter-redis` |
+| Redis 读写（业务层） | `StringRedisTemplate.opsForXxx()` | `NebulaCacheHelper` | `nebula-boot-starter-redis` |
+| 多租户动态条件查询 | `@Select` 注解（绕过拦截器） | `MapperExt` + `LambdaQueryWrapper` | `nebula-framework-mybatis` |
+| 文件流复制 | 手动 `byte[]` buffer 循环 | `StreamUtils.copy(in, out)` | `spring-core` |
+| 系统级异常（IO/外部调用） | `throw new RuntimeException` | `SystemException(GlobalErrorCode.INTERNAL_SERVER_ERROR, ...)` | `nebula-framework-core` |
+| 业务校验异常 | `throw new RuntimeException` | `BusinessException(GlobalErrorCode...)` | `nebula-framework-core` |
+| 查询不存在时抛异常 | 手动 `if(obj == null) throw...` | `getByIdOrThrow(id)` | `BaseServiceImpl` |
+| HTTP 响应包装 | 直接返回裸对象 | `R.ok(data)` / `R.ok()` | `nebula-framework-core` |
+| 日志打印 | `System.out.println` | `@Slf4j` + `log.info/warn/error` | Lombok |
+| 跨服务 RPC | 直接 Feign 无 LocalStub | Constants + `@FeignClient(primary=false)` + LocalStub | `{业务模块}-api/core` |
+
+---
+
+## 八、代码审查检查清单（扩展）
+
+> 是对「十三、新业务模块开发检查清单」的补充，专注于框架合规性。
+
+### 依赖与工具使用
+
+- [ ] JSON 操作是否全部使用 `JsonUtils`（不存在 `new ObjectMapper()`）
+- [ ] 分布式锁是否使用 `NebulaLockHelper` 或 `RedissonClient`（不使用 `StringRedisTemplate.setIfAbsent`）
+- [ ] Redis 操作是否使用 `NebulaCacheHelper`（不直接使用 `StringRedisTemplate`）
+- [ ] 需要读取整个 Hash 时，是否改为 JSON 字符串存储（避开 `hashGetAll` 缺口）
+- [ ] 新增三方依赖是否已在 `nebula-support-dependencies` 中声明版本约束
+- [ ] 模块 `build.gradle` 中的依赖是否**不写版本号**（从 BOM 继承）
+- [ ] Framework 层模块是否未依赖 Starter 层（用 `compileOnly` 声明可选依赖）
+
+### 目录与命名
+
+- [ ] Service 实现类（含 SPI 实现）是否在 `service/impl/` 目录
+- [ ] 泛型参数数量是否与接口定义一致，没有多写或少写 `?`
+- [ ] `MapperExt` 类是否在 `mapper/` 目录，`Convert` 类是否在 `convert/` 目录
+- [ ] 常量类（状态值、枚举码）是否放在 API 模块的 `constant/` 目录
+
+### 多租户安全
+
+- [ ] 需要多租户隔离的查询是否使用 `LambdaQueryWrapper`（不使用 `@Select` 注解）
+- [ ] `@Select` 注解 SQL 是否手动补充了 `AND delete_flag = 0 AND tenant_id = #{tenantId}`
+
+### 代码质量
+
+- [ ] Service 层是否**未出现** `LambdaQueryWrapper`（动态查询移到 `MapperExt`）
+- [ ] Controller 是否**未出现**业务 `if` 判断，以及文件流/响应头处理等业务逻辑
+- [ ] IO 异常是否用 `SystemException` 包装（不用 `RuntimeException`）
+- [ ] 文件流复制是否用 `StreamUtils.copy`（不用手动 `byte[]` 循环）
+- [ ] 写操作（增删改）是否加 `@Transactional(rollbackFor = Exception.class)`
+- [ ] 是否没有 raw type 警告（如 `TaskHandler` 应写 `TaskHandler<?>` 而非 `TaskHandler`）
+- [ ] 跨模块操作是否通过 Service 接口（不直接注入其他业务域的 Mapper）
+- [ ] 对外 VO / RPC DTO 是否不含存储层内部字段（storagePath、bucketName、storageType 等）
+- [ ] DDL 是否完整包含 BaseEntity 11 个公共字段（`remark` 和 `custom_fields` 高频遗漏）
+
+### RPC 接口
+
+- [ ] 跨服务 Feign 接口是否按「三件套」实现（Constants + Feign Client + LocalStub）
+- [ ] Feign Client 是否声明了 `primary = false`（防止与 LocalStub 产生 Bean 冲突）
+- [ ] RPC Controller 是否加了 `@Hidden` 注解（隐藏于 Swagger 文档）
+- [ ] 服务名（SERVICE_NAME）是否与 `application.yaml` 中的 `spring.application.name` 一致
+
+### 日志与链路追踪
+
+- [ ] 服务是否已引入 `nebula-boot-starter-trace` 依赖（缺失则 HTTP/定时任务/MQ 均无 traceId）
+- [ ] Log4j2 日志 pattern 中 MDC 取值是否用 `%X{traceId}`（不是 Logback 写法 `%X{traceId:-}`）
+- [ ] Log4j2 日志 pattern 中进程 ID 是否用 `%processId`（不是 `${PID}`，后者在独立加载的 Log4j2 XML 中无值）
+- [ ] 各 profile（dev/uat/prod）的 `logging.config` 是否指向正确的环境配置文件
+- [ ] UAT/PROD 环境是否配置了 ELK JSON 日志文件（供 Filebeat 采集）
+- [ ] 生产环境（prod）是否关闭了 SQL 日志（`jdbc.*` 全部 `OFF`）
+- [ ] `@Scheduled` 定时任务不需要手动注入 traceId，框架 `ScheduledTraceAspect` 自动处理（确认 `spring-boot-starter-aop` 已引入）
+- [ ] MQ 消费者不需要手动设置 traceId，`TraceConsumerContextSetup` 自动从消息 Header 恢复或生成
+- [ ] 异步线程池任务是否通过 `TraceTaskDecorator` 传播 traceId（避免子线程日志无 traceId）