DMS 代码编写规范（完整版）

1. 适用范围

• 适用于 DMS 全部 Java 服务与模块：wpglb-dms-admin、wpglb-dms-service、wpglb-dms-lms-service、wpglb-dms-driver-service、wpglb-dms-exporter-service、wpglb-dms-task、wpglb-dms-security-gateway、wpglb-dms-service-api、wpglb-dms-commons、wpglb-dms-tool。
• 适用于新增代码、重构代码、AI 生成代码、人工编写代码。

2. 技术与语言边界（强制）

1. 仅允许使用 Java 语言开发业务代码。
2. 统一基于 OpenJDK 17 编译与运行。
3. 禁止输出、提交或运行 C# 代码。
4. 新增依赖必须与 Java 17 兼容，并遵循现有 Maven 依赖体系。

3. 分层与模块职责

1. controller：仅处理请求参数、权限校验、调用服务、返回结果，不写核心业务。
2. service/service.impl：承载业务逻辑、事务边界、跨组件编排。
3. mapper：仅做数据访问，不做业务编排。
4. service-api：只放接口契约（Feign/DTO/VO），不放实现。
5. 公共能力必须优先沉淀在 dms-common 或 wpglb-dms-tool 对应模块。

4. 命名规范

1. 包名全小写，按业务域分层。
2. 类名大驼峰，方法/字段小驼峰。
3. 常量全大写下划线，常量类统一以 Constant 结尾。
4. DTO/VO/Query/Enum 命名统一为：XxxDTO、XxxVO、XxxQuery、XxxEnum。

5. 实体与数据库规范（MyBatis-Plus）

1. 实体类与数据库表名保持语义一致，类名使用大驼峰。
2. 所有 Entity 必须继承 BasePO.java。
3. 主键统一使用：
   @TableId(value = "xx_id", type = IdType.ASSIGN_ID)。
4. 字段与数据库列映射必须使用 @TableField。
5. 禁止在 Entity 中编写业务逻辑。

6. 接口与返回规范

1. 使用 @RequestBody 时，前端必须使用 application/json。
2. 接口返回统一使用 R<T> 封装，禁止直接返回原始对象。
3. 接口文档必须补齐 Swagger 注解（如 @Operation、@Schema）。
4. 业务接口必须提供批量接口（新增/更新/删除至少提供 batch 版本）。

7. 分页与动态查询规范（强制）

1. 所有分页查询必须基于 DynamicConditionUtil 转换器。
2. 禁止手写重复查询条件拼装逻辑。
3. Controller 不允许拼接复杂查询逻辑，统一下沉到 Service。
4. 复杂条件如需扩展，必须封装统一转换方法，禁止散落实现。

8. DTO/VO/Query 与参数校验

1. DTO 用于写入，VO 用于输出，Query 用于查询条件。
2. Controller 入参必须使用 @Valid/@Validated 进行校验。
3. 禁止直接使用 Entity 作为对外接口入参/出参（特殊情况需评审）。

9. 异常与错误码规范

1. 所有业务异常统一抛出 ServiceException。
2. 异常码统一维护在 DmsErrorEnum，由各项目自行维护本域错误码。
3. 异常信息要求可读、可定位，不暴露敏感底层信息。

10. 枚举与字典规范

1. 字典值统一写入 Enum。
2. 所有字典 Enum 必须包含 getCode() 和 getDesc() 方法。
3. 禁止在代码中使用魔法值。

11. 数据访问与性能规范（强制）

1. insert、update、delete 必须优先批量实现。
2. 禁止循环写入数据库（禁止 for/while/stream + insert/update/delete）。
3. 禁止循环查询数据库（禁止 for/while/stream + select，避免 N+1）。
4. 需要批量场景时，必须使用批量 SQL、IN 查询、关联查询或预加载映射。
5. 批量操作需控制分批大小并保证事务一致性。

12. 线程与异步规范（强制）

1. 不允许业务模块单独新建线程池（禁止 new ThreadPoolExecutor、Executors.*）。
2. 不允许直接 new Thread 执行业务任务。
3. 线程池必须统一管理、统一配置、统一监控。
4. 异步任务统一走平台线程池或统一调度框架。

13. 分布式锁规范（强制）

1. 统一只使用 @RedissonLock 或 RedissonLockClient 两种方式，禁止新增第三种实现。
2. 所有分布式锁必须设置自动释放时间（leaseTime），禁止无过期时间锁。
3. 锁粒度必须细化到业务主键或唯一业务键（如 orderId、taskId、bizNo），禁止使用过于宽泛的全局锁。
4. 锁 Key 必须复用 RedisConstants 前缀，并拼接唯一业务键，禁止散写字符串锁 Key。
5. 必须使用 try/finally 释放锁，且仅允许“持有者线程”解锁。
6. 获取锁失败必须有明确处理策略：快速失败、有限重试或返回标准业务码（如 DmsErrorEnum）。
7. 锁内逻辑必须短事务、短耗时，禁止在锁内执行长耗时远程调用/批量 I/O。
8. 同一业务场景禁止重复叠加同资源锁，避免死锁和性能浪费。

13.1 分层策略（必须）

1. Service 层强制兜底锁：凡涉及状态变更、扣减、生成唯一号等一致性场景，必须在 Service 层加业务锁。
2. Controller 层可选轻锁：仅用于高并发削峰、防重复点击、短时间重放拦截，不能替代 Service 兜底锁。
3. Controller 轻锁与 Service 业务锁必须使用不同 Key 语义（请求级 vs 业务级）。

13.2 使用注解的场景（优先）

1. 单方法、单资源互斥场景，且锁 Key 可由方法参数稳定生成。
2. 幂等控制、重复提交拦截、同一单据状态迁移防并发等标准场景。
3. 不需要复杂锁编排（多锁顺序、续期、降级）时优先使用注解方式。
4. 注解方法必须为 public，禁止 this.xxx() 自调用绕过 AOP 锁。

13.3 使用 Redis 锁类调用的场景（必须）

1. 需要多 Key 组合加锁或固定加锁顺序防死锁。
2. 需要显式控制重试、续期、降级、兜底释放等高级策略。
3. 跨方法/跨组件协同加锁，注解无法表达完整生命周期。
4. 需要对锁获取失败进行精细化分支处理（部分成功、补偿、告警）场景。
5. 批量接口需要批量加解锁（如 trackingNumber 列表）场景。

14. 日志规范

1. 使用 Slf4j 规范日志，禁止 System.out.println。
2. 关键链路必须记录：业务标识、耗时、结果、异常。
3. 禁止打印敏感信息（密码、token、隐私字段）。
4. 统一使用参数占位符方式写日志。

15. 安全规范

1. 受保护接口必须经过网关鉴权与权限控制。
2. 数据权限必须在业务层落实，禁止仅依赖前端限制。
3. 外部输入必须做合法性校验。
4. 上传、下载、导出等接口必须设置边界与权限。

16. 公共代码归档规范

1. 公共类统一放入 dms-common。
2. 常量类统一放入 com.wpglb.common.constant 目录。
3. 技术基础能力统一沉淀至 wpglb-dms-tool 对应模块。
4. 禁止在业务模块重复实现同类工具能力。

17. 可维护性与提交前检查

1. 保持代码简洁，方法职责单一，控制方法长度。
2. 删除无用代码、无用注释、无用 import。
3. 提交前必须完成：编译通过、主要路径自测通过、异常分支可控。
4. 新增接口同步补齐：参数校验、异常码、日志、Swagger 文档。

18. 违规示例（禁止）

• 循环里调用 mapper.insert/mapper.update/mapper.selectById。
• Controller 中拼接 SQL 条件或承载核心业务逻辑。
• 直接返回实体对象，不使用 R<T>。
• 在业务模块私自创建线程池。
• 新增 C# 文件或非 Java 业务实现。
• 使用无过期时间的分布式锁或使用粗粒度全局锁。

19. 规范执行级别

• 本规范为 DMS 强制编码规范，适用于人工开发与 AI 生成代码双场景。
• 代码评审、联调、上线前检查均以本规范为准。