adspecs 0.1.12

package/references/yudaocloud-end-standard/04-Java/345/220/216/347/253/257/347/274/226/347/240/201/350/247/204/350/214/203.md

@@ -0,0 +1,1095 @@
+# sie-cloud 项目 Java 后端编码规范
+
+> **版本**: v2.0
+> **修订日期**: 2026-05-16
+> **适用范围**: sie-cloud 项目所有 Java 后端模块
+
+本规范基于项目实际代码（sie-module-system、sie-module-infra、sie-module-wms）和 sie-framework 框架源码编写，可直接落地、团队通用。
+
+---
+
+## 一、项目约定
+
+### 1.1 技术栈
+
+| 组件                 | 版本     |
+| -------------------- | -------- |
+| Java                 | JDK 21   |
+| Spring Boot          | 3.5.13   |
+| Spring Cloud         | 2025.0.0 |
+| Spring Cloud Alibaba | 2025.0.0 |
+| MyBatis Plus         | 3.5.15   |
+| Redis + Redisson     | 3.52.0   |
+| Flowable             | 7.2.0    |
+| MapStruct            | 1.6.3    |
+| Knife4j              | 4.5.0    |
+| Lombok               | 1.18.42  |
+
+### 1.2 基础约定
+
+- **ID 类型**: 统一使用 `Long`（自增主键），不使用 UUID
+- **时间类型**: 统一使用 `LocalDateTime`，不使用 `Date`/`Instant`
+- **依赖注入**: 统一使用 `@Resource`（Jakarta），不使用 `@Autowired`
+- **对象命名**: DO（数据对象）替代 PO，继承 BaseDO/TenantBaseDO
+- **审计字段**: createTime/updateTime/creator/updater/deleted 由框架自动填充，无需手动维护
+- **对象转换**: 简单转换使用 `BeanUtils.toBean()`，复杂映射使用 MapStruct
+- **分页返回**: 使用 `PageResult<T>`，分页参数继承 `PageParam`
+- **异常抛出**: 使用 `ServiceExceptionUtil.exception(ErrorCodeConstants.XXX)`
+- **数据翻译**: 使用 `@TransMethodResult` + Easy-Trans 自动翻译关联字段
+- **租户隔离**: 使用 `TenantBaseDO` + 框架自动过滤，跨租户查询加 `@TenantIgnore`
+- **错误码段**: `1_XXX_YYY_ZZZ`（XXX 为模块编号，如 System=002, Infra=001, WMS=060）
+
+### 1.3 模块结构
+
+每个业务模块采用 `-api` + `-server` 双模块结构：
+
+```
+sie-module-xxx/
+├── sie-module-xxx-api/              # 跨模块 RPC 接口 + DTO + 枚举 + 错误码
+│   └── com.sie.cloud.module.xxx/
+│       ├── api/                     # @FeignClient 接口定义
+│       ├── dto/                     # RPC 传输 DTO
+│       └── enums/                   # ErrorCodeConstants、业务枚举
+└── sie-module-xxx-server/           # 服务实现
+    └── com.sie.cloud.module.xxx/
+        ├── controller/admin/        # 管理端 REST（自动添加 /admin-api 前缀）
+        │   └── {domain}/vo/         # VO 定义（按业务域子目录）
+        ├── controller/app/          # C 端 API（自动添加 /app-api 前缀）
+        ├── service/{domain}/        # Service 接口 + Impl
+        ├── dal/dataobject/{domain}/ # DO 实体
+        ├── dal/mysql/{domain}/      # MyBatis Plus Mapper
+        ├── convert/                 # MapStruct 转换器
+        ├── api/                     # RPC API 实现（@RestController）
+        └── framework/config/        # 模块配置（SecurityConfiguration 等）
+```
+
+---
+
+## 二、命名规范
+
+### 2.1 包名
+
+全部使用小写字母，单词之间用小数点分隔，禁止使用下划线、大写字母。
+
+格式：`com.sie.cloud.module.{module}.{layer}.{domain}`
+
+示例：
+- `com.sie.cloud.module.wms.controller.admin.warehouse`
+- `com.sie.cloud.module.wms.dal.dataobject`
+- `com.sie.cloud.module.wms.service.warehouse`
+- `com.sie.cloud.module.wms.dal.mysql`
+- `com.sie.cloud.module.wms.enums`
+
+### 2.2 类名
+
+采用大驼峰命名法，望文知意，后缀明确：
+
+| 类型             | 后缀                 | 示例                                         |
+| ---------------- | -------------------- | -------------------------------------------- |
+| Controller       | `Controller`         | `WmsWarehouseController`                     |
+| Service 接口     | `Service`            | `WmsWarehouseService`（不加 `I` 前缀）       |
+| Service 实现     | `ServiceImpl`        | `WmsWarehouseServiceImpl`                    |
+| Mapper           | `Mapper`             | `WmsWarehouseMapper`                         |
+| DO 实体          | `DO`                 | `WmsWarehouseDO`（继承 BaseDO/TenantBaseDO） |
+| 创建/更新请求    | `SaveReqVO`          | `WarehouseSaveReqVO`                         |
+| 分页查询请求     | `PageReqVO`          | `WarehousePageReqVO`                         |
+| 列表查询请求     | `ListReqVO`          | `DeptListReqVO`                              |
+| 响应对象         | `RespVO`             | `WarehouseRespVO`                            |
+| 精简响应         | `SimpleRespVO`       | `WarehouseSimpleRespVO`                      |
+| RPC DTO          | `ReqDTO` / `RespDTO` | `AdminUserRespDTO`（位于 -api 模块）         |
+| 枚举             | `Enum`               | `WmsOrgStatusEnum`                           |
+| MapStruct 转换器 | `Convert`            | `ConfigConvert`                              |
+
+### 2.3 方法名
+
+采用小驼峰命名法，以动词开头：
+
+| 操作     | 命名                                             | 示例                                             |
+| -------- | ------------------------------------------------ | ------------------------------------------------ |
+| 创建     | `create{Entity}`                                 | `createWarehouse`                                |
+| 更新     | `update{Entity}`                                 | `updateWarehouse`                                |
+| 删除     | `delete{Entity}`                                 | `deleteWarehouse`                                |
+| 批量删除 | `delete{Entity}List` / `delete{Entity}ListByIds` | `deleteWarehouseListByIds`                       |
+| 获得单个 | `get{Entity}`                                    | `getWarehouse`                                   |
+| 分页查询 | `get{Entity}Page`                                | `getWarehousePage`                               |
+| 列表查询 | `get{Entity}List`                                | `getSimpleList`                                  |
+| 状态修改 | `{action}{Entity}`                               | `enableWarehouse` / `disableWarehouse`           |
+| 校验方法 | `validate{Condition}`                            | `validateWarehouseExists` / `validateCodeUnique` |
+
+### 2.4 变量名
+
+采用小驼峰命名法，语义清晰，禁止拼音、单字母、无意义缩写。
+
+- 正确：`warehouseCode`、`createTime`、`orgId`
+- 错误：`a`、`abc`、`ckbm`、`czsj`
+
+### 2.5 常量名
+
+全部大写，单词之间用下划线分隔，集中定义在 `ErrorCodeConstants` 或常量类中，禁止魔法值。
+
+示例：`WAREHOUSE_NOT_EXISTS`、`MAX_PAGE_SIZE`
+
+---
+
+## 三、API 接口规范
+
+### 3.1 请求路径
+
+项目采用**路径动词风格**，不依赖 HTTP method 区分操作：
+
+| 操作     | 路径                          | HTTP Method |
+| -------- | ----------------------------- | ----------- |
+| 创建     | `/wms/warehouse/create`       | POST        |
+| 更新     | `/wms/warehouse/update`       | PUT         |
+| 删除     | `/wms/warehouse/delete`       | DELETE      |
+| 批量删除 | `/wms/warehouse/delete-list`  | DELETE      |
+| 获得单个 | `/wms/warehouse/get`          | GET         |
+| 分页查询 | `/wms/warehouse/page`         | GET         |
+| 列表查询 | `/wms/warehouse/list`         | GET         |
+| 导出     | `/wms/warehouse/export-excel` | GET         |
+| 其他操作 | `/wms/warehouse/{action}`     | PUT/GET     |
+
+路径规则：
+- 全部使用小写字母，单词之间用中横线分隔
+- `@RequestMapping("/wms/warehouse")` 不包含 `/admin-api` 或 `/app-api` 前缀
+- `controller/admin/` 下的类由框架自动添加 `/admin-api` 前缀
+- `controller/app/` 下的类自动添加 `/app-api` 前缀
+- Gateway 负责路由转发
+
+### 3.2 接口返回格式
+
+所有接口返回统一使用 `CommonResult<T>`：
+
+```java
+// 成功
+return success(data);                    // CommonResult<Long>
+return success(true);                    // CommonResult<Boolean>
+return success(BeanUtils.toBean(warehouse, WarehouseRespVO.class));  // CommonResult<WarehouseRespVO>
+return success(BeanUtils.toBean(pageResult, WarehouseRespVO.class)); // CommonResult<PageResult<WarehouseRespVO>>
+
+// 失败（通过框架全局异常处理自动返回）
+throw exception(WAREHOUSE_NOT_EXISTS);   // CommonResult.error(code, msg)
+```
+
+`CommonResult` 结构：
+- `code`（Integer）— 状态码，使用 `ErrorCode` 对象
+- `msg`（String）— 提示信息
+- `data`（T）— 业务数据
+
+### 3.3 错误码体系
+
+错误码定义在 `-api` 模块的 `ErrorCodeConstants` **接口**中：
+
+```java
+package com.sie.cloud.module.wms.enums;
+
+import com.sie.cloud.framework.common.exception.ErrorCode;
+
+public interface ErrorCodeConstants {
+
+    // ========== 仓库 1-060-003-000 ==========
+    ErrorCode WAREHOUSE_NOT_EXISTS = new ErrorCode(1_060_003_000, "仓库不存在");
+    ErrorCode WAREHOUSE_CODE_DUPLICATE = new ErrorCode(1_060_003_001, "仓库编码已存在");
+    ErrorCode WAREHOUSE_HAS_ZONES = new ErrorCode(1_060_003_002, "仓库下存在库区，不允许删除");
+}
+```
+
+格式：`1_XXX_YYY_ZZZ`（Java 下划线数字字面量）
+- `1` = 业务模块前缀
+- `XXX` = 模块编号（System=002, Infra=001, WMS=060, Coding=070, AI=040, BPM=003）
+- `YYY` = 子模块编号
+- `ZZZ` = 子模块内序号
+
+错误消息支持 `{}` 占位符：
+```java
+ErrorCode DEPT_ORG_CODE_DUPLICATE = new ErrorCode(1_002_004_008, "已经存在编码为【{}】的组织");
+// 使用：throw exception(DEPT_ORG_CODE_DUPLICATE, orgCode);
+```
+
+### 3.4 权限控制
+
+使用 `@PreAuthorize("@ss.hasPermission('module:resource:action')")`：
+
+```java
+@PreAuthorize("@ss.hasPermission('wms:warehouse:create')")   // 创建
+@PreAuthorize("@ss.hasPermission('wms:warehouse:update')")   // 修改
+@PreAuthorize("@ss.hasPermission('wms:warehouse:delete')")   // 删除
+@PreAuthorize("@ss.hasPermission('wms:warehouse:query')")    // 查询
+@PreAuthorize("@ss.hasPermission('wms:warehouse:export')")   // 导出
+```
+
+### 3.5 API 文档注解
+
+使用 SpringDoc（OpenAPI 3）注解：
+
+```java
+// Controller 类级别
+@Tag(name = "管理后台 - WMS 仓库")
+
+// 方法级别
+@Operation(summary = "创建仓库")
+
+// 参数级别
+@Parameter(name = "id", description = "编号", required = true, example = "1024")
+
+// VO 类级别
+@Schema(description = "管理后台 - WMS 仓库新增/修改 Request VO")
+
+// VO 字段级别
+@Schema(description = "仓库编码", requiredMode = Schema.RequiredMode.REQUIRED, example = "WH001")
+```
+
+---
+
+## 四、Controller 层规范
+
+### 4.1 标准写法
+
+```java
+package com.sie.cloud.module.wms.controller.admin.warehouse;
+
+import com.sie.cloud.framework.common.pojo.CommonResult;
+import com.sie.cloud.framework.common.pojo.PageResult;
+import com.sie.cloud.framework.common.util.object.BeanUtils;
+import com.sie.cloud.module.wms.controller.admin.vo.warehouse.WarehousePageReqVO;
+import com.sie.cloud.module.wms.controller.admin.vo.warehouse.WarehouseRespVO;
+import com.sie.cloud.module.wms.controller.admin.vo.warehouse.WarehouseSaveReqVO;
+import com.sie.cloud.module.wms.dal.dataobject.WmsWarehouseDO;
+import com.sie.cloud.module.wms.service.warehouse.WmsWarehouseService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.annotation.Resource;
+import jakarta.validation.Valid;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.validation.annotation.Validated;
+import org.springframework.web.bind.annotation.*;
+
+import static com.sie.cloud.framework.common.pojo.CommonResult.success;
+
+@Tag(name = "管理后台 - WMS 仓库")
+@RestController
+@RequestMapping("/wms/warehouse")
+@Validated
+public class WmsWarehouseController {
+
+    @Resource
+    private WmsWarehouseService warehouseService;
+
+    @PostMapping("/create")
+    @Operation(summary = "创建仓库")
+    @PreAuthorize("@ss.hasPermission('wms:warehouse:create')")
+    public CommonResult<Long> createWarehouse(@Valid @RequestBody WarehouseSaveReqVO createReqVO) {
+        return success(warehouseService.createWarehouse(createReqVO));
+    }
+
+    @PutMapping("/update")
+    @Operation(summary = "更新仓库")
+    @PreAuthorize("@ss.hasPermission('wms:warehouse:update')")
+    public CommonResult<Boolean> updateWarehouse(@Valid @RequestBody WarehouseSaveReqVO updateReqVO) {
+        warehouseService.updateWarehouse(updateReqVO);
+        return success(true);
+    }
+
+    @DeleteMapping("/delete")
+    @Operation(summary = "删除仓库")
+    @Parameter(name = "id", description = "编号", required = true)
+    @PreAuthorize("@ss.hasPermission('wms:warehouse:delete')")
+    public CommonResult<Boolean> deleteWarehouse(@RequestParam("id") Long id) {
+        warehouseService.deleteWarehouse(id);
+        return success(true);
+    }
+
+    @GetMapping("/get")
+    @Operation(summary = "获得仓库")
+    @Parameter(name = "id", description = "编号", required = true, example = "1024")
+    @PreAuthorize("@ss.hasPermission('wms:warehouse:query')")
+    public CommonResult<WarehouseRespVO> getWarehouse(@RequestParam("id") Long id) {
+        WmsWarehouseDO warehouse = warehouseService.getWarehouse(id);
+        return success(BeanUtils.toBean(warehouse, WarehouseRespVO.class));
+    }
+
+    @GetMapping("/page")
+    @Operation(summary = "获得仓库分页")
+    @PreAuthorize("@ss.hasPermission('wms:warehouse:query')")
+    public CommonResult<PageResult<WarehouseRespVO>> getWarehousePage(@Valid WarehousePageReqVO pageReqVO) {
+        PageResult<WmsWarehouseDO> pageResult = warehouseService.getWarehousePage(pageReqVO);
+        return success(BeanUtils.toBean(pageResult, WarehouseRespVO.class));
+    }
+}
+```
+
+### 4.2 禁止事项
+
+1. 禁止在 Controller 层编写任何业务逻辑（参数处理、数据转换、数据库操作）
+2. 禁止直接返回 `Map`、`Object`、`List` 等未封装对象，必须使用 `CommonResult`
+3. 禁止不做参数校验（POST/PUT 必须加 `@Valid @RequestBody`，GET 加 `@Valid`）
+4. 禁止使用 `@Autowired` 注入，统一使用 `@Resource`
+5. 禁止接口路径包含 `/admin-api` 或 `/app-api` 前缀（由框架自动添加）
+
+---
+
+## 五、Service 层规范
+
+### 5.1 接口与实现分离
+
+```java
+// Service 接口（不加注解）
+public interface WmsWarehouseService {
+
+    Long createWarehouse(WarehouseSaveReqVO createReqVO);
+
+    void updateWarehouse(WarehouseSaveReqVO updateReqVO);
+
+    void deleteWarehouse(Long id);
+
+    WmsWarehouseDO getWarehouse(Long id);
+
+    PageResult<WmsWarehouseDO> getWarehousePage(WarehousePageReqVO pageReqVO);
+}
+
+// Service 实现类
+@Service
+@Validated
+@Slf4j
+public class WmsWarehouseServiceImpl implements WmsWarehouseService {
+
+    @Resource
+    private WmsWarehouseMapper warehouseMapper;
+
+    @Override
+    public Long createWarehouse(WarehouseSaveReqVO createReqVO) {
+        validateCodeUnique(null, createReqVO.getCode());
+        WmsWarehouseDO warehouse = BeanUtils.toBean(createReqVO, WmsWarehouseDO.class);
+        warehouseMapper.insert(warehouse);
+        return warehouse.getId();
+    }
+
+    @Override
+    public void updateWarehouse(WarehouseSaveReqVO updateReqVO) {
+        validateExists(updateReqVO.getId());
+        validateCodeUnique(updateReqVO.getId(), updateReqVO.getCode());
+        WmsWarehouseDO updateObj = BeanUtils.toBean(updateReqVO, WmsWarehouseDO.class);
+        warehouseMapper.updateById(updateObj);
+    }
+
+    @Override
+    public void deleteWarehouse(Long id) {
+        WmsWarehouseDO warehouse = validateExists(id);
+        if (!WmsOrgStatusEnum.PENDING.getStatus().equals(warehouse.getStatus())) {
+            throw exception(WAREHOUSE_STATUS_INVALID);
+        }
+        warehouseMapper.deleteById(id);
+    }
+
+    @Override
+    public WmsWarehouseDO getWarehouse(Long id) {
+        return warehouseMapper.selectById(id);
+    }
+
+    @Override
+    public PageResult<WmsWarehouseDO> getWarehousePage(WarehousePageReqVO pageReqVO) {
+        return warehouseMapper.selectPage(pageReqVO, new LambdaQueryWrapperX<WmsWarehouseDO>()
+                .likeIfPresent(WmsWarehouseDO::getCode, pageReqVO.getCode())
+                .likeIfPresent(WmsWarehouseDO::getName, pageReqVO.getName())
+                .eqIfPresent(WmsWarehouseDO::getOrgId, pageReqVO.getOrgId())
+                .orderByDesc(WmsWarehouseDO::getId));
+    }
+
+    // ====== 私有校验方法 ======
+
+    private WmsWarehouseDO validateExists(Long id) {
+        WmsWarehouseDO warehouse = warehouseMapper.selectById(id);
+        if (warehouse == null) {
+            throw exception(WAREHOUSE_NOT_EXISTS);
+        }
+        return warehouse;
+    }
+
+    private void validateCodeUnique(Long id, String code) {
+        WmsWarehouseDO warehouse = warehouseMapper.selectOne(WmsWarehouseDO::getCode, code);
+        if (warehouse == null) return;
+        if (id == null || !id.equals(warehouse.getId())) {
+            throw exception(WAREHOUSE_CODE_DUPLICATE);
+        }
+    }
+}
+```
+
+**关键约定**：
+- Service 方法直接接收 `SaveReqVO`/`PageReqVO`，返回 `DO` 对象（不是 RespVO）
+- Controller 层负责 DO → RespVO 转换
+- 接口无需注解，实现类加 `@Service` + `@Validated` + `@Slf4j`
+- 私有校验方法使用 `throw exception(ErrorCodeConstants.XXX)` 抛出异常
+
+### 5.2 事务管理
+
+- 涉及多表操作的方法加 `@Transactional(rollbackFor = Exception.class)`
+- 单表 CRUD 不需要事务注解
+- 主子表场景下代码生成器自动添加事务注解
+
+### 5.3 禁止事项
+
+1. 禁止 Service 层直接接收 HTTP 请求、返回响应
+2. 禁止 Service 层跳过 Mapper 层直接编写 SQL 操作数据库
+3. 禁止未加事务注解的多表修改操作
+4. 禁止手动设置审计字段（createTime/updateTime 等由框架自动填充）
+
+---
+
+## 六、Mapper/数据库规范
+
+### 6.1 Mapper 接口
+
+```java
+package com.sie.cloud.module.wms.dal.mysql;
+
+import com.sie.cloud.framework.mybatis.core.mapper.BaseMapperX;
+import com.sie.cloud.module.wms.dal.dataobject.WmsWarehouseDO;
+import org.apache.ibatis.annotations.Mapper;
+
+import java.util.List;
+
+@Mapper
+public interface WmsWarehouseMapper extends BaseMapperX<WmsWarehouseDO> {
+
+    default List<WmsWarehouseDO> selectListByOrgId(Long orgId) {
+        return selectList(WmsWarehouseDO::getOrgId, orgId);
+    }
+
+    default Long selectCountByOrgId(Long orgId) {
+        return selectCount(WmsWarehouseDO::getOrgId, orgId);
+    }
+}
+```
+
+**关键约定**：
+- 继承 `BaseMapperX<DO>`（扩展自 `MPJBaseMapper<T>`，支持 MyBatis Plus Join）
+- 接口加 `@Mapper` 注解
+- 位于 `dal/mysql/{domain}/` 目录
+- 自定义方法使用 `default` 方法 + `LambdaQueryWrapperX` 链式 API
+
+### 6.2 LambdaQueryWrapperX 链式 API
+
+优先使用 `LambdaQueryWrapperX`，不手写 SQL：
+
+```java
+default PageResult<ConfigDO> selectPage(ConfigPageReqVO reqVO) {
+    return selectPage(reqVO, new LambdaQueryWrapperX<ConfigDO>()
+            .likeIfPresent(ConfigDO::getConfigName, reqVO.getConfigName())
+            .eqIfPresent(ConfigDO::getConfigKey, reqVO.getConfigKey())
+            .eqIfPresent(ConfigDO::getType, reqVO.getType())
+            .betweenIfPresent(ConfigDO::getCreateTime, reqVO.getCreateTime())
+            .orderByDesc(ConfigDO::getId));
+}
+```
+
+常用条件方法：
+
+| 方法                                                    | 说明                         |
+| ------------------------------------------------------- | ---------------------------- |
+| `likeIfPresent(column, value)`                          | 模糊匹配（值非空时才加条件） |
+| `eqIfPresent(column, value)`                            | 精确匹配                     |
+| `betweenIfPresent(column, val1, val2)`                  | 区间匹配                     |
+| `inIfPresent(column, collection)`                       | IN 匹配                      |
+| `neIfPresent(column, value)`                            | 不等匹配                     |
+| `gtIfPresent / geIfPresent / ltIfPresent / leIfPresent` | 大小写比较                   |
+| `orderByDesc(column)`                                   | 降序排序                     |
+| `orderByAsc(column)`                                    | 升序排序                     |
+
+### 6.3 BaseMapperX 内置方法
+
+| 方法                                        | 说明                                     |
+| ------------------------------------------- | ---------------------------------------- |
+| `selectOne(field, value)`                   | 单字段精确查询，返回一条                 |
+| `selectOne(field1, value1, field2, value2)` | 多字段精确查询                           |
+| `selectCount(field, value)`                 | 计数查询                                 |
+| `selectList(field, value)`                  | 单字段列表查询                           |
+| `selectList(Wrapper)`                       | Wrapper 条件查询                         |
+| `selectPage(PageParam, Wrapper)`            | 分页查询，支持 `PAGE_SIZE_NONE` 返回全部 |
+| `insert(entity)`                            | 插入单条                                 |
+| `insertBatch(Collection)`                   | 批量插入                                 |
+| `updateById(entity)`                        | 根据 ID 更新                             |
+| `updateBatch(Collection)`                   | 批量更新                                 |
+| `deleteById(id)`                            | 根据 ID 删除                             |
+| `deleteBatch(Collection)`                   | 批量删除                                 |
+
+### 6.4 DO 实体
+
+```java
+package com.sie.cloud.module.wms.dal.dataobject;
+
+import com.sie.cloud.framework.tenant.core.db.TenantBaseDO;
+import com.baomidou.mybatisplus.annotation.KeySequence;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import lombok.*;
+
+@TableName("wms_warehouse")
+@KeySequence("wms_warehouse_seq")
+@Data
+@EqualsAndHashCode(callSuper = true)
+@ToString(callSuper = true)
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+public class WmsWarehouseDO extends TenantBaseDO {
+
+    @TableId
+    private Long id;
+    private String code;
+    private String name;
+    private Long orgId;
+    // 其他字段... 不需要 @TableField，MyBatis Plus 自动驼峰转下划线
+}
+```
+
+**关键约定**：
+- 命名：`{Entity}DO`，位于 `dal/dataobject/{domain}/` 目录
+- 基类：`BaseDO`（标准）或 `TenantBaseDO`（多租户）
+- 字段默认使用 camelCase，MyBatis Plus 自动映射为 snake_case，**不需要 `@TableField`**
+- 审计字段（createTime/updateTime/creator/updater/deleted）由 `BaseDO` 基类提供
+- 多租户字段（tenantId）由 `TenantBaseDO` 基类提供,需用引用`
+import com.sie.cloud.framework.tenant.core.db.TenantBaseDO;`
+
+### 6.5 BaseDO 提供的字段
+
+| 字段         | 类型            | 说明                                         |
+| ------------ | --------------- | -------------------------------------------- |
+| `createTime` | `LocalDateTime` | `@TableField(fill = INSERT)` 自动填充        |
+| `updateTime` | `LocalDateTime` | `@TableField(fill = INSERT_UPDATE)` 自动填充 |
+| `creator`    | `String`        | `@TableField(fill = INSERT)` 自动填充        |
+| `updater`    | `String`        | `@TableField(fill = INSERT_UPDATE)` 自动填充 |
+| `deleted`    | `Boolean`       | `@TableLogic` 逻辑删除                       |
+
+### 6.6 TenantBaseDO 提供的字段
+
+`TenantBaseDO` 继承自 `BaseDO`，额外提供以下字段：
+
+| 字段       | 类型   | 说明                                                       |
+| ---------- | ------ | ---------------------------------------------------------- |
+| `tenantId` | `Long` | 租户编号，框架自动填充并过滤，跨租户查询加 `@TenantIgnore` |
+
+需要多租户隔离的 DO 继承 `TenantBaseDO`，引入路径：
+
+```java
+import com.sie.cloud.framework.tenant.core.db.TenantBaseDO;
+```
+
+### 6.7 数据库表规范
+
+- 表名：小写字母 + 下划线，语义清晰，如 `wms_warehouse`、`system_dept`
+- 字段名：小写字母 + 下划线，与 DO 实体 camelCase 对应
+- 主键：`id`（`BIGINT` 自增）
+- 不需要手动定义 `create_time`、`update_time`、`is_deleted` 字段（由 BaseDO 管理）
+
+### 6.7 SQL 规范
+
+- 优先使用 `LambdaQueryWrapperX` 链式 API，不手写 SQL
+- 复杂 SQL（JOIN、子查询、聚合）才使用 XML Mapper
+- XML 文件位于 `src/main/resources/mapper/{domain}/` 目录
+- 逻辑删除由 `@TableLogic` 自动处理，无需手动加 `WHERE deleted = 0`
+
+---
+
+## 七、VO 规范
+
+### 7.1 VO 分类
+
+| 类型         | 命名                   | 用途                                        | 继承        | 校验                       |
+| ------------ | ---------------------- | ------------------------------------------- | ----------- | -------------------------- |
+| SaveReqVO    | `{Entity}SaveReqVO`    | 创建/更新（id=null 为创建，非 null 为更新） | 无          | `@NotBlank`、`@NotNull` 等 |
+| PageReqVO    | `{Entity}PageReqVO`    | 分页查询                                    | `PageParam` | 无                         |
+| ListReqVO    | `{Entity}ListReqVO`    | 列表查询（不分页）                          | 无          | 无                         |
+| RespVO       | `{Entity}RespVO`       | 响应展示                                    | 无          | 无                         |
+| SimpleRespVO | `{Entity}SimpleRespVO` | 精简响应（下拉列表）                        | 无          | 无                         |
+
+### 7.2 SaveReqVO 示例
+
+```java
+package com.sie.cloud.module.wms.controller.admin.vo.warehouse;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.NotNull;
+import lombok.Data;
+
+@Schema(description = "管理后台 - WMS 仓库新增/修改 Request VO")
+@Data
+public class WarehouseSaveReqVO {
+
+    @Schema(description = "仓库编号", example = "1024")
+    private Long id;
+
+    @Schema(description = "仓库编码", requiredMode = Schema.RequiredMode.REQUIRED, example = "WH001")
+    @NotBlank(message = "仓库编码不能为空")
+    private String code;
+
+    @Schema(description = "仓库名称", requiredMode = Schema.RequiredMode.REQUIRED, example = "华东主仓")
+    @NotBlank(message = "仓库名称不能为空")
+    private String name;
+
+    @Schema(description = "所属库存组织编号", requiredMode = Schema.RequiredMode.REQUIRED, example = "1")
+    @NotNull(message = "所属库存组织不能为空")
+    private Long orgId;
+}
+```
+
+### 7.3 PageReqVO 示例
+
+```java
+package com.sie.cloud.module.wms.controller.admin.vo.warehouse;
+
+import com.sie.cloud.framework.common.pojo.PageParam;
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Data;
+import org.springframework.format.annotation.DateTimeFormat;
+import java.time.LocalDateTime;
+
+import static com.sie.cloud.framework.common.util.date.DateUtils.FORMAT_YEAR_MONTH_DAY_HOUR_MINUTE_SECOND;
+
+@Schema(description = "管理后台 - WMS 仓库分页 Request VO")
+@Data
+public class WarehousePageReqVO extends PageParam {
+
+    @Schema(description = "仓库编码", example = "WH001")
+    private String code;
+
+    @Schema(description = "仓库名称", example = "华东主仓")
+    private String name;
+
+    @Schema(description = "所属库存组织编号", example = "1")
+    private Long orgId;
+
+    @Schema(description = "创建时间")
+    @DateTimeFormat(pattern = FORMAT_YEAR_MONTH_DAY_HOUR_MINUTE_SECOND)
+    private LocalDateTime[] createTime;
+}
+```
+
+### 7.4 RespVO 示例
+
+```java
+package com.sie.cloud.module.wms.controller.admin.vo.warehouse;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Data;
+import java.time.LocalDateTime;
+
+@Schema(description = "管理后台 - WMS 仓库 Response VO")
+@Data
+public class WarehouseRespVO {
+
+    @Schema(description = "仓库编号", example = "1024")
+    private Long id;
+
+    @Schema(description = "仓库编码", example = "WH001")
+    private String code;
+
+    @Schema(description = "仓库名称", example = "华东主仓")
+    private String name;
+
+    @Schema(description = "所属库存组织编号", example = "1")
+    private Long orgId;
+
+    @Schema(description = "状态", example = "1")
+    private Integer status;
+
+    @Schema(description = "创建时间", example = "2026-01-01 00:00:00")
+    private LocalDateTime createTime;
+}
+```
+
+### 7.5 VO 位置
+
+位于 `controller/admin/{domain}/vo/{domain}/` 下，按业务域组织子目录。
+
+### 7.6 DTO 与 VO 的区分
+
+- **VO**：前端接口使用，位于 `-server` 模块的 `controller/admin/{domain}/vo/`
+- **DTO**：跨模块 RPC 调用使用，位于 `-api` 模块的 `dto/{domain}/`
+- 前端接口不使用 DTO，跨模块调用不使用 VO
+
+---
+
+## 八、对象转换规范
+
+### 8.1 BeanUtils.toBean()
+
+项目统一使用 `BeanUtils.toBean()`（基于 Hutool `BeanUtil`）：
+
+```java
+import static com.sie.cloud.framework.common.util.object.BeanUtils.toBean;
+
+// 单对象转换
+WmsWarehouseDO warehouse = warehouseMapper.selectById(id);
+return success(toBean(warehouse, WarehouseRespVO.class));
+
+// 分页转换（自动保留 total）
+PageResult<WmsWarehouseDO> pageResult = warehouseMapper.selectPage(pageReqVO);
+return success(toBean(pageResult, WarehouseRespVO.class));
+
+// List 转换
+List<WmsWarehouseDO> list = warehouseMapper.selectList(reqVO);
+return success(toBean(list, WarehouseRespVO.class));
+
+// 带回调的转换
+return success(toBean(warehouse, WarehouseRespVO.class, vo -> {
+    vo.setExtraInfo("computed value");
+}));
+```
+
+### 8.2 MapStruct 转换器
+
+复杂映射使用 MapStruct，位于 `convert/` 目录：
+
+```java
+@Mapper
+public interface ConfigConvert {
+    ConfigConvert INSTANCE = Mappers.getMapper(ConfigConvert.class);
+
+    ConfigDO convert(ConfigSaveReqVO bean);
+    ConfigRespVO convert(ConfigDO bean);
+}
+```
+
+---
+
+## 九、枚举规范
+
+### 9.1 简单枚举
+
+不需要参数校验的枚举，普通定义即可：
+
+```java
+@Getter
+@AllArgsConstructor
+public enum RoleTypeEnum {
+    SYSTEM(1),
+    CUSTOM(2);
+    private final Integer type;
+}
+```
+
+### 9.2 ArrayValuable 枚举
+
+需要用于 `@InEnum` 参数校验的枚举：
+
+```java
+package com.sie.cloud.module.wms.enums;
+
+import com.sie.cloud.framework.common.core.ArrayValuable;
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+
+import java.util.Arrays;
+
+@Getter
+@AllArgsConstructor
+public enum WmsOrgStatusEnum implements ArrayValuable<Integer> {
+
+    PENDING(0, "待启用"),
+    ENABLED(1, "已启用"),
+    DISABLED(2, "已停用");
+
+    public static final Integer[] ARRAYS = Arrays.stream(values())
+            .map(WmsOrgStatusEnum::getStatus).toArray(Integer[]::new);
+
+    private final Integer status;
+    private final String name;
+
+    @Override
+    public Integer[] array() {
+        return ARRAYS;
+    }
+}
+```
+
+### 9.3 @InEnum 校验
+
+在 VO 字段上使用 `@InEnum` 进行枚举值校验：
+
+```java
+@InEnum(WmsOrgStatusEnum.class)
+@Schema(description = "状态", example = "1")
+private Integer status;
+```
+
+枚举位于 `-api` 模块的 `enums/` 目录下。
+
+---
+
+## 十、参数校验规范
+
+### 10.1 Controller 校验
+
+- Controller 类加 `@Validated` 注解
+- POST/PUT 方法参数加 `@Valid @RequestBody`
+- GET 方法参数加 `@Valid`（不加 @RequestBody）
+
+### 10.2 常用校验注解
+
+来自 `jakarta.validation.constraints`：
+
+| 注解                       | 说明                                             |
+| -------------------------- | ------------------------------------------------ |
+| `@NotBlank`                | 字符串非空（禁止空白字符）                       |
+| `@NotNull`                 | 对象非空（用于 Integer、Long、LocalDateTime 等） |
+| `@NotEmpty`                | 字符串/集合非空                                  |
+| `@Size(min = N, max = M)`  | 长度限制                                         |
+| `@Email`                   | 邮箱格式                                         |
+| `@Pattern(regexp = "...")` | 正则校验                                         |
+| `@InEnum(XxxEnum.class)`   | 枚举值校验                                       |
+
+### 10.3 时间参数
+
+项目统一使用 `LocalDateTime`，JSON 序列化由框架全局配置处理，**无需在字段上加 `@JsonFormat`**。
+
+PageReqVO 中的时间区间查询：
+```java
+@DateTimeFormat(pattern = FORMAT_YEAR_MONTH_DAY_HOUR_MINUTE_SECOND)
+private LocalDateTime[] createTime;
+```
+
+---
+
+## 十一、异常规范
+
+### 11.1 全局异常处理
+
+全局异常处理由 `sie-starter-web` 的 `GlobalExceptionHandler` 统一提供（`@RestControllerAdvice`），业务模块**无需手写**。
+
+框架已处理的异常：
+- 参数校验异常（`MethodArgumentNotValidException`、`BindException` 等）→ 400
+- 业务异常（`ServiceException`）→ 返回 `CommonResult.error(code, msg)`
+- 权限异常（`AccessDeniedException`）→ 403
+- 资源不存在（`NoHandlerFoundException`）→ 404
+- 兜底异常（`Exception`）→ 500，自动记录错误日志
+
+### 11.2 业务异常抛出
+
+使用 `ServiceExceptionUtil.exception()` 通过静态导入抛出：
+
+```java
+import static com.sie.cloud.framework.common.exception.util.ServiceExceptionUtil.exception;
+import static com.sie.cloud.module.wms.enums.ErrorCodeConstants.*;
+
+// 简单抛出
+throw exception(WAREHOUSE_NOT_EXISTS);
+
+// 带占位符参数
+throw exception(WAREHOUSE_CODE_DUPLICATE, code);
+```
+
+### 11.3 异常分类
+
+| 类型         | 处理方式                                        |
+| ------------ | ----------------------------------------------- |
+| 业务异常     | `throw exception(ErrorCodeConstants.XXX)`       |
+| 参数校验异常 | `@Valid` + `@Validated`，框架自动捕获并返回 400 |
+| 系统异常     | 框架兜底返回 500，自动记录错误日志              |
+
+### 11.4 禁止事项
+
+1. 禁止手写 `GlobalExceptionHandler`（框架已提供）
+2. 禁止手写 `ServiceException extends RuntimeException`（框架已提供 `ServiceExceptionUtil`）
+3. 禁止使用 `try-catch` 捕获所有异常（仅捕获特定异常，兜底异常交给全局处理）
+4. 禁止抛出 `Exception`、`RuntimeException` 等通用异常
+
+---
+
+## 十二、多租户开发规范
+
+### 12.1 实体层
+
+- 需要租户隔离的 DO 继承 `TenantBaseDO`（自动获得 `tenantId` 字段）
+- 不需要租户隔离的 DO 继承 `BaseDO`，并在类上加 `@TenantIgnore` 注解：
+
+```java
+@TenantIgnore
+@TableName("infra_config")
+@Data
+@EqualsAndHashCode(callSuper = true)
+public class ConfigDO extends BaseDO {
+    // ...
+}
+```
+
+### 12.2 查询层
+
+- 框架自动在 SQL 中追加 `tenant_id = ?` 条件，无需手动添加
+- 跨租户查询：在 Service 方法上加 `@TenantIgnore` 注解
+
+---
+
+## 十三、跨模块 RPC 调用规范
+
+### 13.1 Feign Client 定义（-api 模块）
+
+```java
+package com.sie.cloud.module.system.api.user;
+
+import com.sie.cloud.framework.common.pojo.CommonResult;
+import org.springframework.cloud.openfeign.FeignClient;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+
+@FeignClient(name = ApiConstants.NAME, path = ApiConstants.PREFIX + "/user")
+public interface AdminUserApi {
+
+    @GetMapping("/get")
+    CommonResult<AdminUserRespDTO> getUser(@RequestParam("id") Long id);
+}
+```
+
+### 13.2 RPC API 实现（-server 模块）
+
+```java
+package com.sie.cloud.module.system.api.user;
+
+import com.sie.cloud.framework.common.pojo.CommonResult;
+import com.sie.cloud.module.system.api.user.dto.AdminUserRespDTO;
+import com.sie.cloud.module.system.service.user.AdminUserService;
+import jakarta.annotation.Resource;
+import org.springframework.web.bind.annotation.RestController;
+
+import static com.sie.cloud.framework.common.util.object.BeanUtils.toBean;
+import static com.sie.cloud.framework.common.pojo.CommonResult.success;
+
+@RestController
+public class AdminUserApiImpl implements AdminUserApi {
+
+    @Resource
+    private AdminUserService adminUserService;
+
+    @Override
+    public CommonResult<AdminUserRespDTO> getUser(Long id) {
+        return success(toBean(adminUserService.getUser(id), AdminUserRespDTO.class));
+    }
+}
+```
+
+### 13.3 DTO 定义
+
+- 位于 `-api` 模块的 `dto/{domain}/` 目录
+- 命名以 `RespDTO` / `ReqDTO` 结尾
+- 不包含 VO 特有的 `@Schema`、校验注解等
+
+---
+
+## 十四、测试规范
+
+### 14.1 测试基类
+
+- DB 单元测试：继承 `BaseDbUnitTest`（使用 H2 内存数据库）
+- 需要 Redis 的测试：继承 `BaseDbAndRedisUnitTest`（使用 jedis-mock）
+
+### 14.2 测试类模板
+
+```java
+package com.sie.cloud.module.wms.service.warehouse;
+
+import com.sie.cloud.framework.test.core.ut.BaseDbUnitTest;
+import jakarta.annotation.Resource;
+import org.junit.jupiter.api.Test;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.test.context.ActiveProfiles;
+import org.springframework.test.context.jdbc.Sql;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.NONE, classes = BaseDbUnitTest.Application.class)
+@ActiveProfiles("unit-test")
+@Sql(scripts = "/sql/clean.sql", executionPhase = Sql.ExecutionPhase.AFTER_TEST_METHOD)
+class WmsWarehouseServiceImplTest extends BaseDbUnitTest {
+
+    @Resource
+    private WmsWarehouseServiceImpl warehouseService;
+
+    @Test
+    void testCreateWarehouse_success() {
+        // given
+        WarehouseSaveReqVO reqVO = new WarehouseSaveReqVO();
+        reqVO.setCode("WH001");
+        reqVO.setName("华东主仓");
+        // when
+        Long id = warehouseService.createWarehouse(reqVO);
+        // then
+        assertNotNull(id);
+    }
+}
+```
+
+### 14.3 测试 SQL
+
+- 创建表脚本：`src/test/resources/sql/create_tables.sql`
+- 清理脚本：`src/test/resources/sql/clean.sql`（每个测试方法执行后运行）
+
+### 14.4 测试方法命名
+
+`test{Method}_{Scenario}`，如 `testCreateWarehouse_success`、`testCreateWarehouse_codeDuplicate`
+
+---
+
+## 十五、注释规范
+
+### 15.1 类注释
+
+- DO 类：代码生成器自动生成 `/** ... */` Javadoc 包含 `@author`
+- 手写类：简洁注释说明作用即可，不强制 `@author` / `@date`
+
+### 15.2 方法注释
+
+- 公共方法：简洁的 `// 说明` 注释或单行 Javadoc
+- 复杂业务逻辑方法：详细 Javadoc（方法作用、参数说明、返回值）
+
+### 15.3 字段注释
+
+- VO 字段：使用 `@Schema(description = "...")` 替代 Javadoc
+- DO 字段：使用 `/** ... */` Javadoc 说明含义
+
+### 15.4 禁止事项
+
+1. 禁止无意义注释（如 `// 这里是循环`）
+2. 禁止注释与代码不一致
+3. 禁止使用拼音注释
+
+---
+
+## 十六、代码风格规范
+
+1. **缩进**: 统一使用 4 个空格，禁止 Tab
+2. **大括号**: 左大括号紧跟语句末尾，右大括号单独成行
+3. **空行**: 方法之间、类成员之间空一行，逻辑块之间空一行
+4. **魔法值**: 禁止直接写数字、字符串，需定义为常量或枚举
+5. **集合初始化**: 指定大小（如 `new ArrayList<>(10)`）
+6. **空判断**: 使用 `ObjectUtil.isNull()` / `CollUtil.isEmpty()`（Hutool 工具类）
+7. **代码简洁**: 禁止冗余代码，复杂逻辑拆分方法
+8. **命名统一**: 同一含义的字段、方法，命名必须统一
+
+---
+
+## 十七、代码生成器
+
+`sie-module-infra` 提供代码生成器（codegen），可生成：
+- Controller、Service、Mapper、DO、VO（SaveReqVO/PageReqVO/ListReqVO/RespVO）
+- 单元测试类、SQL 脚本
+- 前端代码（Vue2 Element UI、Vue3 Element Plus、Vue3 Vben5 等）
+
+使用方式：管理后台 `/admin-api/infra/codegen/` 或 API 调用。
+
+生成的代码已遵循本规范中的所有约定。生成的错误码常量需手动补充到 `ErrorCodeConstants` 中。
+
+---
+
+## 十八、开发标准流程
+
+1. **需求分析**: 明确功能、入参、出参、业务逻辑
+2. **定义 VO**: 编写 SaveReqVO（含校验）、PageReqVO、RespVO
+3. **定义 DO**: 在 `dal/dataobject/` 下创建实体，继承 BaseDO/TenantBaseDO
+4. **定义 Mapper**: 在 `dal/mysql/` 下创建接口，继承 BaseMapperX
+5. **定义 Service**: 接口 + Impl，实现业务逻辑
+6. **定义 Controller**: 定义接口路径、请求方法、权限注解，调用 Service
+7. **定义错误码**: 在 `ErrorCodeConstants` 中补充业务错误码
+8. **单元测试**: 编写测试用例，覆盖正常流程和异常场景
+9. **联调测试**: 测试接口是否正常、参数校验是否生效、异常是否正确返回