cdspec 0.1.1 → 0.1.4

package/templates/{standards-backend → backend-standard}/references/JUC/345/271/266/345/217/221/350/247/204/350/214/203.md

@@ -1,232 +1,232 @@
-# JUC 并发规范与样例（部门版）
-
-## 1. 总原则
-1. 先明确是否真的需要并发，不要把并发当性能“银弹”。
-2. 并发代码必须具备四件套：线程池边界、超时控制、异常收敛、可观测日志。
-3. 并发优化必须配套压测或至少基线对比，不允许凭感觉上线。
-4. 业务写操作并发时，必须先定义幂等与一致性策略。
-
-## 2. 线程池规范
-### 2.1 必须遵守
-1. 业务代码禁止直接使用 `Executors` 创建通用线程池。
-2. 必须显式设置 `corePoolSize`、`maxPoolSize`、`queueCapacity`、`RejectedExecutionHandler`。
-3. 线程名前缀必须带业务语义，便于排障。
-4. 必须设置优雅停机参数（等待任务完成与超时时间）。
-
-### 2.2 推荐样例（Spring）
-```java
-@Configuration
-public class BizThreadPoolConfig {
-
-    @Bean("orderAsyncExecutor")
-    public ThreadPoolTaskExecutor orderAsyncExecutor() {
-        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
-        executor.setCorePoolSize(8);
-        executor.setMaxPoolSize(16);
-        executor.setQueueCapacity(200);
-        executor.setKeepAliveSeconds(60);
-        executor.setThreadNamePrefix("order-async-");
-        executor.setRejectedExecutionHandler(new ThreadPoolExecutor.CallerRunsPolicy());
-        executor.setWaitForTasksToCompleteOnShutdown(true);
-        executor.setAwaitTerminationSeconds(30);
-        executor.initialize();
-        return executor;
-    }
-}
-```
-
-### 2.3 拒绝策略建议
-1. `AbortPolicy`：核心链路，宁可失败暴露问题。
-2. `CallerRunsPolicy`：允许调用方降速回压。
-3. `Discard/DiscardOldest`：仅可用于弱一致、可丢任务场景，需业务签字。
-
-## 3. CompletableFuture 规范
-### 3.1 必须遵守
-1. 优先使用业务线程池，禁止默认公共线程池污染全局。
-2. 聚合调用必须设置整体超时。
-3. 必须有异常兜底与降级值，禁止直接 `join` 后抛到最外层。
-4. 合并结果前必须过滤空值与异常结果。
-
-### 3.2 推荐样例
-```java
-public List<OrderView> queryOrdersAsync(List<String> ids, Executor executor) {
-    List<CompletableFuture<OrderView>> futures = ids.stream()
-            .map(id -> CompletableFuture.supplyAsync(() -> queryOne(id), executor)
-                    .completeOnTimeout(OrderView.empty(id), 800, TimeUnit.MILLISECONDS)
-                    .exceptionally(ex -> {
-                        log.error("异步查询订单失败, id:{}", id, ex);
-                        return OrderView.empty(id);
-                    }))
-            .toList();
-
-    CompletableFuture<Void> all = CompletableFuture.allOf(futures.toArray(new CompletableFuture[0]));
-    all.orTimeout(2, TimeUnit.SECONDS).join();
-
-    return futures.stream()
-            .map(CompletableFuture::join)
-            .filter(OrderView::valid)
-            .toList();
-}
-```
-
-## 4. CountDownLatch 规范
-### 4.1 使用边界
-1. 适合“一次性协同等待”，不适合可复用屏障。
-2. 每个 `countDown` 必须放在 `finally`，防止死等。
-3. `await` 必须设置超时，超时后记录上下文并快速失败。
-
-### 4.2 推荐样例
-```java
-public void batchHandle(List<Task> tasks, Executor executor) throws InterruptedException {
-    CountDownLatch latch = new CountDownLatch(tasks.size());
-    for (Task task : tasks) {
-        executor.execute(() -> {
-            try {
-                handleOne(task);
-            } catch (Exception ex) {
-                log.error("并发任务处理失败, taskId:{}", task.getId(), ex);
-            } finally {
-                latch.countDown();
-            }
-        });
-    }
-
-    boolean finished = latch.await(30, TimeUnit.SECONDS);
-    if (!finished) {
-        throw new IllegalStateException("批处理超时，存在未完成任务");
-    }
-}
-```
-
-## 5. Semaphore 规范
-### 5.1 适用场景
-1. 需要限制并发访问量，如第三方接口、限连接资源、下游慢服务。
-2. 单机内“令牌桶”式削峰，避免瞬时把下游打挂。
-
-### 5.2 推荐样例
-```java
-public class ThirdPartyGateway {
-
-    private final Semaphore semaphore = new Semaphore(20, true);
-
-    public Result call(ApiReq req) throws InterruptedException {
-        boolean acquired = semaphore.tryAcquire(200, TimeUnit.MILLISECONDS);
-        if (!acquired) {
-            throw new IllegalStateException("下游繁忙，请稍后重试");
-        }
-        try {
-            return doHttpCall(req);
-        } finally {
-            semaphore.release();
-        }
-    }
-}
-```
-
-### 5.3 注意事项
-1. `acquire` 后必须在 `finally` 中 `release`。
-2. 优先 `tryAcquire(timeout)`，避免无限等待。
-3. 公平锁会牺牲吞吐，默认仅在“先来先服务”强需求时启用公平参数。
-
-## 6. ReentrantLock 规范
-### 6.1 适用场景
-1. 需要可中断锁、可轮询尝试锁、读写条件变量等能力。
-2. 需要比 `synchronized` 更细粒度的锁控制和可观测性。
-
-### 6.2 推荐样例
-```java
-public class OrderCache {
-
-    private final ReentrantLock lock = new ReentrantLock();
-    private final Map<String, Order> cache = new HashMap<>();
-
-    public void put(Order order) {
-        lock.lock();
-        try {
-            cache.put(order.getId(), order);
-        } finally {
-            lock.unlock();
-        }
-    }
-
-    public Optional<Order> get(String id) {
-        if (!lock.tryLock()) {
-            return Optional.empty();
-        }
-        try {
-            return Optional.ofNullable(cache.get(id));
-        } finally {
-            lock.unlock();
-        }
-    }
-}
-```
-
-### 6.3 注意事项
-1. 禁止 `lock()` 后非 `finally` 解锁。
-2. 对外部调用或 IO 逻辑不要包在锁内，避免锁膨胀。
-3. 多锁场景必须固定加锁顺序，避免死锁。
-
-## 7. 原子类规范（Atomic / LongAdder）
-### 7.1 常用选择
-1. `AtomicInteger/AtomicLong`：单值计数与状态位。
-2. `AtomicReference`：无锁替换对象引用。
-3. `AtomicStampedReference`：需要避免 ABA 问题。
-4. `LongAdder`：高并发计数优于 `AtomicLong`。
-
-### 7.2 推荐样例
-```java
-public class StatsCounter {
-
-    private final LongAdder success = new LongAdder();
-    private final LongAdder failed = new LongAdder();
-    private final AtomicReference<String> currentBatch = new AtomicReference<>("INIT");
-
-    public void markSuccess() {
-        success.increment();
-    }
-
-    public void markFailed() {
-        failed.increment();
-    }
-
-    public boolean switchBatch(String expect, String next) {
-        return currentBatch.compareAndSet(expect, next);
-    }
-}
-```
-
-### 7.3 注意事项
-1. 多字段一致性更新不能只靠原子类，必要时使用锁或事务。
-2. 原子类只保证单变量原子性，不保证复合操作原子性。
-
-## 8. 常用并发容器与同步器
-### 8.1 ConcurrentHashMap
-1. 高并发读写缓存首选 `ConcurrentHashMap`。
-2. 使用 `computeIfAbsent` 避免重复初始化。
-
-### 8.2 BlockingQueue
-1. 生产消费解耦优先 `LinkedBlockingQueue/ArrayBlockingQueue`。
-2. 必须设置容量上限，避免内存无界增长。
-
-### 8.3 CopyOnWriteArrayList
-1. 读多写少场景可用，写多场景禁止使用。
-
-### 8.4 CyclicBarrier / Phaser
-1. `CyclicBarrier` 适合固定参与方的分阶段任务。
-2. `Phaser` 适合参与方动态变化的分阶段协同。
-
-## 9. 并发反模式
-1. `CompletableFuture.completedFuture(同步查询)` 伪异步。
-2. 静态全局 `CountDownLatch` 工具类跨任务复用，导致串扰。
-3. 不区分业务池和公共池，导致不同模块相互拖垮。
-4. 捕获异常后静默吞掉，线上只能看到“卡死/超时”。
-5. 使用无界队列和无限重试掩盖系统容量问题。
-6. 把共享可变对象放进并发容器后误以为“业务线程安全”。
-
-## 10. 交付前并发检查清单
-1. 是否声明了线程池参数并解释依据。
-2. 是否设置了超时和异常兜底。
-3. 是否记录关键并发日志（任务数、耗时、失败数）。
-4. 是否验证了停机或发布期间的任务收敛行为。
-5. 是否说明共享状态的并发保护手段（锁/原子/隔离）。
+# JUC 并发规范与样例（部门版）
+
+## 1. 总原则
+1. 先明确是否真的需要并发，不要把并发当性能“银弹”。
+2. 并发代码必须具备四件套：线程池边界、超时控制、异常收敛、可观测日志。
+3. 并发优化必须配套压测或至少基线对比，不允许凭感觉上线。
+4. 业务写操作并发时，必须先定义幂等与一致性策略。
+
+## 2. 线程池规范
+### 2.1 必须遵守
+1. 业务代码禁止直接使用 `Executors` 创建通用线程池。
+2. 必须显式设置 `corePoolSize`、`maxPoolSize`、`queueCapacity`、`RejectedExecutionHandler`。
+3. 线程名前缀必须带业务语义，便于排障。
+4. 必须设置优雅停机参数（等待任务完成与超时时间）。
+
+### 2.2 推荐样例（Spring）
+```java
+@Configuration
+public class BizThreadPoolConfig {
+
+    @Bean("orderAsyncExecutor")
+    public ThreadPoolTaskExecutor orderAsyncExecutor() {
+        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
+        executor.setCorePoolSize(8);
+        executor.setMaxPoolSize(16);
+        executor.setQueueCapacity(200);
+        executor.setKeepAliveSeconds(60);
+        executor.setThreadNamePrefix("order-async-");
+        executor.setRejectedExecutionHandler(new ThreadPoolExecutor.CallerRunsPolicy());
+        executor.setWaitForTasksToCompleteOnShutdown(true);
+        executor.setAwaitTerminationSeconds(30);
+        executor.initialize();
+        return executor;
+    }
+}
+```
+
+### 2.3 拒绝策略建议
+1. `AbortPolicy`：核心链路，宁可失败暴露问题。
+2. `CallerRunsPolicy`：允许调用方降速回压。
+3. `Discard/DiscardOldest`：仅可用于弱一致、可丢任务场景，需业务签字。
+
+## 3. CompletableFuture 规范
+### 3.1 必须遵守
+1. 优先使用业务线程池，禁止默认公共线程池污染全局。
+2. 聚合调用必须设置整体超时。
+3. 必须有异常兜底与降级值，禁止直接 `join` 后抛到最外层。
+4. 合并结果前必须过滤空值与异常结果。
+
+### 3.2 推荐样例
+```java
+public List<OrderView> queryOrdersAsync(List<String> ids, Executor executor) {
+    List<CompletableFuture<OrderView>> futures = ids.stream()
+            .map(id -> CompletableFuture.supplyAsync(() -> queryOne(id), executor)
+                    .completeOnTimeout(OrderView.empty(id), 800, TimeUnit.MILLISECONDS)
+                    .exceptionally(ex -> {
+                        log.error("异步查询订单失败, id:{}", id, ex);
+                        return OrderView.empty(id);
+                    }))
+            .toList();
+
+    CompletableFuture<Void> all = CompletableFuture.allOf(futures.toArray(new CompletableFuture[0]));
+    all.orTimeout(2, TimeUnit.SECONDS).join();
+
+    return futures.stream()
+            .map(CompletableFuture::join)
+            .filter(OrderView::valid)
+            .toList();
+}
+```
+
+## 4. CountDownLatch 规范
+### 4.1 使用边界
+1. 适合“一次性协同等待”，不适合可复用屏障。
+2. 每个 `countDown` 必须放在 `finally`，防止死等。
+3. `await` 必须设置超时，超时后记录上下文并快速失败。
+
+### 4.2 推荐样例
+```java
+public void batchHandle(List<Task> tasks, Executor executor) throws InterruptedException {
+    CountDownLatch latch = new CountDownLatch(tasks.size());
+    for (Task task : tasks) {
+        executor.execute(() -> {
+            try {
+                handleOne(task);
+            } catch (Exception ex) {
+                log.error("并发任务处理失败, taskId:{}", task.getId(), ex);
+            } finally {
+                latch.countDown();
+            }
+        });
+    }
+
+    boolean finished = latch.await(30, TimeUnit.SECONDS);
+    if (!finished) {
+        throw new IllegalStateException("批处理超时，存在未完成任务");
+    }
+}
+```
+
+## 5. Semaphore 规范
+### 5.1 适用场景
+1. 需要限制并发访问量，如第三方接口、限连接资源、下游慢服务。
+2. 单机内“令牌桶”式削峰，避免瞬时把下游打挂。
+
+### 5.2 推荐样例
+```java
+public class ThirdPartyGateway {
+
+    private final Semaphore semaphore = new Semaphore(20, true);
+
+    public Result call(ApiReq req) throws InterruptedException {
+        boolean acquired = semaphore.tryAcquire(200, TimeUnit.MILLISECONDS);
+        if (!acquired) {
+            throw new IllegalStateException("下游繁忙，请稍后重试");
+        }
+        try {
+            return doHttpCall(req);
+        } finally {
+            semaphore.release();
+        }
+    }
+}
+```
+
+### 5.3 注意事项
+1. `acquire` 后必须在 `finally` 中 `release`。
+2. 优先 `tryAcquire(timeout)`，避免无限等待。
+3. 公平锁会牺牲吞吐，默认仅在“先来先服务”强需求时启用公平参数。
+
+## 6. ReentrantLock 规范
+### 6.1 适用场景
+1. 需要可中断锁、可轮询尝试锁、读写条件变量等能力。
+2. 需要比 `synchronized` 更细粒度的锁控制和可观测性。
+
+### 6.2 推荐样例
+```java
+public class OrderCache {
+
+    private final ReentrantLock lock = new ReentrantLock();
+    private final Map<String, Order> cache = new HashMap<>();
+
+    public void put(Order order) {
+        lock.lock();
+        try {
+            cache.put(order.getId(), order);
+        } finally {
+            lock.unlock();
+        }
+    }
+
+    public Optional<Order> get(String id) {
+        if (!lock.tryLock()) {
+            return Optional.empty();
+        }
+        try {
+            return Optional.ofNullable(cache.get(id));
+        } finally {
+            lock.unlock();
+        }
+    }
+}
+```
+
+### 6.3 注意事项
+1. 禁止 `lock()` 后非 `finally` 解锁。
+2. 对外部调用或 IO 逻辑不要包在锁内，避免锁膨胀。
+3. 多锁场景必须固定加锁顺序，避免死锁。
+
+## 7. 原子类规范（Atomic / LongAdder）
+### 7.1 常用选择
+1. `AtomicInteger/AtomicLong`：单值计数与状态位。
+2. `AtomicReference`：无锁替换对象引用。
+3. `AtomicStampedReference`：需要避免 ABA 问题。
+4. `LongAdder`：高并发计数优于 `AtomicLong`。
+
+### 7.2 推荐样例
+```java
+public class StatsCounter {
+
+    private final LongAdder success = new LongAdder();
+    private final LongAdder failed = new LongAdder();
+    private final AtomicReference<String> currentBatch = new AtomicReference<>("INIT");
+
+    public void markSuccess() {
+        success.increment();
+    }
+
+    public void markFailed() {
+        failed.increment();
+    }
+
+    public boolean switchBatch(String expect, String next) {
+        return currentBatch.compareAndSet(expect, next);
+    }
+}
+```
+
+### 7.3 注意事项
+1. 多字段一致性更新不能只靠原子类，必要时使用锁或事务。
+2. 原子类只保证单变量原子性，不保证复合操作原子性。
+
+## 8. 常用并发容器与同步器
+### 8.1 ConcurrentHashMap
+1. 高并发读写缓存首选 `ConcurrentHashMap`。
+2. 使用 `computeIfAbsent` 避免重复初始化。
+
+### 8.2 BlockingQueue
+1. 生产消费解耦优先 `LinkedBlockingQueue/ArrayBlockingQueue`。
+2. 必须设置容量上限，避免内存无界增长。
+
+### 8.3 CopyOnWriteArrayList
+1. 读多写少场景可用，写多场景禁止使用。
+
+### 8.4 CyclicBarrier / Phaser
+1. `CyclicBarrier` 适合固定参与方的分阶段任务。
+2. `Phaser` 适合参与方动态变化的分阶段协同。
+
+## 9. 并发反模式
+1. `CompletableFuture.completedFuture(同步查询)` 伪异步。
+2. 静态全局 `CountDownLatch` 工具类跨任务复用，导致串扰。
+3. 不区分业务池和公共池，导致不同模块相互拖垮。
+4. 捕获异常后静默吞掉，线上只能看到“卡死/超时”。
+5. 使用无界队列和无限重试掩盖系统容量问题。
+6. 把共享可变对象放进并发容器后误以为“业务线程安全”。
+
+## 10. 交付前并发检查清单
+1. 是否声明了线程池参数并解释依据。
+2. 是否设置了超时和异常兜底。
+3. 是否记录关键并发日志（任务数、耗时、失败数）。
+4. 是否验证了停机或发布期间的任务收敛行为。
+5. 是否说明共享状态的并发保护手段（锁/原子/隔离）。

package/templates/{standards-backend → backend-standard}/references//344/274/240/347/273/237/344/270/211/345/261/202/346/236/266/346/236/204/347/272/246/346/235/237.md

@@ -1,35 +1,35 @@
-# 传统三层架构约束（Controller-Service-Mapper）
-
-## 1. 适用范围
-1. 业务以 CRUD 为主，规则相对简单。
-2. 项目周期短、团队规模小、强调交付速度。
-3. 不适合复杂跨域流程和高频业务规则变更场景。
-
-## 2. 分层职责
-1. Controller 层：接收请求、参数校验、统一返回，不承载复杂业务。
-2. Service 层：承载业务逻辑、事务边界、流程控制。
-3. Mapper/Repository 层：专注数据访问，不承载业务决策。
-4. Convert 层：负责 DTO/VO/Entity 转换，避免污染业务层。
-
-## 3. 强制约束
-1. Controller 禁止直接访问 Mapper。
-2. Service 禁止返回数据库实体给前端。
-3. Mapper 接口仅暴露数据访问方法，命名表达查询语义。
-4. 复杂查询优先 XML/动态 SQL，禁止拼接裸 SQL 字符串。
-5. 事务注解放在 Service 层，避免跨层事务失控。
-
-## 4. 代码组织建议
-1. 包结构建议：`controller`、`service`、`service.impl`、`mapper`、`entity`、`convert`。
-2. 类命名建议：`XxxController`、`IXxxService`、`XxxServiceImpl`、`XxxMapper`。
-3. 使用 MyBatis-Plus 时，仍需显式表达业务规则，不要把业务混在查询构造器里。
-
-## 5. 常见反模式
-1. 在 Controller 写业务编排。
-2. 在 Mapper 写业务规则判断。
-3. Service 方法过长且无领域语义，只有流程堆砌。
-4. 返回模型复用混乱，导致 API 和数据库实体耦合。
-
-## 6. 交付检查
-1. 每个接口的入参、出参、错误码是否统一。
-2. 关键写操作是否记录中文日志。
-3. 是否补充了最小回归测试。
+# 传统三层架构约束（Controller-Service-Mapper）
+
+## 1. 适用范围
+1. 业务以 CRUD 为主，规则相对简单。
+2. 项目周期短、团队规模小、强调交付速度。
+3. 不适合复杂跨域流程和高频业务规则变更场景。
+
+## 2. 分层职责
+1. Controller 层：接收请求、参数校验、统一返回，不承载复杂业务。
+2. Service 层：承载业务逻辑、事务边界、流程控制。
+3. Mapper/Repository 层：专注数据访问，不承载业务决策。
+4. Convert 层：负责 DTO/VO/Entity 转换，避免污染业务层。
+
+## 3. 强制约束
+1. Controller 禁止直接访问 Mapper。
+2. Service 禁止返回数据库实体给前端。
+3. Mapper 接口仅暴露数据访问方法，命名表达查询语义。
+4. 复杂查询优先 XML/动态 SQL，禁止拼接裸 SQL 字符串。
+5. 事务注解放在 Service 层，避免跨层事务失控。
+
+## 4. 代码组织建议
+1. 包结构建议：`controller`、`service`、`service.impl`、`mapper`、`entity`、`convert`。
+2. 类命名建议：`XxxController`、`IXxxService`、`XxxServiceImpl`、`XxxMapper`。
+3. 使用 MyBatis-Plus 时，仍需显式表达业务规则，不要把业务混在查询构造器里。
+
+## 5. 常见反模式
+1. 在 Controller 写业务编排。
+2. 在 Mapper 写业务规则判断。
+3. Service 方法过长且无领域语义，只有流程堆砌。
+4. 返回模型复用混乱，导致 API 和数据库实体耦合。
+
+## 6. 交付检查
+1. 每个接口的入参、出参、错误码是否统一。
+2. 关键写操作是否记录中文日志。
+3. 是否补充了最小回归测试。

package/templates/{standards-backend → backend-standard}/references//345/220/216/347/253/257/345/274/200/345/217/221/350/247/204/350/214/203.md

@@ -1,49 +1,49 @@
-# 后端开发规范（部门版）
-
-## 1. 命名与结构
-1. 包名全部小写，按语义分层组织。
-2. 类名使用大驼峰，方法/变量使用小驼峰。
-3. 命名必须表达业务语义，避免拼音、无意义缩写、单字符变量（循环计数除外）。
-4. 常量必须使用 `static final`，常量名全大写下划线分隔。
-5. 枚举值全大写下划线分隔，枚举要体现业务语义。
-
-## 2. 对象分层
-1. `Entity`：仅做数据库映射，不承载业务流程。（老项目不改动，新项目需遵守）
-2. `ReqDTO/RespDTO`：跨服务传输对象，仅保留必要字段。（老项目不改动，新项目需遵守）
-3. `ReqVO/RespVO`：接口展示对象，可做展示格式适配。（老项目不改动，新项目需遵守）
-
-
-## 3. 注释与日志
-1. 类、方法、复杂分支必须有中文注释，说明“做什么、为什么这样做”。
-2. 关键写操作必须记录中文日志，包含业务主键与结果。
-3. 异常场景必须记录错误原因、输入上下文。
-4. 日志避免输出敏感信息（密钥、完整证件号、明文密码）。
-
-## 4. 控制器与返回
-1. Controller 仅做参数接收、校验、调用应用服务，不写业务核心逻辑。
-2. 接口返回统一结果模型，错误码和文案来自统一枚举。
-3. 禁止直接暴露领域对象作为对外接口返回值。
-4. URI 命名保持语义清晰并与业务动作一致。
-
-## 5. 异常与校验
-1. 业务异常与系统异常分层处理，禁止一把抓 `Exception` 后直接吞掉。
-2. 参数校验前置，尽量使用声明式校验（如 Bean Validation）。
-3. 禁止重复、冗余校验，避免多处维护同一规则。
-4. 比较字符串时避免空指针风险，优先常量调用 `equals`。
-
-## 6. 并发与基础能力
-1. 禁止直接使用 `Executors` 创建线程池，使用 `ThreadPoolExecutor` 显式配置边界。
-2. 优先使用 `java.time` 替代 `Date` / `Calendar` / `SimpleDateFormat`。
-3. 不使用过时 API。
-4. 复写方法必须显式加 `@Override`。
-
-## 7. 代码质量门禁
-1. 提交前通过静态检查（Checkstyle/PMD/FindBugs/SonarQube）。
-2. 新增模块必须提供最小可回归测试路径。
-3. 出现“临时方案”时，必须补充重构计划或明确技术债登记。
-
-## 8. 可扩展性与并发基线
-1. 业务分支超过 3 个且预计持续增长时，优先引入策略/工厂/责任链等可扩展模式。
-2. 外部系统字段模型不一致时，优先通过适配器隔离，不在主流程直接拼装转换。
-3. 异步并发能力统一走线程池，禁止散落创建线程。
-4. 并发逻辑必须具备超时、降级和错误日志，禁止无边界 `join/await`。
+# 后端开发规范（部门版）
+
+## 1. 命名与结构
+1. 包名全部小写，按语义分层组织。
+2. 类名使用大驼峰，方法/变量使用小驼峰。
+3. 命名必须表达业务语义，避免拼音、无意义缩写、单字符变量（循环计数除外）。
+4. 常量必须使用 `static final`，常量名全大写下划线分隔。
+5. 枚举值全大写下划线分隔，枚举要体现业务语义。
+
+## 2. 对象分层
+1. `Entity`：仅做数据库映射，不承载业务流程。（老项目不改动，新项目需遵守）
+2. `ReqDTO/RespDTO`：跨服务传输对象，仅保留必要字段。（老项目不改动，新项目需遵守）
+3. `ReqVO/RespVO`：接口展示对象，可做展示格式适配。（老项目不改动，新项目需遵守）
+
+
+## 3. 注释与日志
+1. 类、方法、复杂分支必须有中文注释，说明“做什么、为什么这样做”。
+2. 关键写操作必须记录中文日志，包含业务主键与结果。
+3. 异常场景必须记录错误原因、输入上下文。
+4. 日志避免输出敏感信息（密钥、完整证件号、明文密码）。
+
+## 4. 控制器与返回
+1. Controller 仅做参数接收、校验、调用应用服务，不写业务核心逻辑。
+2. 接口返回统一结果模型，错误码和文案来自统一枚举。
+3. 禁止直接暴露领域对象作为对外接口返回值。
+4. URI 命名保持语义清晰并与业务动作一致。
+
+## 5. 异常与校验
+1. 业务异常与系统异常分层处理，禁止一把抓 `Exception` 后直接吞掉。
+2. 参数校验前置，尽量使用声明式校验（如 Bean Validation）。
+3. 禁止重复、冗余校验，避免多处维护同一规则。
+4. 比较字符串时避免空指针风险，优先常量调用 `equals`。
+
+## 6. 并发与基础能力
+1. 禁止直接使用 `Executors` 创建线程池，使用 `ThreadPoolExecutor` 显式配置边界。
+2. 优先使用 `java.time` 替代 `Date` / `Calendar` / `SimpleDateFormat`。
+3. 不使用过时 API。
+4. 复写方法必须显式加 `@Override`。
+
+## 7. 代码质量门禁
+1. 提交前通过静态检查（Checkstyle/PMD/FindBugs/SonarQube）。
+2. 新增模块必须提供最小可回归测试路径。
+3. 出现“临时方案”时，必须补充重构计划或明确技术债登记。
+
+## 8. 可扩展性与并发基线
+1. 业务分支超过 3 个且预计持续增长时，优先引入策略/工厂/责任链等可扩展模式。
+2. 外部系统字段模型不一致时，优先通过适配器隔离，不在主流程直接拼装转换。
+3. 异步并发能力统一走线程池，禁止散落创建线程。
+4. 并发逻辑必须具备超时、降级和错误日志，禁止无边界 `join/await`。