@nebula-skills/nebula-code-standards 0.1.0

package/skill/backend-standards.md

@@ -0,0 +1,611 @@
+# 后端开发规范
+
+> 适用于所有 Nebula 框架业务后端项目。
+
+## 一、分层架构与职责边界
+
+```
+HTTP 请求
+    │
+    ▼
+Controller 层     ← 接收/校验入参，调用 Service，包装 R<T> 响应；不含任何业务 if 逻辑
+    │
+    ▼
+Service 层        ← 业务逻辑、唯一性校验、事务边界、抛出 BusinessException；不写 LambdaQueryWrapper
+    │
+   ┌┴──────────────────────┐
+   ▼                       ▼
+Mapper 接口               MapperExt 类
+（固定/注解 SQL）          （动态 LambdaQueryWrapper、分页两段式、唯一性检查）
+   │
+   ▼
+MySQL（Flyway 版本化管理）
+```
+
+**禁止事项：**
+
+| 禁止 | 原因 |
+|------|------|
+| Controller 中写 `if` 业务判断 | 违反分层原则 |
+| Controller 中处理文件流、设置响应头、读写 InputStream | 业务逻辑必须下沉到 Service，Controller 只做透传 |
+| Service 中注入 `HttpServletRequest` | 违反分层原则 |
+| Service 中写 `LambdaQueryWrapper` | 应放在 MapperExt |
+| Controller 直接返回 DO | 泄露数据库结构 |
+| 返回 `null` 给前端的 VO | 应返回空对象或空列表 |
+| `catch(Exception e) { /* 吞掉 */ }` | 掩盖问题，难以排查 |
+| IO/系统异常 `throw new RuntimeException(...)` | 应使用 `SystemException(GlobalErrorCode.INTERNAL_SERVER_ERROR, msg, e)` |
+| XML Mapper / `@Select` 注解 SQL 缺少 `delete_flag = 0` 或租户过滤 | 自定义 SQL 绕过 MP 拦截器，会查出已删除/跨租户数据 |
+| Mapper 接口用 `@Select` 写含动态条件的查询 | 应使用 `MapperExt` + `LambdaQueryWrapper`，确保多租户拦截器生效 |
+| `new ObjectMapper().readValue(...)` | 配置不一致，应使用 `JsonUtils.parseObject()` |
+| `StringRedisTemplate.setIfAbsent` 实现分布式锁 | 非原子释放，应使用 `NebulaLockHelper` 或 `RedissonClient` |
+| `StringRedisTemplate` 直接读写 Redis | 应使用 `NebulaCacheHelper`（自动追加 Key 前缀、JSON 序列化封装） |
+| 模块 `build.gradle` 中硬编码第三方库版本号 | 版本应统一在 `nebula-support-dependencies` 的 BOM 中管理 |
+| Service 实现类放在 `service/` 目录（非 `impl/`） | 违反包结构约定，应放在 `service/impl/` |
+| Framework 层模块依赖 Starter 层 | 违反分层原则，Framework 层只能依赖同层或更底层 |
+| 业务常量（状态值、策略枚举、类型码）硬编码在 Service/Controller 中 | 应提取到 `{域}Constants` 常量类集中管理 |
+| Service 中直接注入**其他业务域**的 Mapper（如 `SysFileMetaMapper`） | 跨模块操作必须通过对方的 Service 接口，不绕过 Service 层调用底层 Mapper |
+| VO（RespVO）和 RPC DTO 中包含存储实现细节字段（`storagePath`、`bucketName`、`storageType`） | 对外接口不暴露内部存储实现，调用方需访问文件时应通过 `getAccessUrl` 接口获取 URL |
+
+---
+
+## 二、包结构约定
+
+```
+com.huida.nebula.{业务域}.{模块名}/
+├── controller/
+│   └── {业务名}Controller.java
+├── service/
+│   ├── I{业务名}Service.java
+│   └── impl/
+│       └── {业务名}ServiceImpl.java
+├── mapper/
+│   ├── {业务名}Mapper.java        # 固定 SQL / 基础 CRUD
+│   └── {业务名}MapperExt.java     # 动态查询（LambdaQueryWrapper）
+├── entity/
+│   └── {业务名}DO.java
+├── vo/
+│   ├── param/
+│   │   ├── {业务名}PageParamVO.java
+│   │   └── {业务名}SaveParamVO.java
+│   └── resp/
+│       ├── {业务名}RespVO.java
+│       └── {业务名}DetailVO.java
+└── convert/
+    └── {业务名}Convert.java
+```
+
+---
+
+## 三、实体类规范（DO）
+
+```java
+@Data
+@EqualsAndHashCode(callSuper = true)
+@TableName("t_demo")                      // 必须：映射数据库表名（t_ 前缀）
+@Schema(description = "示例实体")          // 必须：Swagger 文档描述
+public class DemoDO extends BaseEntity {  // 必须继承 BaseEntity
+
+    @Schema(description = "示例名称")
+    private String demoName;              // 驼峰，自动映射 demo_name 列
+
+    @Schema(description = "状态（0:正常 1:禁用）")
+    private Integer status;
+}
+```
+
+**注意：**
+- `BaseEntity` 已有的字段（`id`、`tenantId`、`creator`、`createTime`、`remark` 等 11 个）**不要**在子类重复声明
+- 字段类型：`VARCHAR → String`、`INT → Integer`、`BIGINT → Long`、`DATETIME → LocalDateTime`
+- 枚举值在注释中说明，如：`状态（0:正常 1:禁用）`
+- DO 中**禁止**添加计算属性或前端展示逻辑
+
+---
+
+## 四、VO 规范
+
+### 4.1 分页入参（XxxPageParamVO）
+
+```java
+@Data
+@EqualsAndHashCode(callSuper = true)
+@Schema(description = "示例分页查询参数")
+public class DemoPageParamVO extends PageParam {  // 必须继承 PageParam
+
+    @Schema(description = "示例名称（支持模糊匹配）")
+    private String demoName;   // 所有过滤字段均为可选，不传则不过滤
+
+    @Schema(description = "状态（0:正常 1:禁用）")
+    private Integer status;
+}
+```
+
+`PageParam` 内置：`pageNo`（默认1）、`pageSize`（默认10）、`sorts`（`List<SortItem>`）
+
+### 4.2 新增/修改入参（XxxSaveParamVO）
+
+新增和修改**共用一个 VO**，通过校验分组区分：
+
+```java
+@Data
+@Schema(description = "示例新增/修改参数")
+public class DemoSaveParamVO implements Serializable {
+
+    /** 修改专用校验分组 */
+    public interface UpdateGroup {}
+
+    @NotNull(groups = UpdateGroup.class, message = "修改时主键 id 不能为空")
+    @Schema(description = "主键（新增时不传，修改时必填）")
+    private Long id;
+
+    @NotBlank(message = "示例名称不能为空")
+    @Size(max = 100, message = "名称不能超过 100 个字符")
+    @Schema(description = "示例名称", requiredMode = Schema.RequiredMode.REQUIRED)
+    private String demoName;
+
+    /** 判断是否为新增操作 */
+    public boolean isNew() { return id == null; }
+}
+```
+
+Controller 使用方式：
+- 新增：`@Valid @RequestBody`（不校验 id）
+- 修改：`@Validated(DemoSaveParamVO.UpdateGroup.class) @RequestBody`（id 变为必填）
+
+### 4.3 列表响应 VO（XxxRespVO）
+
+只返回列表展示所需字段：
+
+```java
+@Data
+@Schema(description = "示例列表项")
+public class DemoRespVO implements Serializable {
+    @Schema(description = "主键ID")       private Long id;
+    @Schema(description = "示例名称")     private String demoName;
+    @Schema(description = "示例编码")     private String demoCode;
+    @Schema(description = "状态")         private Integer status;
+    @Schema(description = "创建人")       private String creator;
+    @Schema(description = "创建时间")     private LocalDateTime createTime;
+    @Schema(description = "最后修改时间") private LocalDateTime modifyTime;
+}
+```
+
+### 4.4 详情响应 VO（XxxDetailVO）
+
+包含所有相关字段，含备注、审计信息：
+
+```java
+@Data
+@Schema(description = "示例详情")
+public class DemoDetailVO implements Serializable {
+    // 基础字段（与 RespVO 一致）
+    private Long id;
+    private String demoName;
+    private String demoCode;
+    private Integer status;
+    // 详情专有字段
+    @Schema(description = "备注")             private String remark;
+    @Schema(description = "自定义扩展字段")   private String customFields;
+    @Schema(description = "创建人")           private String creator;
+    @Schema(description = "创建时间")         private LocalDateTime createTime;
+    @Schema(description = "创建人ID")         private Long createUserId;
+    @Schema(description = "最后修改人用户名") private String updater;
+    @Schema(description = "最后修改人ID")     private Long modifyUserId;
+    @Schema(description = "最后修改时间")     private LocalDateTime modifyTime;
+}
+```
+
+---
+
+## 五、MapStruct 对象转换规范
+
+```java
+@Mapper(config = BaseMapperConfig.class)   // 必须指定，忽略未映射字段（防编译报错）
+public interface DemoConvert {
+
+    DemoConvert INSTANCE = Mappers.getMapper(DemoConvert.class);  // 全局单例，直接调用
+
+    DemoRespVO doToRespVO(DemoDO demoDO);              // 实体 → 列表VO（分页查询）
+    DemoDetailVO doToDetailVO(DemoDO demoDO);           // 实体 → 详情VO（详情查询）
+    DemoDO saveParamToDo(DemoSaveParamVO saveParam);    // 入参 → 实体（新增）
+
+    // 入参合并到现有实体（修改）：只覆盖 saveParam 中有值的字段，createTime 等不受影响
+    void saveParamMergeToDo(DemoSaveParamVO saveParam, @MappingTarget DemoDO demoDO);
+}
+```
+
+四种场景：
+
+```java
+// 场景1：分页查询 → 批量转换
+return pageResult.convert(DemoConvert.INSTANCE::doToRespVO);
+
+// 场景2：详情查询
+return DemoConvert.INSTANCE.doToDetailVO(demoDO);
+
+// 场景3：新增
+DemoDO demoDO = DemoConvert.INSTANCE.saveParamToDo(saveParam);
+save(demoDO);  // id、tenantId、createTime 等由框架自动填充
+
+// 场景4：修改（增量更新）
+DemoDO demoDO = getByIdOrThrow(id);
+DemoConvert.INSTANCE.saveParamMergeToDo(saveParam, demoDO);
+updateById(demoDO);
+```
+
+---
+
+## 六、MapperExt 规范（动态查询）
+
+```java
+@Repository
+@RequiredArgsConstructor
+public class DemoMapperExt {
+
+    private final DemoMapper demoMapper;
+}
+```
+
+### 6.1 分页两段式查询（必须遵守）
+
+```java
+public PageResult<DemoDO> pageQuery(DemoPageParamVO query) {
+    LambdaQueryWrapper<DemoDO> wrapper = buildPageWrapper(query);
+
+    // 第一段：先 count，count=0 时短路，避免无效的 LIMIT 查询
+    Long count = demoMapper.selectCount(wrapper);
+    if (count == null || count == 0) {
+        return PageResult.empty(query);
+    }
+
+    // 第二段：fetch，false 表示不让 MP 自动再 count 一次
+    Page<DemoDO> mpPage = new Page<>(query.getPageNo(), query.getPageSize(), false);
+    applySort(mpPage, query);
+    Page<DemoDO> result = demoMapper.selectPage(mpPage, wrapper);
+    return PageResult.of(result.getRecords(), count, query);
+}
+```
+
+### 6.2 动态条件构建规则
+
+```java
+private LambdaQueryWrapper<DemoDO> buildPageWrapper(DemoPageParamVO query) {
+    return new LambdaQueryWrapper<DemoDO>()
+        // String 类型：用 StringUtils.hasText() 判空（防止空字符串参与过滤）
+        .like(StringUtils.hasText(query.getDemoName()), DemoDO::getDemoName, query.getDemoName())
+        .eq(StringUtils.hasText(query.getDemoCode()), DemoDO::getDemoCode, query.getDemoCode())
+        // 对象类型：用 != null 判空
+        .eq(query.getStatus() != null, DemoDO::getStatus, query.getStatus())
+        .orderByDesc(DemoDO::getCreateTime);
+}
+```
+
+**判空规则：**
+- `String` 字段 → `StringUtils.hasText(value)`
+- `Integer` / `Long` / 其他对象 → `value != null`
+
+### 6.3 唯一性检查
+
+```java
+// excludeId：修改时传入自身 id（排除自身），新增时传 null
+public boolean existsByCode(String demoCode, Long excludeId) {
+    return demoMapper.selectCount(
+        new LambdaQueryWrapper<DemoDO>()
+            .eq(DemoDO::getDemoCode, demoCode)
+            .ne(excludeId != null, DemoDO::getId, excludeId)
+    ) > 0;
+}
+```
+
+### 6.4 排序处理
+
+```java
+private void applySort(Page<DemoDO> mpPage, DemoPageParamVO query) {
+    if (!query.hasSorts()) return;
+    for (SortItem sortItem : query.getSorts()) {
+        String col = camelToSnake(sortItem.getColumn());  // 驼峰转下划线
+        mpPage.addOrder(sortItem.isAscending() ? OrderItem.asc(col) : OrderItem.desc(col));
+    }
+}
+
+private static String camelToSnake(String camel) {
+    StringBuilder sb = new StringBuilder();
+    for (int i = 0; i < camel.length(); i++) {
+        char c = camel.charAt(i);
+        if (Character.isUpperCase(c) && i > 0) sb.append('_');
+        sb.append(Character.toLowerCase(c));
+    }
+    return sb.toString();
+}
+```
+
+---
+
+## 七、Mapper 接口规范
+
+```java
+@Mapper
+public interface DemoMapper extends BaseMapper<DemoDO> {
+    // BaseMapper 已提供：save / removeById / updateById / selectById / selectPage 等
+    // 极少数需要固定 SQL 且无动态条件时，才在此处用 @Select，必须手动加租户和删除过滤
+    @Select("SELECT * FROM t_demo WHERE demo_code = #{code} AND delete_flag = 0 LIMIT 1")
+    Optional<DemoDO> selectByCode(@Param("code") String code);
+}
+```
+
+**多租户与逻辑删除的过滤规则：**
+
+| SQL 来源 | 自动过滤 `delete_flag` | 自动追加 `tenant_id` |
+|---------|----------------------|---------------------|
+| MP BaseMapper / `LambdaQueryWrapper` | ✅ 自动 | ✅ 自动（TenantLineInnerInterceptor） |
+| `@Select` 注解 / XML Mapper | ❌ 需手动加 | ❌ 需手动加 |
+
+**结论：凡是需要多租户隔离的查询，必须走 `LambdaQueryWrapper`（放在 `MapperExt`），不能用 `@Select` 注解 SQL。**
+
+```java
+// ✅ 正确：MapperExt 中使用 LambdaQueryWrapper，MP 自动追加租户和逻辑删除过滤
+public DemoDO findByCode(String code) {
+    return demoMapper.selectOne(
+        new LambdaQueryWrapper<DemoDO>()
+            .eq(DemoDO::getDemoCode, code)
+            .last("LIMIT 1")
+    );
+}
+
+// ❌ 错误：@Select 注解绕过了 TenantLineInnerInterceptor，有跨租户数据泄露风险
+@Select("SELECT * FROM t_demo WHERE demo_code = #{code} LIMIT 1")
+DemoDO selectByCode(@Param("code") String code);
+```
+
+---
+
+## 八、Service 层规范
+
+### 8.1 接口定义
+
+```java
+public interface IDemoService extends BaseService<DemoDO> {
+    PageResult<DemoRespVO> pageDemo(DemoPageParamVO query);
+    DemoDetailVO getDemoById(Long id);
+    Long createDemo(DemoSaveParamVO saveParam);
+    void updateDemo(DemoSaveParamVO saveParam);
+    void deleteDemo(List<Long> ids);
+    void enableDemo(Long id);   // 语义化命名，而非 updateStatus
+    void disableDemo(Long id);
+}
+```
+
+### 8.2 实现类
+
+```java
+@Slf4j
+@Service
+@RequiredArgsConstructor
+public class DemoServiceImpl extends BaseServiceImpl<DemoMapper, DemoDO>
+        implements IDemoService {
+
+    private final DemoMapperExt demoMapperExt;
+}
+```
+
+### 8.3 关键规范
+
+**写操作加事务：**
+```java
+@Transactional(rollbackFor = Exception.class)
+public Long createDemo(DemoSaveParamVO saveParam) { ... }
+```
+
+**查询不存在时抛异常（不要手动判 null）：**
+```java
+DemoDO demoDO = getByIdOrThrow(id);  // 不存在自动抛 BusinessException(DATA_NOT_FOUND)
+```
+
+**业务校验抛异常：**
+```java
+if (demoMapperExt.existsByCode(saveParam.getDemoCode(), null)) {
+    throw new BusinessException(GlobalErrorCode.PARAM_INVALID.getCode(),
+            "编码 [" + saveParam.getDemoCode() + "] 已存在");
+}
+```
+
+**状态变更（最小更新，不污染其他字段）：**
+```java
+public void enableDemo(Long id) {
+    getByIdOrThrow(id);
+    DemoDO update = new DemoDO();
+    update.setId(id);
+    update.setStatus(0);
+    updateById(update);
+    log.info("启用示例成功，id={}", id);
+}
+```
+
+**关键写操作必须打日志：**
+```java
+log.info("新增示例成功，id={}，code={}", demoDO.getId(), demoDO.getDemoCode());
+log.info("修改示例成功，id={}", id);
+log.info("批量逻辑删除成功，ids={}", ids);
+```
+
+---
+
+## 九、Controller 层规范
+
+### 9.1 类结构
+
+```java
+@Tag(name = "示例管理", description = "t_demo 增删改查接口")  // Swagger 分组
+@Validated                                                    // 激活方法级参数校验
+@RestController
+@RequestMapping("/{domain}/demo")                              // 路径格式：/{业务域}/{资源名}
+@RequiredArgsConstructor
+public class DemoController {
+
+    private final IDemoService demoService;   // 只依赖接口，不依赖 Impl
+}
+```
+
+### 9.2 Swagger 注解规范
+
+| 注解 | 位置 | 说明 |
+|------|------|------|
+| `@Tag(name, description)` | Controller 类 | 接口分组 |
+| `@Operation(summary)` | 接口方法 | 接口描述 |
+| `@Parameter(name, description, required)` | Path/Query 参数 | 参数说明 |
+| `@Schema(description)` | VO 字段 | 字段说明 |
+| `@Schema(requiredMode = REQUIRED)` | VO 必填字段 | 标记必填 |
+
+### 9.3 统一响应规范
+
+- 返回类型**必须**为 `R<T>`，不允许直接返回裸对象
+- 有数据：`R.ok(data)`
+- 无数据（写操作）：`R.ok()`
+- Controller 中**不处理**异常，由全局异常处理器统一响应
+
+---
+
+## 十、通用 Java 规范
+
+### 依赖注入
+统一使用构造器注入，配合 `@RequiredArgsConstructor`（字段必须为 `final`）：
+```java
+private final DemoMapperExt demoMapperExt;   // 不使用 @Autowired
+```
+
+### 日志规范
+```java
+@Slf4j   // Lombok 自动注入 log 字段
+// 使用 log.info/warn/error，不使用 System.out.println
+// 异常捕获：log.error("操作失败", e)
+// 不在日志中打印密码、Token 等敏感信息
+```
+
+### 空值处理
+```java
+// String 判空：使用 StringUtils.hasText（同时排除 null 和空白字符串）
+if (!StringUtils.hasText(demoCode)) { ... }
+
+// 集合判空：先判 null 再判 empty
+if (ids == null || ids.isEmpty()) { return; }
+
+// 对象判空：使用框架提供的 getByIdOrThrow，不要手动 if(xx == null) throw ...
+```
+
+### 异常处理
+
+| 场景 | 正确用法 |
+|------|---------|
+| 业务校验失败（参数非法、数据不存在、状态不符） | `BusinessException(GlobalErrorCode.PARAM_INVALID, "...")` |
+| 系统级失败（IO 异常、外部调用失败、序列化失败） | `SystemException(GlobalErrorCode.INTERNAL_SERVER_ERROR, "...", e)` |
+| 查询不存在直接抛异常 | `getByIdOrThrow(id)`（`BaseServiceImpl` 提供，自动包装 `DATA_NOT_FOUND`） |
+
+```java
+// ✅ IO 异常正确写法
+try {
+    StreamUtils.copy(in, out);
+} catch (IOException e) {
+    throw new SystemException(GlobalErrorCode.INTERNAL_SERVER_ERROR, "文件下载失败: " + e.getMessage(), e);
+}
+
+// ❌ 禁止
+throw new RuntimeException("文件读取失败", e);
+```
+
+- 不允许吞掉异常（`catch(Exception e) {}`）
+- `@Transactional` 必须指定 `rollbackFor = Exception.class`
+
+### 编码规范
+- 所有 Java 文件使用 **UTF-8** 编码
+- 所有注释使用**中文**
+- 注释只写"为什么这样做"，不写"做了什么"
+
+---
+
+## 十一、文件流与特殊响应规范
+
+Controller **禁止**直接处理 `InputStream`/`OutputStream`，所有文件下载、预览、流式响应逻辑必须下沉到 Service 层：
+
+```java
+// ✅ Controller：只做透传
+@GetMapping("/{id}/download")
+public void download(@PathVariable Long id, HttpServletResponse response) {
+    fileService.download(id, response);  // 业务逻辑全在 Service
+}
+
+// ❌ Controller：手动设置响应头、读写流 —— 严格禁止
+@GetMapping("/{id}/download")
+public void download(@PathVariable Long id, HttpServletResponse response) throws Exception {
+    FileMetaRespVO meta = fileService.getFileMeta(id);
+    response.setContentType(meta.getMimeType()); // ❌ 业务逻辑泄露到 Controller
+    FileMetaDO do = fileService.getById(id);     // ❌ 双重查询
+    // ... 手动 byte[] 循环 ...               // ❌ 应用 StreamUtils.copy
+}
+```
+
+**Service 中文件流处理规范：**
+
+```java
+// ✅ 使用 StreamUtils.copy 替代手动 byte[] 循环
+try (InputStream in = storageService.download(path, bucket);
+     OutputStream out = response.getOutputStream()) {
+    StreamUtils.copy(in, out);   // org.springframework.util.StreamUtils
+    out.flush();
+} catch (IOException e) {
+    throw new SystemException(GlobalErrorCode.INTERNAL_SERVER_ERROR, "文件下载失败", e);
+}
+```
+
+---
+
+## 十二、常量管理规范
+
+业务域内使用的字符串常量（状态值、枚举码、策略标识等）必须集中定义到 `{域}Constants` 类，**禁止在 Service/Controller 中出现硬编码字符串常量**：
+
+```java
+// 位置：{业务模块}-api/src/main/java/com/.../api/constant/{域名}Constants.java
+public final class FsmConstants {
+    private FsmConstants() {}
+
+    // ==================== 服务名（供 Feign Client 引用） ====================
+    public static final String SERVICE_NAME = "nebula-fsm";
+
+    // ==================== RPC 路径前缀 ====================
+    public static final String URI_PREFIX = CommonConstants.RPC_URI_PREFIX + "/nebula/fsm";
+
+    // ==================== 业务枚举值 ====================
+    public static final String ACCESS_POLICY_PUBLIC  = "PUBLIC";
+    public static final String ACCESS_POLICY_PRIVATE = "PRIVATE";
+    public static final String UPLOAD_STATUS_COMPLETE   = "COMPLETE";
+    public static final String UPLOAD_STATUS_UPLOADING  = "UPLOADING";
+}
+```
+
+**常量类放置规则：**
+
+| 常量类型 | 放置位置 |
+|---------|---------|
+| 微服务 RPC 路径、服务名、业务枚举值 | `{业务模块}-api` 的 `constant/` 包下 |
+| 框架内部常量（不对外暴露） | `{业务模块}-core` 的 `constant/` 包下 |
+| 全局公共常量 | `nebula-framework-core` 的 `CommonConstants` |
+
+---
+
+## 十三、新业务模块开发检查清单
+
+- [ ] 在 `nebula-{domain}-server/src/main/resources/db/migration/` 创建 Flyway DDL 脚本
+- [ ] 在 `nebula-system` 迁移脚本中补充菜单和字典 DML（如需要）
+- [ ] 创建 `{业务名}DO`，继承 `BaseEntity`
+- [ ] 创建 `{业务名}Mapper`，继承 `BaseMapper<DO>`
+- [ ] 创建 `{业务名}MapperExt`（如需动态查询，将 `LambdaQueryWrapper` 放此处）
+- [ ] 创建 `{业务名}PageParamVO` 和 `{业务名}SaveParamVO`（含 `UpdateGroup`）
+- [ ] 创建 `{业务名}RespVO` 和 `{业务名}DetailVO`
+- [ ] 创建 `{业务名}Convert`，指定 `BaseMapperConfig`
+- [ ] 创建 `I{业务名}Service` 和 `{业务名}ServiceImpl`（实现类在 `service/impl/`）
+- [ ] 创建 `{业务名}Controller`，完成所有 REST 接口并添加 Swagger 注解
+- [ ] 验证 Swagger 文档（`/doc.html`）接口展示正常
+- [ ] 验证逻辑删除、多租户过滤是否生效
+- [ ] 业务常量是否已提取到 `{域}Constants` 常量类
+- [ ] 跨服务 RPC 接口是否按三件套规范实现（Constants + Feign Client + LocalStub）
+- [ ] 跨模块操作是否通过 Service 接口（不直接注入其他业务域的 Mapper）
+- [ ] 对外 VO / RPC DTO 是否不含存储内部字段（storagePath、bucketName 等）
+- [ ] DDL 是否包含 BaseEntity 完整 11 个公共字段（特别检查 `remark` 和 `custom_fields`）