@nebula-skills/nebula-code-standards 0.1.0

package/skill/boot-components-catalog.md

@@ -0,0 +1,546 @@
+# nebula-boot 组件能力目录
+
+> 写代码前先来此查表。如果 boot 已经封装了某能力，**禁止** 在业务项目自己造轮子。如果 boot 没有，请走 [[upgrade-decision]] 判断「下沉到 boot」还是「业务自实现」。
+
+> 本目录是规则文档，**不需要去本地源码** 验证。当 API 签名有疑问时，去 Nexus 内网仓库（`http://10.10.1.130:8081/repository/nebula-public/`）翻 jar 包或问 nebula-boot 维护者。
+
+---
+
+## A. Framework 层（14 个模块）
+
+framework 层是**纯 Java + Spring 集成契约**，不带 `@AutoConfiguration`。每个模块导出工具类、注解、SPI 接口。
+
+### A.1 nebula-framework-core — 基础工具
+
+| 工具 | 一句话用法 |
+|------|----------|
+| `JsonUtils` | `JsonUtils.toJsonString(obj)` / `JsonUtils.parseObject(json, Class)` / `JsonUtils.parseArray(json, Class)` / `JsonUtils.getObjectMapper()` |
+| `AesUtils` / `RsaUtils` / `DigestUtils` | 对称/非对称加密、MD5/SHA 摘要 |
+| `DateUtils` / `DatePattern` | 日期工具与格式常量 |
+| `MDCUtils` | SLF4J MDC 取值/设置（traceId 等） |
+| `IdUtils` | Snowflake ID 生成（注意：跨服务业务号请用 system `IdGenRpcService`，不要拿 IdUtils 当业务号） |
+| `SpelExpressionUtils` | SpEL 表达式解析（支持方法参数、静态方法） |
+| `AssertUtils` | 参数断言 |
+| `StringUtils` / `CollectionUtils` / `MapUtils` | 集合 / 字符串工具 |
+| `BeanConvertUtils` / `BaseMapperConfig` | MapStruct 全局配置入口 |
+| `PageParam` / `PageResult<T>` | 分页入参 / 分页响应 |
+| `R<T>` | HTTP 统一响应包装：`R.ok(data)` / `R.fail(code, msg)` |
+| `BusinessException` / `SystemException` / `GlobalErrorCode` | 业务异常 / 系统异常 / 错误码 |
+
+**配置类入口：** `JacksonConfig`（Spring 注入即生效，已配置 LocalDateTime/null/日期格式）
+
+---
+
+### A.2 nebula-framework-trace — 链路追踪
+
+| 入口 | 用法 |
+|------|------|
+| `TraceContextHolder` | `TraceContextHolder.getTraceId()` / `TraceContextHolder.runWithContext(ctx, lambda)` |
+| `TraceContext` | 数据模型：traceId / spanId / parentSpanId / startTime |
+| `TraceIdGenerator`（SPI） | 自定义 TraceId 生成策略 |
+| `TracePropagator` / `TraceHeaders` | 在 HTTP Header / MDC 间传播 |
+| `ScheduledTraceAspect` | `@Scheduled` 任务自动生成 TraceId（已默认装配） |
+| `TraceTaskDecorator` | **线程池任务包装器，自建线程池必须包它**，否则丢 traceId |
+
+**关键代码：**
+```java
+String traceId = TraceContextHolder.getTraceId();   // 取当前 TraceId
+TraceContextHolder.runWithContext(ctx, () -> bizService.call());  // 函数式切换
+```
+
+**所属模块：** `nebula-framework-trace`，包 `com.huida.nebula.framework.trace`
+
+---
+
+### A.3 nebula-framework-tenant — 多租户
+
+| 入口 | 用法 |
+|------|------|
+| `TenantContextHolder` | `getTenantId()` / `getTenantCode()` / `runAsTenant(t, lambda)` / `runWithoutTenant(lambda)` |
+| `TenantInfo` | 数据模型：tenantId / tenantCode / schemaName / databaseKey |
+| `TenantIsolationMode` | 枚举：`DATABASE` / `SCHEMA` / `FIELD`（默认 FIELD） |
+| `@TenantSwitch` | 方法级切换租户 |
+| `@TenantIgnore` | 方法级忽略租户过滤（系统级操作） |
+| `@FeatureEnabled` | 功能开关注解 |
+| `TenantRoutingDataSource` / `SchemaSwitchingDataSource` | 多数据源路由 |
+
+**SPI 接口（业务方按需实现）：**
+
+| SPI | 用途 |
+|-----|------|
+| `TenantResolver` | 从请求中解析租户（Header / URL） |
+| `TenantDomainRepository` | 查询租户元数据 |
+| `TenantDataSourceProvider` | 提供租户对应数据源 |
+| `TenantInfoRepository` | 查询租户详情 |
+| `TenantFeatureRepository` | 查询租户功能开关 |
+| `TenantDataInitializer` | 租户初始化钩子 |
+| `TenantIsolationStrategy` | 自定义隔离策略 |
+
+**典型用法：**
+```java
+TenantContextHolder.runAsTenant(targetTenant, () -> orderService.syncOrders());
+TenantContextHolder.runWithoutTenant(() -> globalReportService.reloadAll());
+```
+
+**所属模块：** `nebula-framework-tenant`，包 `com.huida.nebula.framework.tenant`
+
+---
+
+### A.4 nebula-framework-security — 认证授权契约
+
+| 入口 | 用法 |
+|------|------|
+| `SecurityContextHolder` | 当前用户信息持有者 |
+| `@RequiresPermission` | 权限校验，支持 SpEL 与 AND/OR（`logic = LogicType.OR`） |
+| `@RequiresRole` | 角色校验 |
+| `@AnonymousAccess` | 标记匿名可访问 |
+| `IamUser` / `ClientIamUser` / `TokenInfo` / `SocialUserInfo` | 模型 |
+
+**SPI 接口：** `UserDetailsLoader` / `PermissionChecker` / `TokenValidator` / `TokenStore` / `SocialAuthProvider`
+
+**示例：**
+```java
+@RequiresPermission({"user:create", "user:edit"})            // AND
+@RequiresPermission(value = {"user:manage", "admin:all"}, logic = LogicType.OR)
+```
+
+> 注意：framework-security 只是契约，真正自动装配在 `nebula-boot-starter-security`。
+
+---
+
+### A.5 nebula-framework-idempotent — 幂等契约
+
+| 入口 | 用法 |
+|------|------|
+| `@Idempotent` | 注解参数：`key`（SpEL）/ `prefix` / `ttl` / `timeUnit` / `message` |
+| `IdempotentStore`（SPI） | 后端：Redis（默认）/ 内存 |
+
+**示例：**
+```java
+@Idempotent(key = "#req.tradeNo", ttl = 30)
+public void createOrder(CreateOrderRequest req) { ... }
+
+@Idempotent(key = "#msgId", prefix = "mq:pay")
+public void handlePayResult(String msgId, PayResultDTO dto) { ... }
+```
+
+---
+
+### A.6 nebula-framework-web — Web 基础设施
+
+| 入口 | 用法 |
+|------|------|
+| `ResponseResultHandler` | 自动包装返回值为 `R<T>` |
+| `GlobalExceptionHandler` | 全局异常 → `R.fail(...)` |
+| `RequestLoggingFilter` | 请求/响应日志 |
+| `@RepeatSubmit` | 防重复提交：`interval`（默认 5s）/ `keyExtra`（SpEL） |
+| `@IgnoreResponseWrap` | 跳过 R 包装（用于文件流返回） |
+| `@Desensitize` | 字段脱敏（响应序列化时生效） |
+| `SensitizeType` | 脱敏类型：手机、邮箱、身份证、银行卡等 |
+| `WebUtils` | Web 工具方法 |
+| `NebulaWebProperties` | 配置属性入口 |
+
+**示例：**
+```java
+@PostMapping("/order/create")
+@RepeatSubmit(interval = 5, message = "请勿重复提交订单")
+public R<Long> createOrder(@RequestBody @Valid CreateOrderDTO dto) {
+    return R.ok(orderService.create(dto));
+}
+
+public class UserVO {
+    @Desensitize(SensitizeType.MOBILE)
+    private String mobile;
+}
+```
+
+---
+
+### A.7 nebula-framework-mybatis — MyBatis-Plus 集成
+
+| 入口 | 用法 |
+|------|------|
+| `AuditEntity` | 审计基类（id / 7 个公共字段，不含 deleteFlag） |
+| `BaseEntity` | 业务实体基类，继承 AuditEntity 加上 `deleteFlag`（推荐默认使用） |
+| `TenantBaseEntity` | 带租户字段的基类（额外含 `tenantId`） |
+| `BaseMapper<T>` | 继承 MyBatis-Plus 的 BaseMapper，预留扩展点 |
+| `BaseService<T>` / `BaseServiceImpl<M, T>` | 通用 Service，`getByIdOrThrow(id)` 等 |
+| `MetaObjectHandlerImpl` | 字段自动填充（createTime / updateTime / creator / updater） |
+
+**11 个公共字段（继承 BaseEntity 后默认拥有，不要重复声明）：**
+
+```
+id  tenantId  createUserId  creator  createTime
+modifyUserId  updater  modifyTime  deleteFlag  remark  customFields
+```
+
+详见 [db-standards.md](db-standards.md) §二-2。
+
+**所属模块：** `nebula-framework-mybatis`，包 `com.huida.nebula.framework.mybatis.entity`
+
+---
+
+### A.8 nebula-framework-flyway / nacos / swagger / ratelimit / file / excel / task
+
+| 模块 | 用途 |
+|-----|------|
+| `nebula-framework-flyway` | Flyway 集成契约 |
+| `nebula-framework-nacos` | Nacos 配置中心契约 |
+| `nebula-framework-swagger` | OpenAPI 文档契约 |
+| `nebula-framework-ratelimit` | 限流契约（注解 / SPI） |
+| `nebula-framework-file` | 文件存储抽象 |
+| `nebula-framework-excel` | EasyExcel 集成契约 |
+| `nebula-framework-task` | 定时任务契约 |
+
+> 实际生效需引入对应 starter。
+
+---
+
+## B. Starter 层（22 个 starter）
+
+starter 层使用 Spring Boot 3 的 `@AutoConfiguration`，注册在 `META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports`。所有 `@Bean` 默认带 `@ConditionalOnMissingBean`，允许下游覆盖。
+
+### B.1 nebula-boot-starter-web
+
+| 装配内容 | 入口 |
+|---------|------|
+| 统一响应包装 | `ResponseResultHandler` |
+| 全局异常处理 | `GlobalExceptionHandler` |
+| 请求日志 Filter | `RequestLoggingFilter` |
+| @RepeatSubmit 拦截器 | （自动注册） |
+| Jackson 全局配置 | `JacksonConfig` |
+
+---
+
+### B.2 nebula-boot-starter-trace
+
+| 装配内容 | 说明 |
+|---------|------|
+| `TraceFilter` | HTTP 入口提取/生成 TraceId |
+| MDC 自动注入 | `traceId` / `spanId` |
+| 响应头追加 | `X-Trace-Id` |
+| `TraceTaskDecorator` | 提供给线程池 |
+
+---
+
+### B.3 nebula-boot-starter-tenant
+
+| 装配内容 | 说明 |
+|---------|------|
+| `TenantContextFilter` | HTTP 过滤器提取租户 |
+| MyBatis-Plus 租户插件 | 自动追加 `WHERE tenant_id = ?`（仅对 BaseMapper / LambdaQueryWrapper 生效；`@Select` 自定义 SQL 不会自动追加） |
+| 数据源路由 | DATABASE / SCHEMA 隔离时启用 |
+
+**配置：**
+```yaml
+nebula:
+  tenant:
+    enabled: true
+    isolation-mode: FIELD          # FIELD / SCHEMA / DATABASE
+    field:
+      ignore-tables: auth_login_log, auth_account  # 不追加 tenant_id 的表
+```
+
+---
+
+### B.4 nebula-boot-starter-jdbc
+
+Druid 多数据源 + 监控 + SQL 防火墙（可选）。配合 tenant 启用时支持租户路由。
+
+---
+
+### B.5 nebula-boot-starter-mybatis
+
+| 装配内容 | 说明 |
+|---------|------|
+| `PaginationInterceptor` | 分页插件 |
+| `OptimisticLockerInnerInterceptor` | 乐观锁（`@Version` 字段） |
+| `BlockAttackInnerInterceptor` | 防全表 UPDATE/DELETE |
+| 逻辑删除全局配置 | `@TableLogic` → `delete_flag` |
+| `MetaObjectHandlerImpl` | 自动填充 |
+
+---
+
+### B.6 nebula-boot-starter-redis ⭐
+
+| 装配内容 | 入口 |
+|---------|------|
+| Redisson 客户端 | `RedissonClient` |
+| **`NebulaLockHelper`** | 分布式锁，**禁止用 `StringRedisTemplate.setIfAbsent`** |
+| **`NebulaCacheHelper`** | Redis 缓存工具 |
+| `@DistributedLock` | 声明式分布式锁（SpEL Key） |
+| `NebulaMultiLevelCacheAutoConfiguration` | 本地 + Redis 多级缓存 |
+| `CacheEvictPublisher/Subscriber` | 多级缓存一致性 |
+
+**典型用法：**
+```java
+// 函数式 — Runnable
+lockHelper.tryLock("order:" + orderId, () -> orderService.create(...));
+
+// 函数式 — Supplier（有返回值）
+OrderVO vo = lockHelper.tryLock("order:" + orderId, () -> orderService.detail(orderId));
+
+// 注解式
+@DistributedLock(key = "'order:create:' + #orderId")
+public OrderVO createOrder(Long orderId, OrderDTO dto) { ... }
+
+// 缓存工具
+cacheHelper.set("user:" + id, user, Duration.ofMinutes(10));
+User u = cacheHelper.get("user:" + id, User.class);
+```
+
+> ⚠️ `NebulaCacheHelper` 没有 `hashGetAll`，整体对象读写改用 JSON 字符串存。
+
+**所属模块：** `nebula-boot-starter-redis`，包 `com.huida.nebula.boot.autoconfigure.redis`
+
+---
+
+### B.7 nebula-boot-starter-mq
+
+| 装配内容 | 说明 |
+|---------|------|
+| `NebulaRocketMQProducer` | 同步/异步/延迟/顺序消息发送，自动透传 TraceId/TenantCode |
+| `AbstractNebulaMessageListener<T>` | 消费者抽象基类，自动恢复 TraceId/TenantCode 上下文 |
+| `ConsumeContext` | 消费上下文（msgId / traceId / retry） |
+| `DeadLetterHandler`（SPI） | 死信处理 |
+
+**消费者用法：**
+```java
+@Component
+@RocketMQMessageListener(topic = "order-topic", consumerGroup = "order-consumer-group")
+public class OrderCreatedListener extends AbstractNebulaMessageListener<OrderCreatedEvent> {
+    @Override
+    protected void onMessage(OrderCreatedEvent event, ConsumeContext context) {
+        // TraceId / TenantCode 已自动恢复
+        orderService.handleCreated(event);
+    }
+}
+```
+
+---
+
+### B.8 nebula-boot-starter-log ⭐
+
+审计日志的全部代码在此 starter（framework 层无 log 模块）。
+
+| 装配内容 | 入口 |
+|---------|------|
+| `AuditLogAspect` | 拦截 `@AuditLog` |
+| `AuditDiffer` | 对象变更差异计算 |
+| `AuditLogPipelineRouter` | 路由到 MySQL / Mongo / MQ / Console |
+| `OperationLogAspect` | 操作日志记录 |
+| 字段脱敏 | `MaskerRegistry` |
+
+**核心注解：**
+
+| 注解 | 用法 |
+|------|------|
+| `@AuditLog` | 参数 `bizType` / `bizId`（SpEL）/ `changeType` / `content`（SpEL）/ `executeBeforeFunc` |
+| `@AuditObject` | 标记被审计对象 |
+| `@AuditField` | 标记审计字段 |
+| `@AuditFieldIgnore` | 忽略字段 |
+
+**内置 SpEL 函数：** `#_DIFF(oldObj, newObj)` / `#_DIFF_ROWS(oldList, newList)` / `#_return` / `#_errorMsg`
+
+**示例：**
+```java
+@AuditLog(
+    bizType = "ORDER",
+    bizId = "#order.id",
+    changeType = "UPDATE",
+    content = "'订单修改' + #_DIFF(#oldOrder, #order)"
+)
+public void updateOrder(OrderDO oldOrder, OrderDO order) { ... }
+```
+
+**SPI：** `AuditLogPipeline` — 自定义日志输出目的地。
+
+---
+
+### B.9 nebula-boot-starter-idempotent
+
+`@Idempotent` 拦截器 + Redis/Memory 后端实现。引入即可用注解。
+
+---
+
+### B.10 nebula-boot-starter-security
+
+| 装配内容 | 说明 |
+|---------|------|
+| Spring Security 无状态配置 | JWT |
+| Token 黑名单 | Redis 存储 |
+| `@RequiresPermission` / `@RequiresRole` 拦截器 | （自动注册） |
+
+> 注意：聚合 starter `nebula-boot-starter` 默认 **不** 引入 security，业务项目需自己引。
+
+---
+
+### B.11 nebula-boot-starter-openfeign
+
+| 装配内容 | 说明 |
+|---------|------|
+| `FeignTraceInterceptor` | 自动透传 `X-Trace-Id` |
+| `FeignTenantInterceptor` | （README 标记暂未透传 TenantCode，是已知缺口） |
+| `NebulaFeignDecoder` | 统一 `R<T>` 解包 |
+| `NebulaFeignErrorDecoder` | 错误响应处理 |
+
+---
+
+### B.12 nebula-boot-starter-threadpool
+
+业务线程池统一装配，已内嵌 `TraceTaskDecorator` + `TenantTaskDecorator`，**用此 starter 提供的线程池就不会丢上下文**。
+
+---
+
+### B.13 其他 starter
+
+| starter | 用途 |
+|---------|------|
+| `nebula-boot-starter-flyway` | Flyway 自动迁移 |
+| `nebula-boot-starter-nacos` | Nacos 配置中心 |
+| `nebula-boot-starter-swagger` | springdoc-openapi 集成 |
+| `nebula-boot-starter-ratelimit` | 注解式限流 |
+| `nebula-boot-starter-task` | 定时任务装配 |
+| `nebula-boot-starter-excel` | EasyExcel 装配 |
+| `nebula-boot-starter-file` | 文件存储抽象（本地 / OSS 接入点） |
+| `nebula-boot-starter-elasticsearch` | ES 客户端 |
+| `nebula-boot-starter-mongo` | MongoDB 客户端 |
+
+---
+
+### B.14 nebula-boot-starter（聚合器）
+
+一行引入除 security 之外的全部 starter：
+
+```gradle
+api "com.huida.nebula.boot:nebula-boot-starter:${nebulaBootVersion}"
+api "com.huida.nebula.boot:nebula-boot-starter-security:${nebulaBootVersion}"  // 按需单引
+```
+
+---
+
+## C. 速查矩阵（关键词 → 组件）
+
+写代码前先在这张表里找关键词。**没找到** 才进入 [[upgrade-decision]]。
+
+| 场景关键词 | 该用的组件 | 文档锚点 |
+|-----------|----------|---------|
+| JSON 序列化 | `JsonUtils` | §A.1 |
+| 雪花 ID | `IdUtils` | §A.1 |
+| 业务号（订单号/工单号） | system `IdGenRpcService`（**不要 IdUtils**） | [[rpc-api-reference]] |
+| 分布式锁 | `NebulaLockHelper` / `@DistributedLock` | §B.6 |
+| Redis 缓存 | `NebulaCacheHelper` | §B.6 |
+| 防重复提交（HTTP） | `@RepeatSubmit` | §A.6 |
+| 接口幂等（业务 Key） | `@Idempotent` | §A.5 |
+| 数据脱敏（响应） | `@Desensitize` | §A.6 |
+| 限流 | `nebula-boot-starter-ratelimit` | §B.13 |
+| 审计日志 | `@AuditLog` | §B.8 |
+| 操作日志 | `OperationLogAspect`（starter-log） | §B.8 |
+| 权限校验 | `@RequiresPermission` / `@RequiresRole` | §A.4 |
+| 当前用户 | `SecurityContextHolder` | §A.4 |
+| 多租户切换 | `TenantContextHolder.runAsTenant` / `@TenantSwitch` | §A.3 |
+| 忽略租户过滤 | `TenantContextHolder.runWithoutTenant` / `@TenantIgnore` | §A.3 |
+| 链路追踪当前 ID | `TraceContextHolder.getTraceId()` | §A.2 |
+| 自建线程池保 traceId | `TraceTaskDecorator` 或直接用 starter-threadpool | §A.2 / §B.12 |
+| 分页 | `PageParam` / `PageResult<T>` | §A.1 |
+| 统一响应 | `R<T>` | §A.1 |
+| 业务异常 | `BusinessException` + `GlobalErrorCode` | §A.1 |
+| 系统异常 | `SystemException` | §A.1 |
+| 实体基类 | `BaseEntity`（默认） / `AuditEntity`（物理删除） / `TenantBaseEntity` | §A.7 |
+| 字段自动填充 | `MetaObjectHandlerImpl`（starter-mybatis 已装配） | §B.5 |
+| 防全表 UPDATE/DELETE | `BlockAttackInnerInterceptor`（已装配） | §B.5 |
+| RocketMQ 发送 | `NebulaRocketMQProducer` | §B.7 |
+| RocketMQ 消费 | `extends AbstractNebulaMessageListener<T>` | §B.7 |
+| Excel 导入导出 | `nebula-boot-starter-excel` | §B.13 |
+| 文件存储 | `nebula-boot-starter-file` | §B.13 |
+| Feign Trace 透传 | starter-openfeign 已自动 | §B.11 |
+| Feign Tenant 透传 | ❌ 当前缺口 | [[upgrade-decision]] |
+| Redis 多租户 Key 隔离 | ❌ 当前缺口 | [[upgrade-decision]] |
+| XXL-Job 集成 | ❌ 当前缺口（`nebula-boot-starter-job` 未实现） | [[upgrade-decision]] |
+| OSS 对象存储抽象 | ❌ 当前缺口（`nebula-boot-starter-oss` 未实现） | [[upgrade-decision]] |
+| 可靠本地事件 | ❌ 当前缺口（`nebula-boot-starter-event` 未实现） | [[upgrade-decision]] |
+| 短信 | ❌ 当前缺口（`nebula-boot-starter-sms` 未实现） | [[upgrade-decision]] |
+
+---
+
+## D. 请求生命周期（理解组件协作）
+
+```
+HTTP 请求
+  → TraceFilter             (生成/提取 TraceId → MDC + TraceContextHolder)
+  → TenantContextFilter     (解析 TenantCode → TenantContextHolder + 数据源路由)
+  → RequestLoggingFilter    (请求/响应日志)
+  → Controller
+      → @RepeatSubmit       (body hash 防重)
+      → @Idempotent         (业务 Key 幂等)
+      → @DistributedLock    (Redisson 锁)
+      → @RequiresPermission (权限校验)
+      → @AuditLog           (前置快照 → 执行 → 计算 diff → 写管道)
+  → Service / Mapper        (自动填充审计字段、自动追加 tenant_id 与 delete_flag = 0)
+  → ResponseResultHandler   (包装为 R<T>、响应头追加 X-Trace-Id)
+  → finally                 (TraceContextHolder.clear / TenantContextHolder.clear / MDC.clear)
+```
+
+线程池场景：
+- 用 `nebula-boot-starter-threadpool` 的线程池 → 上下文自动传播
+- 自建 `ThreadPoolExecutor` → 必须包装 `TraceTaskDecorator` + `TenantTaskDecorator`
+
+---
+
+## E. 关键 SPI / 必备实现
+
+`nebula-framework-task` 模块定义了 3 个**持久化 SPI 契约**，业务 starter 启动时若未提供实现会拿不到默认 Bean。业务项目初始化时**必须** 提供（哪怕是空实现）：
+
+| SPI | 包 | 方法签名 |
+|-----|-----|---------|
+| `ApiLogRepository` | `com.huida.nebula.framework.task.apilog` | `void saveAsync(ApiLogModel logModel)` |
+| `TaskQueueService` | `com.huida.nebula.framework.task.queue` | `void publish(TaskMessage)` / `void publishDelayed(TaskMessage, long)` / `String queueType()` |
+| `TaskInstanceRepository` | `com.huida.nebula.framework.task.core.executor` | `markRunning(Long)` / `markSuccess(Long, TaskContext)` / `markFailed(Long, String)` / `markCancelled(Long)` / `updateProgress(Long, int, long, long)` |
+
+占位实现模板与 `@AutoConfiguration` 装配见 [[init-new-project]] §五-必备 SPI 空实现。
+
+---
+
+## F. 包导入约定（业务项目最常用）
+
+```java
+// core 工具
+import com.huida.nebula.core.json.JsonUtils;
+import com.huida.nebula.core.common.model.R;
+import com.huida.nebula.core.common.model.PageParam;
+import com.huida.nebula.core.common.model.PageResult;
+import com.huida.nebula.core.exception.BusinessException;
+import com.huida.nebula.core.common.constant.CommonConstants;
+
+// MyBatis 基类
+import com.huida.nebula.framework.mybatis.entity.BaseEntity;
+import com.huida.nebula.framework.mybatis.entity.AuditEntity;
+import com.huida.nebula.framework.mybatis.entity.TenantBaseEntity;
+import com.huida.nebula.framework.mybatis.mapper.BaseMapper;
+import com.huida.nebula.framework.mybatis.service.BaseService;
+import com.huida.nebula.framework.mybatis.service.impl.BaseServiceImpl;
+
+// 上下文
+import com.huida.nebula.framework.trace.context.TraceContextHolder;
+import com.huida.nebula.framework.tenant.context.TenantContextHolder;
+import com.huida.nebula.framework.security.context.SecurityContextHolder;
+
+// 注解
+import com.huida.nebula.framework.web.annotation.RepeatSubmit;
+import com.huida.nebula.framework.web.annotation.Desensitize;
+import com.huida.nebula.framework.web.annotation.IgnoreResponseWrap;
+import com.huida.nebula.framework.idempotent.Idempotent;
+import com.huida.nebula.framework.security.annotation.RequiresPermission;
+import com.huida.nebula.framework.security.annotation.RequiresRole;
+import com.huida.nebula.framework.tenant.annotation.TenantSwitch;
+import com.huida.nebula.framework.tenant.annotation.TenantIgnore;
+
+// starter 提供（需引入对应 starter）
+import com.huida.nebula.boot.autoconfigure.redis.NebulaLockHelper;
+import com.huida.nebula.boot.autoconfigure.redis.NebulaCacheHelper;
+import com.huida.nebula.boot.autoconfigure.redis.lock.DistributedLock;
+import com.huida.nebula.boot.autoconfigure.log.audit.annotation.AuditLog;
+import com.huida.nebula.boot.autoconfigure.mq.consumer.AbstractNebulaMessageListener;
+```
+
+不确定全限定类名时优先 IDE 自动 import，**不要去 Read 源码** 验证。