cdspec 0.1.0

package/templates/standards-backend/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: standards-backend
+description: 部门级后端开发规范执行技能，覆盖后端编码规范、数据库设计规范、传统三层架构约束、DDD架构约束、常用设计模式落地与JUC并发编排规范，并内置数据表基线字段与关联表例外规则。用于需求开发、重构、代码评审、建表SQL设计、接口设计、并发优化与联调前自检等场景；当任务涉及 Java 后端实现、SQL/表结构、分层落位、架构选型（三层或DDD）、可扩展性设计（策略/工厂/责任链/适配器/模板/单例）或线程池/CompletableFuture/CountDownLatch/Semaphore/ReentrantLock/Atomic* 等并发处理时触发。
+---
+
+# 后端开发规范指南
+
+## 总体目标
+在实现后端需求时，优先保证可维护性、一致性和可演进性，避免临时方案累积技术债务。先判断架构模式，再按对应约束完成编码、建表和自检。
+
+## 执行流程
+1. 识别任务类型与架构模式。
+- 若需求以简单 CRUD、快速交付为主，优先采用传统三层约束。
+- 若需求业务规则复杂、存在领域边界和长期演进诉求，优先采用 DDD 约束。
+- 若用户明确指定架构，遵从用户指定。
+
+2. 加载对应规范并生成实现方案。
+- 始终加载 `references/后端开发规范.md`。
+- 涉及表结构或 SQL 时加载 `references/数据库设计规范.md`（已内置基础字段与关联表例外）。
+- 传统三层任务加载 `references/传统三层架构约束.md`。
+- DDD 任务加载 `references/DDD架构约束.md`。
+- 需要可扩展设计或多租户差异化时加载 `references/设计模式落地手册.md`。
+- 涉及异步并发、批处理、超时控制时加载 `references/JUC并发规范.md`。
+
+3. 编码与建模时强制执行。
+- 禁止绕过分层边界。
+- 禁止魔法值直写，统一常量或枚举。
+- 禁止把临时修复直接固化到主流程而无抽象。
+- 对关键写操作、关键分支、异常场景补全中文日志和中文注释。
+
+4. 交付前执行自检。
+- 按所选架构完成分层检查、依赖方向检查、命名检查。
+- 按数据库规范检查命名、索引、SQL 性能风险。
+- 检查每张业务表是否包含必备基础字段。
+- 检查设计模式是否“真落地”：是否去掉了硬编码分支，是否可扩展且可测试。
+- 检查并发代码是否具备线程池边界、超时策略、异常收敛和优雅停机能力。
+- 对高风险变更补充测试点或回归说明。
+
+## 交付要求
+1. 明确说明采用的是传统三层还是 DDD，并给出选择理由。
+2. 列出本次实现遵循的关键约束。
+3. 涉及建表时提供基础字段 SQL 片段，不省略注释。
+4. 输出遗留风险与后续建议，避免将问题留给下一位维护者。
+
+## 参考资料
+- `references/后端开发规范.md`
+- `references/数据库设计规范.md`
+- `references/传统三层架构约束.md`
+- `references/DDD架构约束.md`
+- `references/设计模式落地手册.md`
+- `references/JUC并发规范.md`
+
+## 维护说明
+1. 本技能文档为部门内部规范文档，不依赖任何外部仓库路径。
+2. 规范更新通过本技能 references 文件直接维护，避免引用失效。

package/templates/standards-backend/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "后端开发规范指南"
+  short_description: "统一后端、数据库、架构、设计模式与JUC并发的执行技能"
+  default_prompt: "Use $department-backend-standards to implement backend changes with department standards for coding, DB design, layered or DDD architecture, design patterns, and JUC concurrency."

package/templates/standards-backend/references/DDD/346/236/266/346/236/204/347/272/246/346/235/237.md

@@ -0,0 +1,103 @@
+# DDD 架构约束（项目实战总结版）
+
+## 1. 目标与适用边界
+1. 本规范用于业务规则复杂、状态流转明确、需要长期演进的模块。
+2. 以“领域规则内聚、技术细节外置、跨服务编排上收”为核心目标。
+3. 纯 CRUD 且规则稳定场景优先使用传统三层，不强行 DDD 化。
+
+## 2. 分层模型与职责
+### 2.1 Performance（接口层）
+1. 只负责请求接收、参数校验、响应组装。
+2. 禁止在 Controller 写领域规则和状态流转。
+3. 对外 DTO 只表达接口语义，不泄露领域内部对象结构。
+
+### 2.2 Application（应用层）
+1. 负责用例编排、事务边界、流程顺序控制。
+2. 负责“加载聚合 -> 调用领域行为 -> 持久化 -> 后置动作”的主线流程。
+3. 可做跨聚合协调，但禁止承载可复用的核心业务规则。
+
+### 2.3 Domain（领域层）
+1. 聚合根维护一致性边界内的业务不变量。
+2. 领域实体/值对象暴露业务行为（如提交、确认、状态刷新、数量回写）。
+3. 领域服务承载跨实体规则，保持无基础设施依赖。
+4. 对外依赖通过领域接口抽象（如 `*DomainService`、`*Policy`、`*Repository`）。
+
+### 2.4 Infrastructure（基础设施层）
+1. 实现仓储、策略实现、事件发布器、外部系统客户端。
+2. 承担实体映射与持久化细节，不写业务编排。
+3. 将技术框架能力适配为领域可用接口实现。
+
+## 3. 依赖方向与边界约束
+1. 依赖方向必须稳定：Performance -> Application -> Domain <- Infrastructure。
+2. Domain 禁止依赖 Spring 配置对象、三方 SDK、数据库/消息中间件 API。
+3. Application 禁止绕过领域接口直接依赖底层持久化细节。
+4. Infrastructure 不得反向调用 Application 形成环依赖。
+
+## 4. 聚合设计经验
+1. 聚合根只维护本聚合状态，不跨聚合直接改写对方对象。
+2. 聚合行为命名必须体现业务语义（如 `submit`、`confirm`、`ensureCanEdit`），避免 `doXxx`。
+3. 聚合内校验前置：关键写操作前统一执行可编辑性、状态合法性和明细合法性校验。
+4. 状态流转规则优先封装到枚举/值对象，避免散落的状态码判断。
+5. 聚合字段保持业务最小集，查询条件对象与聚合对象分离。
+
+## 5. 应用服务编排经验
+1. 应用层方法先做轻量参数保护，再加载聚合，最后调用领域行为。
+2. 提交、确认、删除等写操作必须加事务，防止主子表或多仓储更新不一致。
+3. 应用层日志至少记录：业务主键、关键状态、明细数量、执行结果。
+4. 批量操作采用“逐条复用单条逻辑”优先，保证规则一致性。
+
+## 6. 仓储与聚合持久化经验
+1. 仓储接口定义在 Domain，实现在 Infrastructure。
+2. 主表与明细作为聚合整体持久化，提供 `saveAggregate/updateAggregate` 语义接口。
+3. 仓储实现负责“主表落库 + 明细绑定主键 + 明细落库”，应用层不拼装 SQL。
+4. 查询场景按职责拆分：`findById`、`findByNumber`、`findByIdOrNo` 等语义化接口。
+5. Converter 统一负责领域对象与持久化对象转换，禁止在应用层手写大量字段搬运。
+
+## 7. 策略与工厂落地经验
+1. 多租户/多工厂差异规则统一抽象为 `Policy/Strategy` 接口。
+2. 应用层使用工厂解析策略，先匹配显式配置，再匹配租户能力，最后默认兜底。
+3. 默认策略必须存在，且行为可预期。
+4. 策略实现只关注规则差异，不复制主流程。
+
+## 8. 适配器与防腐层经验
+1. 领域接口与已有应用服务模型不一致时，使用应用层 Adapter 进行桥接转换。
+2. 适配器职责只做转换与转调，不承载业务决策。
+3. 外部返回结果判断必须绑定业务语义，禁止笼统“成功/失败兜底”。
+
+## 9. 跨服务编排约束（项目级）
+1. 原子服务（DDD 主栈）只处理本域逻辑，不直接编排外部微服务调用。
+2. 跨服务联动统一放聚合层编排（Facade 层）处理。
+3. 原子服务只负责状态回写、领域规则执行和本域数据一致性。
+
+## 10. 领域事件与一致性经验
+1. 领域事件接口定义在 Domain，发布实现放 Infrastructure。
+2. 应用层在聚合状态稳定后触发事件发布，避免中间态事件外泄。
+3. 事件发布失败策略需明确：重试、补偿或降级日志，不能静默吞掉。
+
+## 11. 校验、异常与日志规范
+1. 参数校验保持最小必要原则，避免重复校验链。
+2. 业务异常信息必须可读并包含关键上下文。
+3. 关键分支、状态变更、异常场景必须有中文日志。
+4. 禁止在通用兜底里吞异常后继续成功返回。
+
+## 12. 测试与回归要求
+1. 领域层：聚合行为与状态流转必须有单元测试。
+2. 基础设施层：仓储聚合保存、更新、删除要有集成测试。
+3. 接口层：关键 API 场景要有集成测试覆盖。
+4. 每次重构至少保证“新增/编辑/提交/删除”主链路可回归。
+
+## 13. 反模式清单（必须规避）
+1. 在 Controller 或 Mapper 层写核心业务规则。
+2. 领域对象直接依赖 Spring 或外部服务 SDK。
+3. 应用层出现大量状态码分支，领域对象退化为贫血模型。
+4. 仓储只存主表不处理聚合明细，导致一致性缺口。
+5. 没有默认策略实现，新增租户时直接运行失败。
+6. 跨服务调用下沉到原子服务，破坏边界与可测试性。
+
+## 14. 交付前 DDD 自检清单
+1. 本次规则是否真正沉淀在 Domain。
+2. 是否存在跨层越权调用。
+3. 聚合保存是否覆盖主表与明细一致性。
+4. 策略扩展是否满足“新增实现类即可扩展”。
+5. 是否补齐关键测试与中文日志。
+6. 是否将跨服务编排留在聚合层处理。

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

@@ -0,0 +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. 是否说明共享状态的并发保护手段（锁/原子/隔离）。

package/templates/standards-backend/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

@@ -0,0 +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. 是否补充了最小回归测试。

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

@@ -0,0 +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`。

package/templates/standards-backend/references//346/225/260/346/215/256/345/272/223/350/256/276/350/256/241/350/247/204/350/214/203.md

@@ -0,0 +1,116 @@
+# 数据库设计规范（部门版）
+
+## 1. 命名规范
+1. 数据库对象名使用小写字母、数字、下划线，禁止数字开头。
+2. 表名使用模块前缀：`sss_xxx`，关系表使用 `sss_xxx_yyy_rel`。
+3. 字段名全小写下划线，命名必须可读且语义明确。
+4. 同语义字段在不同表必须同名同类型。
+5. 关联字段统一 `xxx_id`，类型与被关联主键一致。
+
+## 2. 字段设计
+1. 时间字段：精确到时分秒使用 `xxx_time`（`datetime`）；仅日期使用 `xxx_date`（`date`）。
+2. 标志字段使用 `xxx_flag`；逻辑删除建议统一 `del_flag`（0 未删除，1 已删除）。
+3. 类型字段统一 `xxx_type` 或 `xxx_category`，避免含义不清的数值编码。
+4. 布尔字段命名建议使用 `is_` / `has_` 前缀，避免否定命名。
+
+## 3. 表结构基本约束
+1. 存储引擎统一 InnoDB。
+2. 字符集统一 `utf8mb4`，排序规则统一 `utf8mb4_general_ci`。
+3. 每张表必须有表注释，每个字段必须有字段注释。
+4. 主键建议单一代理键；桥接表可按场景使用复合主键。
+
+## 4. 索引规范
+1. 索引命名使用 `idx_表名_字段名`。
+2. 唯一约束命名使用 `uk_表名_字段名`。
+3. 关联字段必须建索引，避免联表全表扫描。
+4. 单表索引数量建议控制，避免无效和重复索引。
+5. 联合索引遵循最左前缀原则，结合常见查询条件设计。
+
+## 5. SQL 编写规范
+1. 禁止 `select *`，只查询必要列。
+2. 多表查询统一使用别名并带别名前缀。
+3. 分页查询必须限制返回量，避免深分页性能问题。
+4. 避免在索引列上使用函数、隐式转换、前导模糊匹配。
+5. 条件值可能为空时，使用 `is null` / `is not null` 语义表达。
+
+## 6. 变更脚本规范
+1. 版本号采用 `<major>.<minor>.<patch>`。
+2. 脚本命名：`[V|R][版本号]_[序号]__[模块]_[操作]_[描述].sql`。
+3. `V` 脚本只执行一次且不允许改动；`R` 脚本每次运行可重复执行。
+4. 生产变更必须提供回滚策略或数据修复策略。
+
+## 7. 设计评审清单
+1. 是否存在冗余字段或语义不清字段。
+2. 是否缺失必要索引或存在过度索引。
+3. 是否满足基础字段要求（见本文第 8 章）。
+4. 是否考虑了租户、并发更新、历史追溯需求。
+
+## 8. 数据表基线字段规范（内置）
+
+### 8.1 普通业务表（默认必须）
+以下字段为部门级默认基线，除评审通过外不得删除。
+
+```sql
+`id` varchar(36) NOT NULL COMMENT '主键',
+`del_flag` tinyint(4) DEFAULT '0' COMMENT '逻辑删除标志：0-未删除，1-已删除',
+`create_by` varchar(50) DEFAULT NULL COMMENT '创建人',
+`create_time` datetime DEFAULT NULL COMMENT '创建时间',
+`update_by` varchar(50) DEFAULT NULL COMMENT '更新人',
+`update_time` datetime DEFAULT NULL COMMENT '更新时间',
+`version` int(11) DEFAULT '0' COMMENT '乐观锁版本号'
+```
+
+如启用多租户，追加：
+
+```sql
+`tenant_id` int(11) DEFAULT NULL COMMENT '租户ID'
+```
+
+### 8.2 关联表（中间关系表）例外规则
+纯关联表允许精简字段，不强制套用 8.1 的完整审计字段。典型形态如下：
+
+```sql
+`id` varchar(36) NOT NULL COMMENT '主键',
+`user_id` varchar(36) NOT NULL COMMENT '用户ID',
+`role_id` varchar(36) NOT NULL COMMENT '角色ID'
+```
+
+多租户场景建议追加：
+
+```sql
+`tenant_id` int(11) DEFAULT NULL COMMENT '租户ID'
+```
+
+补充约束：
+1. 关联表最少保证 `id + 两端关联ID`，不强制 `del_flag/create_*/update_*/version`。
+2. 若关联关系需要审计追踪、逻辑删除或并发控制，再按 8.1 补齐字段。
+3. 应建立唯一约束避免重复关系（例如 `uk_user_role(user_id, role_id[, tenant_id])`）。
+4. 应给关联 ID 建索引（`idx_xxx_user_id`、`idx_xxx_role_id`）。
+
+### 8.3 历史表（默认必须）
+历史表应包含原表核心业务字段，并追加：
+
+```sql
+`instance_id` varchar(36) DEFAULT NULL COMMENT '历史实例ID',
+`transaction_by` varchar(32) DEFAULT NULL COMMENT '变更人',
+`transaction_time` datetime DEFAULT NULL COMMENT '变更时间'
+```
+
+### 8.4 推荐建表示例（普通业务表）
+```sql
+create table `wms_example_order` (
+  `id` varchar(36) not null comment '主键',
+  `order_no` varchar(64) not null comment '单据编号',
+  `order_status` varchar(32) not null comment '单据状态',
+  `del_flag` tinyint(4) default '0' comment '逻辑删除标志：0-未删除，1-已删除',
+  `create_by` varchar(50) default null comment '创建人',
+  `create_time` datetime default null comment '创建时间',
+  `update_by` varchar(50) default null comment '更新人',
+  `update_time` datetime default null comment '更新时间',
+  `tenant_id` int(11) default null comment '租户ID',
+  `version` int(11) default '0' comment '乐观锁版本号',
+  primary key (`id`),
+  key `idx_wms_example_order_order_no` (`order_no`),
+  key `idx_wms_example_order_status` (`order_status`)
+) engine=innodb default charset=utf8mb4 collate=utf8mb4_general_ci comment='示例订单表';
+```