adspecs 0.1.32 → 0.1.34

package/references/yudaocloud-end-standard/02-/346/225/260/346/215/256/345/272/223/350/256/276/350/256/241/344/270/216/344/275/277/347/224/250/350/247/204/350/214/203.md

@@ -0,0 +1,1023 @@
+# PostgreSQL 数据库设计与使用规范
+
+> **版本**: v2.0
+> **修订日期**: 2026-07-27
+> **适用范围**: ultracloud 项目所有后端模块
+> **目标数据库**: PostgreSQL 16+（主用），兼容 MySQL 8.0+（备用）
+
+本规范基于 PostgreSQL 特性编写，结合项目 MyBatis Plus 3.5.16 + Druid 1.2.28 + Spring Boot 4.1.0 技术栈，可直接落地。
+
+---
+
+## 1. SQL 建表规范
+
+生成的 `*-schema.sql` 文件必须遵循以下约定。
+
+### 1.1 文件头
+
+```sql
+-- {spec标题} — 数据库表结构
+-- 数据库: PostgreSQL 16+
+-- 生成日期: YYYY-MM-DD
+-- 模块: sie-module-{module}
+
+SET client_encoding = 'UTF8';
+SET standard_conforming_strings = ON;
+```
+
+> **差异说明**：
+> - PostgreSQL 无需 `SET FOREIGN_KEY_CHECKS`，无 `ENGINE`/`CHARSET`/`COLLATE` 表级选项
+> - `standard_conforming_strings = ON` 为 PG 9.1+ 默认值，显式声明以确保反斜杠不被转义；若脚本需兼容旧版 PG，此项必写
+
+### 1.2 表命名
+
+- 表名使用 `{module-prefix}_{entity_name}` 格式，如 `mdm_customer`、`mdm_ctct`
+- 模块前缀约定：MDM=mdm, System=system, Infra=infra, BPM=bpm, AI=ai
+- 表名全小写，单词间用下划线分隔
+- **不使用双引号包裹表名**（PostgreSQL 中双引号区分大小写，保持一致的小写无引号风格）
+
+### 1.3 字段规范
+
+| 类别 | MySQL 写法 | PostgreSQL 写法 | 说明 |
+|------|-----------|----------------|------|
+| 主键 | `BIGINT NOT NULL AUTO_INCREMENT` | `BIGSERIAL PRIMARY KEY` | 或使用 `GENERATED BY DEFAULT AS IDENTITY` |
+| 布尔值 | `BIT(1) NOT NULL DEFAULT 0` | `BOOLEAN NOT NULL DEFAULT FALSE` | 使用原生 BOOLEAN（逻辑删除 `deleted` 例外，用 `SMALLINT`，见 §1.5） |
+| 枚举/状态 | `VARCHAR` / `TINYINT` | `VARCHAR` / `SMALLINT` | 不使用 PostgreSQL ENUM 类型（不便修改） |
+| 金额/精度 | `DECIMAL(M,N)` | `NUMERIC(M,N)` | `NUMERIC` 为 PG 标准写法（`DECIMAL` 为其别名） |
+| JSON 字段 | `JSON` | `JSONB` | 使用 JSONB（二进制存储，支持索引与运算） |
+| 时间 | `DATETIME` | `TIMESTAMP` | 与 Java `LocalDateTime` 对应；如需时区用 `TIMESTAMPTZ` |
+| 文本 | `TEXT` / `VARCHAR` | `TEXT` / `VARCHAR` | 一致；PG 中 `TEXT` 与 `VARCHAR` 性能无差异 |
+| 大文本 | `TEXT` / `LONGTEXT` | `TEXT` | PG 的 `TEXT` 无长度限制，无需区分 |
+| 整数 | `INT` / `BIGINT` | `INTEGER` / `BIGINT` | PG 标准写法 |
+| 短整数 | `TINYINT` | `SMALLINT` | PG 无 `TINYINT`，最小整数类型为 `SMALLINT`（2 字节） |
+| 字节 | `BLOB` / `LONGBLOB` | `BYTEA` | 二进制数据存储 |
+
+**通用字段规范**（MySQL / PostgreSQL 共同）：
+
+- **BIGINT**: 所有 ID/外键字段统一使用 `BIGINT`（Snowflake 主键约定）
+- **每列必须带 `COMMENT`**，说明字段含义（PostgreSQL 通过独立的 `COMMENT ON` 语句实现）
+- **不可空字段**: `NOT NULL DEFAULT` 给出合理默认值
+- **可空字段**: `DEFAULT NULL`
+- **JSON 字段**: 不允许有默认值，全部默认为 `NULL`
+
+### 1.4 注释规范（PostgreSQL 专属）
+
+PostgreSQL 的列注释和表注释通过独立语句完成，**不内联在 CREATE TABLE 中**：
+
+```sql
+-- 表注释
+COMMENT ON TABLE mdm_customer IS '客户主数据表';
+
+-- 列注释（建表语句之后逐一添加）
+COMMENT ON COLUMN mdm_customer.id IS '主键ID';
+COMMENT ON COLUMN mdm_customer.code IS '客户编码';
+COMMENT ON COLUMN mdm_customer.name IS '客户名称';
+COMMENT ON COLUMN mdm_customer.status IS '状态（0=草稿 1=已审核 2=已冻结）';
+COMMENT ON COLUMN mdm_customer.ext_json IS '扩展属性（JSONB）';
+```
+
+> **工具辅助**：可使用 `psql` 的 `\d` 命令查看注释；也可在 IDE（DBeaver/Navicat）中直接浏览。
+> **批量生成建议**：建表脚本末尾集中写所有 `COMMENT ON` 语句，便于维护。
+
+### 1.5 审计字段（必须包含）
+
+```sql
+-- TenantBaseDO 实体（绝大多数业务表）:
+tenant_id    BIGINT       NOT NULL DEFAULT 0,
+creator      VARCHAR(64)  DEFAULT '',
+create_time  TIMESTAMP    NOT NULL DEFAULT CURRENT_TIMESTAMP,
+updater      VARCHAR(64)  DEFAULT '',
+update_time  TIMESTAMP    NOT NULL DEFAULT CURRENT_TIMESTAMP,
+deleted      SMALLINT     NOT NULL DEFAULT 0,
+deleted_time TIMESTAMP    DEFAULT NULL,
+
+-- BaseDO 实体（关联表/版本表等非租户表）: 去掉 tenant_id，其余相同
+```
+
+**列注释**：
+
+```sql
+COMMENT ON COLUMN {table}.tenant_id IS '租户ID';
+COMMENT ON COLUMN {table}.creator IS '创建者';
+COMMENT ON COLUMN {table}.create_time IS '创建时间';
+COMMENT ON COLUMN {table}.updater IS '更新者';
+COMMENT ON COLUMN {table}.update_time IS '更新时间';
+COMMENT ON COLUMN {table}.deleted IS '逻辑删除标志（0=未删除 1=已删除）';
+COMMENT ON COLUMN {table}.deleted_time IS '逻辑删除时间';
+```
+
+> **与 MySQL 的关键差异**：
+> - `deleted` 使用 `SMALLINT`（0=未删除，1=已删除），**禁止使用 `BOOLEAN`**。原因：`BaseDO.deleted` 为 `Boolean` 类型，MyBatis-Plus 全局配置 `logic-not-delete-value=0`（整数），生成 SQL `WHERE deleted = 0`。PostgreSQL 中 `smallint = integer` 可隐式转换（正常），但 `boolean = integer` 不可转换（报错"操作符不存在: boolean = integer"）。系统表 `system_dict_type` 即用 `SMALLINT`，以此为统一标准。
+> - 必须配套 `deleted_time TIMESTAMP DEFAULT NULL` 字段，记录逻辑删除发生时间
+> - `update_time` 默认值仅设 `CURRENT_TIMESTAMP`（PG 无 `ON UPDATE CURRENT_TIMESTAMP`，由应用层 `DefaultDBFieldHandler` 自动填充，或可选启用数据库触发器——见 §1.10）
+> - `TIMESTAMP` 对应 Java `LocalDateTime`；如需带时区使用 `TIMESTAMPTZ`
+>
+> ⚠️ **重要**：真布尔字段（如 `visible`/`keep_alive`/`always_show`/`is_primary`）仍使用 `BOOLEAN` 类型。仅逻辑删除标志 `deleted` 例外，使用 `SMALLINT`。
+
+### 1.6 主键与 ID 生成策略
+
+**建表 SQL** 使用 `BIGSERIAL`（PostgreSQL 伪类型，自动创建 `SEQUENCE`）：
+
+```sql
+CREATE TABLE mdm_customer (
+    id BIGSERIAL PRIMARY KEY,
+    -- ...
+);
+```
+
+**Java DO 实体** 对应写法：
+
+```java
+@TableId(type = IdType.AUTO)
+private Long id;
+```
+
+> **说明**：`BIGSERIAL` 等价于 `BIGINT NOT NULL DEFAULT nextval('table_id_seq')`，MyBatis Plus 的 `IdType.AUTO` 可正确识别并通过 JDBC `getGeneratedKeys` 取回自增值。
+>
+> **Snowflake 场景**：如使用雪花 ID（由应用层分配），建表改用普通 `BIGINT PRIMARY KEY`，不设 `BIGSERIAL`，`@TableId(type = IdType.ASSIGN_ID)`。
+
+### 1.7 N:N 关系表
+
+- **无独立 ID 字段**，使用复合主键
+- 不包含审计字段（纯关系映射表）
+- 额外关联属性（如 `clause_code`、`is_primary`）作为主键组成部分或普通字段
+
+```sql
+CREATE TABLE mdm_ctct_standard_ref (
+    ctct_id     BIGINT       NOT NULL,
+    standard_id BIGINT       NOT NULL,
+    clause_code VARCHAR(64)  NOT NULL DEFAULT '',
+    is_primary  BOOLEAN      NOT NULL DEFAULT FALSE,
+    PRIMARY KEY (ctct_id, standard_id, clause_code)
+);
+
+COMMENT ON TABLE mdm_ctct_standard_ref IS 'CTCT-标准引用关系表';
+COMMENT ON COLUMN mdm_ctct_standard_ref.ctct_id IS 'CTCT ID';
+COMMENT ON COLUMN mdm_ctct_standard_ref.standard_id IS '标准ID';
+COMMENT ON COLUMN mdm_ctct_standard_ref.clause_code IS '条款号';
+COMMENT ON COLUMN mdm_ctct_standard_ref.is_primary IS '是否主要引用';
+
+-- 索引（见 §1.8 命名规范）
+CREATE INDEX idx_ctct_ref_ctct_id ON mdm_ctct_standard_ref (ctct_id);
+CREATE INDEX idx_ctct_ref_standard_id ON mdm_ctct_standard_ref (standard_id);
+```
+
+### 1.8 索引规范
+
+#### 1.8.1 索引命名
+
+| 索引类型 | 命名格式 | 示例 |
+|---------|---------|------|
+| 主键 | `pk_{table}` 或直接 `PRIMARY KEY` | 内建 |
+| 唯一索引 | `uk_{table}_{field}` | `uk_customer_code` |
+| 复合唯一 | `uk_{table}_{field1}_{field2}` | `uk_ctct_version` |
+| 普通索引 | `idx_{table}_{field}` | `idx_customer_status` |
+
+#### 1.8.2 索引创建语法
+
+PostgreSQL 的索引通过独立 `CREATE INDEX` 语句创建（不在 CREATE TABLE 内部）：
+
+```sql
+-- 唯一索引（全表唯一，不含逻辑删除条件）
+CREATE UNIQUE INDEX uk_customer_code ON mdm_customer (code);
+
+-- 普通索引
+CREATE INDEX idx_customer_status ON mdm_customer (status);
+
+-- 复合索引
+CREATE INDEX idx_customer_group_status ON mdm_customer (customer_group, status);
+
+-- 降序索引
+CREATE INDEX idx_customer_create_time ON mdm_customer (create_time DESC);
+```
+
+> **注意**：上述 `uk_customer_code` 为全表唯一约束。逻辑删除场景下应改用部分索引（见 §1.8.3），避免已删除记录占用唯一空间。
+
+#### 1.8.3 部分索引（PostgreSQL 特有）
+
+利用 `WHERE` 子句仅索引满足条件的行，大幅减小索引体积：
+
+```sql
+-- 仅索引未删除的记录（逻辑删除场景首选）
+CREATE UNIQUE INDEX uk_customer_code_active ON mdm_customer (code) WHERE deleted = 0;
+
+-- 仅索引特定状态的记录
+CREATE INDEX idx_order_pending ON biz_order (create_time) WHERE status = 'PENDING';
+```
+
+> **最佳实践**：对逻辑删除的表，唯一约束应使用部分索引 `WHERE deleted = 0`，避免已删除记录的编码占用唯一空间。
+
+#### 1.8.4 并发创建索引（生产环境必用）
+
+```sql
+-- 生产环境在线加索引，避免锁表
+CREATE INDEX CONCURRENTLY idx_customer_status ON mdm_customer (status);
+```
+
+> **注意**：`CONCURRENTLY` 不能与 `CREATE INDEX` 放在事务块中，且不支持 `IF NOT EXISTS`。
+
+#### 1.8.5 覆盖索引（INCLUDE）
+
+PostgreSQL 11+ 支持 `INCLUDE` 子句，将非索引列包含进叶子节点以支持 Index-Only Scan：
+
+```sql
+CREATE INDEX idx_order_status ON biz_order (status) INCLUDE (id, order_no, amount);
+```
+
+### 1.9 不使用外键约束
+
+- 本项目不使用数据库 `FOREIGN KEY`，关联关系在代码层面维护
+- PostgreSQL 中同样不添加外键约束，与 MySQL 规范保持一致
+
+### 1.10 表尾与 updateTime 自动更新
+
+#### 1.10.1 应用层更新（默认方案）
+
+项目的 `DefaultDBFieldHandler`（MyBatis Plus `MetaObjectHandler` 实现）已在应用层自动填充 `update_time`，**无需数据库触发器**。此方案适用于所有环境，为默认选择。
+
+#### 1.10.2 数据库触发器（可选方案）
+
+如需在直接操作数据库（如运维脚本、数据迁移）时也能自动更新 `update_time`，可创建触发器：
+
+```sql
+-- 通用触发器函数（建一次，所有表复用）
+CREATE OR REPLACE FUNCTION fn_update_timestamp()
+RETURNS TRIGGER AS $$
+BEGIN
+    NEW.update_time := CURRENT_TIMESTAMP;
+    RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+-- 在目标表上绑定触发器
+CREATE TRIGGER trg_mdm_customer_update
+    BEFORE UPDATE ON mdm_customer
+    FOR EACH ROW
+    EXECUTE FUNCTION fn_update_timestamp();
+```
+
+> **语法说明**：PL/pgSQL 中赋值使用 `:=`（PG 14+ 也支持 `=`，但 `:=` 为传统写法，可读性更好）。
+
+> **使用建议**：开发/测试环境依赖应用层即可；生产环境如 DBA 要求数据库层面保障，可按需添加触发器。
+
+### 1.11 完整建表示例
+
+```sql
+-- 客户主数据表 — 数据库表结构
+-- 数据库: PostgreSQL 16+
+-- 生成日期: 2026-07-27
+-- 模块: sie-module-mdm
+
+SET client_encoding = 'UTF8';
+SET standard_conforming_strings = ON;
+
+-- ========== 表结构 ==========
+CREATE TABLE mdm_customer (
+    id              BIGSERIAL      PRIMARY KEY,
+    code            VARCHAR(64)    NOT NULL DEFAULT '',
+    name            VARCHAR(255)   NOT NULL DEFAULT '',
+    customer_group  VARCHAR(32)    NOT NULL DEFAULT '',
+    lifecycle_status VARCHAR(32)   NOT NULL DEFAULT 'DRAFT',
+    ext_json        JSONB,
+    tenant_id       BIGINT         NOT NULL DEFAULT 0,
+    creator         VARCHAR(64)    DEFAULT '',
+    create_time     TIMESTAMP      NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updater         VARCHAR(64)    DEFAULT '',
+    update_time     TIMESTAMP      NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    deleted         SMALLINT       NOT NULL DEFAULT 0,
+    deleted_time    TIMESTAMP      DEFAULT NULL
+);
+
+-- ========== 注释 ==========
+COMMENT ON TABLE mdm_customer IS '客户主数据表';
+COMMENT ON COLUMN mdm_customer.id IS '主键ID';
+COMMENT ON COLUMN mdm_customer.code IS '客户编码';
+COMMENT ON COLUMN mdm_customer.name IS '客户名称';
+COMMENT ON COLUMN mdm_customer.customer_group IS '客户分组';
+COMMENT ON COLUMN mdm_customer.lifecycle_status IS '生命周期状态';
+COMMENT ON COLUMN mdm_customer.ext_json IS '扩展属性（JSONB）';
+COMMENT ON COLUMN mdm_customer.tenant_id IS '租户ID';
+COMMENT ON COLUMN mdm_customer.creator IS '创建者';
+COMMENT ON COLUMN mdm_customer.create_time IS '创建时间';
+COMMENT ON COLUMN mdm_customer.updater IS '更新者';
+COMMENT ON COLUMN mdm_customer.update_time IS '更新时间';
+COMMENT ON COLUMN mdm_customer.deleted IS '逻辑删除标志';
+
+-- ========== 索引 ==========
+-- 部分唯一索引：仅未删除记录参与唯一约束（见 §1.8.3）
+CREATE UNIQUE INDEX uk_customer_code_active ON mdm_customer (code) WHERE deleted = 0;
+CREATE INDEX idx_customer_tenant_status ON mdm_customer (tenant_id, lifecycle_status);
+CREATE INDEX idx_customer_group ON mdm_customer (customer_group);
+CREATE INDEX idx_customer_create_time ON mdm_customer (create_time DESC);
+
+-- ========== JSONB GIN 索引（对 ext_json 做键值查询加速，见 §2.3）==========
+CREATE INDEX idx_customer_ext_json ON mdm_customer USING GIN (ext_json);
+```
+
+---
+
+## 2. JSONB 使用规范（PostgreSQL 专属）
+
+PostgreSQL 的 `JSONB` 类型相比 MySQL 的 `JSON`，具备索引、键路径查询、包含运算等强大能力，应充分利用。
+
+### 2.1 类型选择
+
+| 场景 | 类型 | 说明 |
+|------|------|------|
+| 结构化半透明数据 | `JSONB` | 支持索引与运算，写入稍慢但读取快 |
+| 原始 JSON 文档（不查询） | `JSON` | 保留原始格式，仅存储用（极少使用） |
+| **本项目统一选择** | **`JSONB`** | 全部替换 MySQL `JSON` |
+
+### 2.2 字段规范
+
+- JSONB 字段**不允许设置默认值**，统一 `DEFAULT NULL`
+- 列名建议使用 `ext_json`、`config_json`、`metadata` 等语义化命名
+- 必须创建 GIN 索引（如需按 key 查询）
+
+### 2.3 GIN 索引
+
+```sql
+-- 全局 GIN 索引：支持 @>（包含）、?（键存在）、?|、?& 运算
+CREATE INDEX idx_{table}_{col}_gin ON {table} USING GIN ({column});
+
+-- 路径_ops 索引：支持 jsonb_path_ops（仅支持 @>，索引更小更快）
+CREATE INDEX idx_{table}_{col}_path ON {table} USING GIN ({column} jsonb_path_ops);
+```
+
+### 2.4 常用查询方式（MyBatis Plus / XML Mapper）
+
+```sql
+-- 包含运算：ext_json 包含 {"industry": "AUTOMOTIVE"}
+SELECT * FROM mdm_customer WHERE ext_json @> '{"industry": "AUTOMOTIVE"}';
+
+-- 键存在判断（⚠️ 在 MyBatis XML Mapper 中 `?` 会与 JDBC 参数占位符冲突，改用函数形式）
+-- 原生 SQL：SELECT * FROM mdm_customer WHERE ext_json ? 'certifications';
+-- MyBatis XML 写法：
+SELECT * FROM mdm_customer WHERE jsonb_exists(ext_json, 'certifications');
+
+-- 提取值（-> 返回 JSONB，->> 返回 TEXT）
+SELECT ext_json->>'industry' AS industry FROM mdm_customer;
+
+-- 嵌套路径提取（#>> 取文本）
+SELECT ext_json #>> '{address,city}' AS city FROM mdm_customer;
+
+-- jsonb_path_query（SQL/JSON Path 语法，PG 12+）
+SELECT * FROM mdm_customer
+WHERE jsonb_path_match(ext_json, '$.tags[*] == "VIP"');
+```
+
+> **MyBatis XML 中的 JSONB 运算符映射**：
+>
+> | 原生运算符 | MyBatis XML 函数形式 | 说明 |
+> |-----------|---------------------|------|
+> | `?` | `jsonb_exists(col, key)` | 键存在判断 |
+> | `?\|` | `jsonb_exists_any(col, array)` | 任一键存在 |
+> | `?&` | `jsonb_exists_all(col, array)` | 全部键存在 |
+> | `@>` | `@>` 可直接使用 | 包含运算，不与 JDBC 冲突 |
+> | `->>` | `->>` 可直接使用 | 文本提取 |
+
+### 2.5 Java 类型映射
+
+在 DO 实体中使用 `String` 或 `Map<String, Object>`，配合 MyBatis Plus 的 `JacksonTypeHandler`：
+
+```java
+@TableName(value = "mdm_customer", autoResultMap = true)
+public class MdmCustomerDO extends TenantBaseDO {
+
+    // 方式一：String（自行序列化/反序列化）
+    private String extJson;
+
+    // 方式二：Map（框架自动 Jackson 序列化，推荐）
+    @TableField(typeHandler = JacksonTypeHandler.class)
+    private Map<String, Object> extJson;
+}
+```
+
+> **重要**：使用 `typeHandler` 时，DO 类必须加 `@TableName(autoResultMap = true)`。
+
+---
+
+## 3. PostgreSQL 特有功能使用规范
+
+### 3.1 数组类型
+
+对于简单的标签、ID 列表等场景，可使用 PostgreSQL 原生数组（替代 MySQL 的逗号分隔字符串或关联表）：
+
+```sql
+-- 标签数组
+tags TEXT[] NOT NULL DEFAULT '{}',
+
+-- 整数数组
+related_org_ids BIGINT[] NOT NULL DEFAULT '{}',
+```
+
+Java 映射（MyBatis Plus 需自定义 TypeHandler 或使用框架内置 `ArrayTypeHandler`）：
+
+```java
+@TableField(typeHandler = ArrayTypeHandler.class)
+private List<String> tags;
+```
+
+> **使用边界**：仅在不需要对数组元素做独立索引/外键关联时使用。频繁按元素查询的场景应拆为子表。
+
+### 3.2 全文搜索（简要）
+
+PostgreSQL 内建全文搜索能力，无需额外组件（轻量场景替代 Elasticsearch）：
+
+```sql
+-- 添加 tsvector 生成列
+ALTER TABLE mdm_customer ADD COLUMN search_tsv TSVECTOR
+    GENERATED ALWAYS AS (
+        to_tsvector('simple', coalesce(name, '') || ' ' || coalesce(code, ''))
+    ) STORED;
+
+-- GIN 索引加速搜索
+CREATE INDEX idx_customer_search ON mdm_customer USING GIN (search_tsv);
+
+-- 查询
+SELECT * FROM mdm_customer WHERE search_tsv @@ plainto_tsquery('simple', '华东客户');
+```
+
+> **适用场景**：中小型数据量（<500 万行）的模糊搜索；大数据量仍建议 Elasticsearch。
+
+### 3.3 RETURNING 子句
+
+PostgreSQL 的 `INSERT ... RETURNING` / `UPDATE ... RETURNING` 可在写操作后直接返回任意列值，无需额外查询：
+
+```sql
+-- 插入后返回生成的 ID 和创建时间
+INSERT INTO mdm_customer (code, name) VALUES ('C001', '华东客户')
+RETURNING id, create_time;
+
+-- 更新后返回修改后的完整行
+UPDATE mdm_customer SET name = '新客户' WHERE id = 1
+RETURNING id, code, name, update_time;
+
+-- 批量插入返回
+INSERT INTO mdm_customer (code, name) VALUES ('C001', 'A'), ('C002', 'B')
+RETURNING id, code;
+```
+
+> **与 MySQL 的差异**：MySQL 的 JDBC `getGeneratedKeys()` 仅能获取自增主键；PostgreSQL 的 `RETURNING` 可返回表中任意列，省去回查开销。
+>
+> **MyBatis Plus 已内建支持**：`@TableId(type = IdType.AUTO)` + `BIGSERIAL` 通过 JDBC `getGeneratedKeys` 自动获取主键。手写 SQL 时可在 XML Mapper 中利用 `RETURNING` 返回非主键字段，进一步优化批量操作。
+
+### 3.4 UPSERT（ON CONFLICT）
+
+PostgreSQL 的 `INSERT ... ON CONFLICT` 实现 upsert 语义：
+
+```sql
+-- 场景一：唯一索引为全表唯一（普通唯一约束）
+INSERT INTO mdm_customer (code, name, tenant_id)
+VALUES ('C001', '华东客户', 1)
+ON CONFLICT (code)
+DO UPDATE SET name = EXCLUDED.name, update_time = CURRENT_TIMESTAMP;
+
+-- 场景二：唯一索引为部分索引（WHERE deleted = 0）
+-- 注意：ON CONFLICT 推断部分索引需要 PostgreSQL 15+（本项目 PG 16+ 已满足）
+INSERT INTO mdm_customer (code, name, tenant_id)
+VALUES ('C001', '华东客户', 1)
+ON CONFLICT (code) WHERE deleted = 0
+DO UPDATE SET name = EXCLUDED.name, update_time = CURRENT_TIMESTAMP;
+```
+
+### 3.5 部分索引与覆盖索引
+
+见 §1.8.3 和 §1.8.5。核心原则：
+
+- **部分索引**：对逻辑删除表，唯一索引加 `WHERE deleted = 0`
+- **覆盖索引**：高频查询的字段通过 `INCLUDE` 放入索引叶子，避免回表
+
+---
+
+## 4. 查询优化规范
+
+### 4.1 分页查询优化
+
+**深分页问题**：`OFFSET N` 性能随偏移量线性下降，大偏移量分页使用 Keyset Pagination：
+
+```sql
+-- 传统分页（偏移量大时慢）
+SELECT * FROM mdm_customer ORDER BY id LIMIT 20 OFFSET 10000;
+
+-- Keyset 分页（推荐，性能恒定）
+SELECT * FROM mdm_customer WHERE id > {last_id} ORDER BY id LIMIT 20;
+```
+
+Java 层实现：在 `PageReqVO` 中增加 `minId` 字段，Service 层根据上一页最后一条记录的 ID 构造查询条件。
+
+### 4.2 COUNT 优化
+
+对于逻辑删除表的全表 COUNT，可使用部分索引加速：
+
+```sql
+-- 创建计数用部分索引
+CREATE INDEX idx_customer_active ON mdm_customer (id) WHERE deleted = 0;
+
+-- 查询活跃记录数（走部分索引）
+SELECT count(*) FROM mdm_customer WHERE deleted = 0;
+```
+
+### 4.3 EXISTS 与 IN 的选择
+
+对于子查询判断存在性，优先使用 `EXISTS`（语义更清晰，大子查询集性能更稳定）：
+
+```sql
+-- 推荐：语义清晰，不受子查询结果集大小影响
+SELECT * FROM mdm_customer c
+WHERE EXISTS (SELECT 1 FROM mdm_ctct ct WHERE ct.customer_id = c.id);
+
+-- 可接受：PG 优化器会自动转为 Semi-Join，性能通常与 EXISTS 等价
+SELECT * FROM mdm_customer
+WHERE id IN (SELECT customer_id FROM mdm_ctct);
+```
+
+> **PG 优化器说明**：现代 PostgreSQL（12+）对 `IN (subquery)` 会自动转换为 Semi-Join，大多数场景下性能与 `EXISTS` 无差异。但当子查询结果集极大、且主表较小时，`EXISTS` 短路求值更稳定。建议统一使用 `EXISTS` 保持代码可读性。
+
+### 4.4 批量操作
+
+批量 INSERT 使用多行 VALUES 或 `COPY`（大数据量导入）：
+
+```sql
+-- 多行 VALUES（常规批量，建议单批 ≤ 1000 行）
+INSERT INTO mdm_customer (code, name) VALUES
+('C001', '客户A'),
+('C002', '客户B'),
+('C003', '客户C');
+
+-- COPY（大数据量导入，CSV 格式）
+COPY mdm_customer (code, name, tenant_id) FROM '/data/import.csv' WITH (FORMAT csv, HEADER true);
+```
+
+> **MyBatis Plus 的 `insertBatch`** 已自动使用多行 VALUES 方式，默认批量大小可通过配置调整。
+
+### 4.5 EXPLAIN 分析
+
+所有复杂查询必须用 `EXPLAIN (ANALYZE, BUFFERS)` 验证执行计划：
+
+```sql
+EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT)
+SELECT * FROM mdm_customer WHERE lifecycle_status = 'APPROVED' ORDER BY create_time DESC LIMIT 20;
+```
+
+关注指标：
+- **Seq Scan**（全表扫描）：大表出现时为性能问题
+- **Index Scan / Index Only Scan**：理想执行方式
+- **Buffers: shared hit**：缓存命中率，越高越好
+- **Actual Time**：实际执行时间（ms）
+
+---
+
+## 5. 数据字典规范
+
+### 5.1 目标表
+
+数据字典由两张表组成：
+
+**字典类型表** `system_dict_type`（字典分组/分类）：
+`id`, `name`, `type`, `status`, `remark`, `creator`, `create_time`, `updater`, `update_time`, `deleted`, `deleted_time`
+
+**字典数据表** `system_dict_data`（字典具体选项）：
+`id`, `sort`, `label`, `value`, `dict_type`, `status`, `color_type`, `css_class`, `remark`, `creator`, `create_time`, `updater`, `update_time`, `deleted`
+
+> **插入顺序要求**：必须先向 `system_dict_type` 插入字典类型记录，再向 `system_dict_data` 插入对应的字典数据。`system_dict_data.dict_type` 的值必须与 `system_dict_type.type` 的值一致。
+
+### 5.2 字典类型表（system_dict_type）
+
+| 字段 | 类型 | 规则 |
+|------|------|------|
+| `id` | BIGINT | 自增主键 |
+| `name` | VARCHAR | 字典类型的中文名称，如 "客户状态" |
+| `type` | VARCHAR | 字典类型的英文标识，如 `customer_status`，必须全小写下划线分隔 |
+| `status` | SMALLINT | `0`=启用，`1`=禁用（对应 `CommonStatusEnum`） |
+| `remark` | VARCHAR | 备注说明 |
+
+### 5.3 字典数据表（system_dict_data）
+
+| 字段 | 类型 | 规则 |
+|------|------|------|
+| `id` | BIGINT | 自增主键 |
+| `sort` | INTEGER | 显示顺序，越小越靠前；实际数据中以 `1` 为步长递增 |
+| `label` | VARCHAR | 显示标签，如 "待审核" |
+| `value` | VARCHAR | 实际存储值，对应 Java Enum 的 `name()` 值或数值字符串 |
+| `dict_type` | VARCHAR | 所属字典类型标识，必须与 `system_dict_type.type` 一致 |
+| `status` | SMALLINT | `0`=启用，`1`=禁用 |
+| `color_type` | VARCHAR | 标签颜色类型，见下方颜色约定 |
+| `css_class` | VARCHAR | 自定义 CSS 类名，通常为空字符串 `''` |
+
+### 5.4 字典类型覆盖范围
+
+必须覆盖 spec 中定义的所有枚举类型，包括：
+- 业务状态枚举（如 `customer_status`、`lifecycle_status`）
+- 分类枚举（如 `customer_group`、`csr_type`、`pcr_type`）
+- 行为/动作枚举（如 `csr_trigger_action`、`delivery_pattern`）
+- 配置枚举（如 `ppap_level`、`contract_type`、`sync_scope`）
+
+### 5.5 颜色类型约定
+
+| 场景 | color_type |
+|------|-----------|
+| 成功/启用/生效 | `success` |
+| 警告/待处理 | `warning` |
+| 危险/禁止/失效 | `danger` |
+| 普通/信息 | `info` |
+| 主要业务标识 | `primary` |
+| 默认/无特殊含义 | `default` |
+
+### 5.6 字典值约定
+
+- 布尔型枚举：`0`/`1`
+- 枚举字符串值：使用 Java Enum 的 `name()` 值（如 `AUTOMOTIVE`、`DRAFT`、`INSPECT`）
+- 数值型枚举：使用数值字符串（如 `1`~`5` 对应 PPAP 等级）
+
+### 5.7 示例 SQL
+
+> **重要**：必须先插入 `system_dict_type`，再插入 `system_dict_data`。
+
+```sql
+-- 步骤1: 先创建字典类型
+INSERT INTO system_dict_type (name, type, status, remark, creator, create_time, updater, update_time, deleted)
+VALUES ('客户状态', 'customer_status', 0, 'MDM 客户生命周期状态', '1', CURRENT_TIMESTAMP, '1', CURRENT_TIMESTAMP, 0);
+
+INSERT INTO system_dict_type (name, type, status, remark, creator, create_time, updater, update_time, deleted)
+VALUES ('客户分组', 'customer_group', 0, 'MDM 客户分类分组', '1', CURRENT_TIMESTAMP, '1', CURRENT_TIMESTAMP, 0);
+
+-- 步骤2: 再插入字典数据
+INSERT INTO system_dict_data (sort, label, value, dict_type, status, color_type, css_class, remark, creator, create_time, updater, update_time, deleted)
+VALUES (1, '草稿', 'DRAFT', 'customer_status', 0, 'info', '', '未提交审核', '1', CURRENT_TIMESTAMP, '1', CURRENT_TIMESTAMP, 0);
+
+INSERT INTO system_dict_data (sort, label, value, dict_type, status, color_type, css_class, remark, creator, create_time, updater, update_time, deleted)
+VALUES (2, '已审核', 'APPROVED', 'customer_status', 0, 'success', '', '审核通过', '1', CURRENT_TIMESTAMP, '1', CURRENT_TIMESTAMP, 0);
+
+INSERT INTO system_dict_data (sort, label, value, dict_type, status, color_type, css_class, remark, creator, create_time, updater, update_time, deleted)
+VALUES (3, '已冻结', 'FROZEN', 'customer_status', 0, 'danger', '', '禁止交易', '1', CURRENT_TIMESTAMP, '1', CURRENT_TIMESTAMP, 0);
+```
+
+### 5.8 注意事项
+
+- **插入顺序**：必须先插入 `system_dict_type`，再插入 `system_dict_data`，否则字典数据无类型归属
+- `system_dict_data.dict_type` 必须与 `system_dict_type.type` 严格一致
+- 同一 `dict_type` 下的 `value` 值不可重复
+- `dict_type` 命名采用全小写 + 下划线分隔格式，如 `customer_status`
+- 字典数据表同样使用 `BaseDO` 审计字段，不含 `tenant_id`
+
+---
+
+## 6. 菜单数据规范
+
+### 6.1 菜单表结构
+
+数据写入 `system_menu` 表（系统内置菜单权限表），表结构为：
+`id`, `name`, `permission`, `type`, `sort`, `parent_id`, `path`, `icon`, `component`, `component_name`, `status`, `visible`, `keep_alive`, `always_show`, `creator`, `create_time`, `updater`, `update_time`, `deleted`
+
+该表使用 `BaseDO` 审计字段，**不包含 `tenant_id`**（菜单为全局共享数据，通过 `@TenantIgnore` 注解忽略租户隔离）。
+
+### 6.2 菜单类型（type）
+
+| type 值 | 含义 | 说明 | 必填字段 |
+|---------|------|------|---------|
+| 1 | 目录 | 一级/二级导航分组，无实际页面 | `name`, `path`, `icon`, `sort`, `parent_id` |
+| 2 | 菜单 | 实际可访问的页面 | `name`, `path`, `icon`, `component`, `sort`, `parent_id` |
+| 3 | 按钮 | 页面内的操作按钮，仅用于权限控制 | `name`, `permission`, `parent_id` |
+
+### 6.3 字段填写规则
+
+| 字段 | 类型 | 规则 |
+|------|------|------|
+| `id` | BIGINT | 自增主键；新模块菜单 ID 从 `6000` 起始分配 |
+| `name` | VARCHAR | 菜单/目录/按钮的中文显示名称 |
+| `permission` | VARCHAR | 权限标识，格式 `${system}:${resource}:${action}` |
+| `type` | SMALLINT | `1`=目录，`2`=菜单，`3`=按钮 |
+| `sort` | INTEGER | 同级排序值，越小越靠前 |
+| `parent_id` | BIGINT | 父菜单 ID，根目录为 `0` |
+| `path` | VARCHAR | 路由路径；目录/菜单必填 |
+| `icon` | VARCHAR | 图标名称，使用 `ep:` 或 `fa:` 前缀 |
+| `component` | VARCHAR | 前端组件路径；仅菜单类型必填 |
+| `component_name` | VARCHAR | 组件名称（用于 keep-alive 缓存） |
+| `status` | SMALLINT | `0`=启用，`1`=禁用 |
+| `visible` | BOOLEAN | `TRUE`=侧边栏可见，`FALSE`=隐藏 |
+| `keep_alive` | BOOLEAN | `TRUE`=缓存页面状态，`FALSE`=不缓存；默认 `TRUE` |
+| `always_show` | BOOLEAN | `TRUE`=始终显示父级，`FALSE`=单子菜单时折叠；默认 `TRUE` |
+
+### 6.4 目录结构层级
+
+```text
+目录 (type=1, parent_id=0)          ← 一级导航，如 "主数据管理"
+ └─ 目录 (type=1, parent_id=父ID)    ← 二级分组（可选），如 "客户管理"
+     └─ 菜单 (type=2, parent_id=父ID) ← 实际页面，如 "客户列表"
+         ├─ 按钮 (type=3, parent_id=菜单ID) ← "客户创建"
+         ├─ 按钮 (type=3, parent_id=菜单ID) ← "客户修改"
+         └─ 按钮 (type=3, parent_id=菜单ID) ← "客户删除"
+```
+
+### 6.5 权限标识命名规则
+
+| 操作 | permission 示例 |
+|------|----------------|
+| 查询 | `mdm:customer:query` |
+| 创建 | `mdm:customer:create` |
+| 更新 | `mdm:customer:update` |
+| 删除 | `mdm:customer:delete` |
+| 导出 | `mdm:customer:export` |
+| 导入 | `mdm:customer:import` |
+
+### 6.6 示例 SQL
+
+```sql
+-- MDM 模块 - 主数据管理目录
+INSERT INTO system_menu (id, name, permission, type, sort, parent_id, path, icon, component, component_name, status, visible, keep_alive, always_show, creator, create_time, updater, update_time, deleted)
+VALUES (5000, '主数据管理', '', 1, 10, 0, '/mdm', 'ep:menu', NULL, NULL, 0, TRUE, TRUE, TRUE, '1', CURRENT_TIMESTAMP, '1', CURRENT_TIMESTAMP, 0);
+
+-- 客户管理菜单
+INSERT INTO system_menu (id, name, permission, type, sort, parent_id, path, icon, component, component_name, status, visible, keep_alive, always_show, creator, create_time, updater, update_time, deleted)
+VALUES (5010, '客户管理', 'mdm:customer:query', 2, 10, 5000, 'customer', 'ep:user', 'mdm/customer/index', 'MdmCustomer', 0, TRUE, TRUE, TRUE, '1', CURRENT_TIMESTAMP, '1', CURRENT_TIMESTAMP, 0);
+
+-- 客户创建按钮
+INSERT INTO system_menu (id, name, permission, type, sort, parent_id, path, icon, component, component_name, status, visible, keep_alive, always_show, creator, create_time, updater, update_time, deleted)
+VALUES (5011, '客户创建', 'mdm:customer:create', 3, 1, 5010, '', '#', NULL, NULL, 0, TRUE, TRUE, TRUE, '1', CURRENT_TIMESTAMP, '1', CURRENT_TIMESTAMP, 0);
+```
+
+### 6.7 注意事项
+
+- 新模块菜单 ID 范围需在模块设计文档中提前约定，避免与已有模块冲突
+- 按钮类型（type=3）的 `path`、`icon`、`component` 字段必须为 NULL 或空字符串
+- 目录类型（type=1）的 `component` 字段必须为 NULL
+- 删除菜单时需先检查 `system_role_menu` 中是否有关联数据
+- 菜单数据通过 `@TenantIgnore` 全局共享，不随租户隔离
+
+---
+
+## 7. 连接池与持久层配置规范
+
+### 7.1 Druid 连接池（PostgreSQL）
+
+```yaml
+spring:
+  datasource:
+    druid:
+      driver-class-name: org.postgresql.Driver
+      url: jdbc:postgresql://localhost:5432/ultracloud?currentSchema=public&stringtype=unspecified
+      username: ultracloud
+      password: ${DB_PASSWORD}
+      # 连接池参数
+      initial-size: 5
+      min-idle: 10
+      max-active: 50
+      max-wait: 600000
+      # 检测配置
+      validation-query: SELECT 1
+      test-while-idle: true
+      test-on-borrow: false
+      test-on-return: false
+      time-between-eviction-runs-millis: 60000
+      min-evictable-idle-time-millis: 300000
+```
+
+> **关键差异**：
+> - `driver-class-name` 使用 `org.postgresql.Driver`
+> - URL 协议为 `jdbc:postgresql://`
+> - `validation-query` 使用 `SELECT 1`（与 MySQL 相同，PG 也支持）
+> - `currentSchema=public` 指定默认 schema（多 schema 场景必配）
+> - **`stringtype=unspecified`**（关键参数）：MyBatis 向 PG 传递参数时，默认会将 `String` 类型标记为 `varchar`。当目标列类型为 `uuid`、`jsonb`、`timestamp` 等非字符串类型时，PG 严格模式下会报 `column is of type X but expression is of type varchar` 错误。设置 `stringtype=unspecified` 后，PG 会自动做隐式类型转换，避免此类问题。
+
+### 7.2 MyBatis Plus PostgreSQL 配置
+
+```yaml
+mybatis-plus:
+  configuration:
+    # PostgreSQL 的 mapUnderscoreToCamelCase 默认开启
+    map-underscore-to-camel-case: true
+    # 日志（开发环境）
+    log-impl: org.apache.ibatis.logging.slf4j.Slf4jImpl
+  global-config:
+    db-config:
+      # ID 策略：AUTO 对应 BIGSERIAL，ASSIGN_ID 对应雪花
+      id-type: auto
+      # 逻辑删除（SMALLINT 0/1 映射，与系统表 system_dict_type 一致）
+      # BaseDO.deleted 为 Boolean 类型，配合整数 0/1：
+      #   生成 SQL WHERE deleted = 0 / SET deleted = 1
+      #   SMALLINT 列 smallint = integer 可隐式转换（PostgreSQL 支持）
+      #   禁止用 BOOLEAN 列，否则报错"操作符不存在: boolean = integer"
+      logic-delete-field: deleted
+      logic-delete-value: 1
+      logic-not-delete-value: 0
+      # 表前缀（按模块配置）
+      table-prefix: ''
+  # 类型处理器（JSONB 支持）
+  type-handlers-package: cn.ultracloud.com.framework.mybatis.core.handler
+```
+
+> **逻辑删除配置**：`logic-delete-value: 1` / `logic-not-delete-value: 0` 对应 `SMALLINT` 类型（0/1 整数），与项目系统表 `system_dict_type` 一致。**禁止将 `deleted` 列定义为 `BOOLEAN`**——`BaseDO.deleted` 为 `Boolean` 类型但逻辑删除值为整数，PostgreSQL 不支持 `boolean = integer` 隐式转换，会报错"操作符不存在: boolean = integer"。
+
+### 7.3 application.yml 多环境 Profile
+
+```yaml
+# application-dev.yml（开发环境）
+spring:
+  datasource:
+    druid:
+      url: jdbc:postgresql://localhost:5432/ultracloud_dev?currentSchema=public&stringtype=unspecified
+
+# application-unit-test.yml（单元测试环境）
+# 使用 Testcontainers 动态启动 PostgreSQL 容器（见 §8）
+```
+
+---
+
+## 8. 单元测试数据库规范
+
+### 8.1 测试数据库选型
+
+| 方案 | 说明 | 推荐场景 |
+|------|------|---------|
+| **Testcontainers PostgreSQL** | 真实 PG 容器，与生产一致 | **首选方案** |
+| H2（PostgreSQL 兼容模式） | 内存运行，速度快但功能不全 | 简单单元测试 |
+| 嵌入式 PostgreSQL（embedded-postgres） | 进程内 PG，无需 Docker | 无 Docker 环境 |
+
+### 8.2 Testcontainers 方案（推荐）
+
+```java
+@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.NONE)
+@ActiveProfiles("unit-test")
+@Testcontainers
+class WmsWarehouseServiceImplTest {
+
+    @Container
+    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16-alpine")
+            .withDatabaseName("ultracloud_test")
+            .withUsername("test")
+            .withPassword("test");
+
+    @DynamicPropertySource
+    static void configureProperties(DynamicPropertyRegistry registry) {
+        registry.add("spring.datasource.url", postgres::getJdbcUrl);
+        registry.add("spring.datasource.username", postgres::getUsername);
+        registry.add("spring.datasource.password", postgres::getPassword);
+    }
+
+    @Resource
+    private WmsWarehouseServiceImpl warehouseService;
+
+    @Test
+    void testCreateWarehouse_success() {
+        // ...
+    }
+}
+```
+
+### 8.3 测试 SQL 脚本
+
+- 创建表脚本：`src/test/resources/sql/create_tables.sql`（使用 PostgreSQL 语法）
+- 清理脚本：`src/test/resources/sql/clean.sql`（每个测试方法执行后运行）
+- 脚本中使用 `BIGSERIAL`、`BOOLEAN`、`TIMESTAMP` 等 PG 类型
+
+---
+
+## 9. 性能优化与运维规范
+
+### 9.1 VACUUM 与 ANALYZE
+
+PostgreSQL 使用 MVCC，更新/删除产生"死元组"，需定期清理：
+
+```sql
+-- 手动分析（更新统计信息，优化器使用）
+ANALYZE mdm_customer;
+
+-- 手动清理（回收死元组空间）
+VACUUM ANALYZE mdm_customer;
+
+-- 强制回收磁盘空间（会排他锁表，生产慎用）
+VACUUM FULL mdm_customer;
+```
+
+> **建议**：开启 `autovacuum`（默认开启），对高频更新表调整 `autovacuum_vacuum_scale_factor` 为更小值（如 `0.01`）。
+
+### 9.2 连接池监控
+
+通过 Druid Monitor 或 Spring Boot Actuator 监控：
+
+| 指标 | 说明 | 告警阈值 |
+|------|------|---------|
+| `activeCount` | 活跃连接数 | > `max-active * 0.8` |
+| `waitThreadCount` | 等待连接的线程数 | > 0 |
+| `errorCount` | SQL 执行错误数 | > 0 |
+| `executeMillisMax` | 最慢 SQL 执行时间（ms） | > 1000 |
+
+### 9.3 慢查询定位
+
+```sql
+-- 查看当前正在执行的慢查询（> 1s）
+SELECT pid, now() - pg_stat_activity.query_start AS duration, query, state
+FROM pg_stat_activity
+WHERE (now() - pg_stat_activity.query_start) > interval '1 second'
+  AND state != 'idle';
+
+-- 取消慢查询
+SELECT pg_cancel_backend(<pid>);
+```
+
+### 9.4 常用维护 SQL
+
+```sql
+-- 查看表大小（含索引）
+SELECT pg_size_pretty(pg_total_relation_size('mdm_customer'));
+
+-- 查看表行数估算（比 COUNT 快得多）
+SELECT reltuples::bigint AS estimated_rows
+FROM pg_class WHERE relname = 'mdm_customer';
+
+-- 查看索引使用情况
+SELECT schemaname, tablename, indexname, idx_scan, idx_tup_read, idx_tup_fetch
+FROM pg_stat_user_indexes
+ORDER BY idx_scan ASC;
+
+-- 查看未使用的索引（idx_scan = 0）
+SELECT schemaname, tablename, indexname
+FROM pg_stat_user_indexes
+WHERE idx_scan = 0;
+```
+
+---
+
+## 10. 数据库迁移规范
+
+### 10.1 迁移工具
+
+推荐使用 **Flyway** 管理数据库版本迁移：
+
+```
+src/main/resources/db/migration/
+├── V1.0.0__init_schema.sql
+├── V1.0.1__add_customer_ext_json.sql
+├── V1.1.0__create_mdm_ctct_table.sql
+└── V1.1.1__add_idx_customer_status.sql
+```
+
+### 10.2 迁移脚本规范
+
+- 文件名格式：`V{version}__{description}.sql`
+- 每个脚本只做一件事（建表 / 加索引 / 改字段）
+- **不修改已执行的脚本**，变更通过新版本脚本实现
+- 所有迁移脚本必须幂等或使用 `IF NOT EXISTS` / `IF EXISTS`：
+
+```sql
+-- 安全的表创建
+CREATE TABLE IF NOT EXISTS mdm_customer (...);
+
+-- 安全的索引创建
+CREATE INDEX IF NOT EXISTS idx_customer_status ON mdm_customer (status);
+
+-- 安全的列添加
+ALTER TABLE mdm_customer ADD COLUMN IF NOT EXISTS ext_json JSONB;
+```
+
+### 10.3 版本与模块对应
+
+| 版本号 | 含义 |
+|--------|------|
+| `V1.0.x` | MDM 模块初始化 |
+| `V1.1.x` | MDM 模块增量变更 |
+| `V2.0.x` | System/Infra 模块 |
+| `V3.0.x` | BPM 模块 |
+| `V4.0.x` | AI 模块 |
+
+---
+
+## 11. MySQL 与 PostgreSQL 对照速查表
+
+| 特性 | MySQL 8.0 | PostgreSQL 16 |
+|------|-----------|---------------|
+| 自增主键 | `AUTO_INCREMENT` | `BIGSERIAL` 或 `GENERATED BY DEFAULT AS IDENTITY` |
+| 布尔类型 | `BIT(1)` / `TINYINT(1)` | `BOOLEAN`（`TRUE`/`FALSE`） |
+| 时间类型 | `DATETIME` | `TIMESTAMP`（无时区）/ `TIMESTAMPTZ`（带时区） |
+| JSON 类型 | `JSON` | `JSONB`（二进制，可索引） |
+| 文本大字段 | `TEXT` / `LONGTEXT` | `TEXT`（无长度限制） |
+| 注释方式 | `COMMENT '...'`（内联） | `COMMENT ON TABLE/COLUMN`（独立语句） |
+| 字符集 | `CHARSET=utf8mb4` | `SET client_encoding = 'UTF8'` |
+| 表引擎 | `ENGINE=InnoDB` | 无需指定 |
+| 排序规则 | `COLLATE=utf8mb4_unicode_ci` | 由数据库/列 Collation 控制 |
+| 自动更新时间 | `ON UPDATE CURRENT_TIMESTAMP` | 触发器 / 应用层 |
+| 外键检查 | `SET FOREIGN_KEY_CHECKS = 0` | 无此概念（可不建 FK） |
+| 唯一约束（逻辑删除） | 不支持条件唯一 | 部分索引 `WHERE deleted = 0` |
+| 并发加索引 | 不支持 | `CREATE INDEX CONCURRENTLY` |
+| 覆盖索引 | 不支持 | `INCLUDE (col1, col2)` |
+| UPSERT | `INSERT ... ON DUPLICATE KEY UPDATE` | `INSERT ... ON CONFLICT DO UPDATE` |
+| 返回值 | 需额外 `SELECT` | `RETURNING` 子句 |
+| 数组类型 | 不支持 | `TEXT[]`、`BIGINT[]` 等 |
+| 全文搜索 | `FULLTEXT`（中文需 ngram） | `TSVECTOR` + `TSQUERY`（中文需 zhparser） |
+
+---
+
+## 12. 禁止事项汇总
+
+1. **禁止使用 MySQL ENUM 类型**（PostgreSQL 的 ENUM 修改不便，统一用 `VARCHAR` + 字典表）
+2. **禁止使用 `JSON` 类型**，统一使用 `JSONB`
+3. **禁止使用 `BIT(1)` 表示布尔值**，真布尔字段（如 `visible`/`keep_alive`/`always_show`/`is_primary`）统一使用 `BOOLEAN`；**逻辑删除字段 `deleted` 例外，统一使用 `SMALLINT`（0/1）+ `deleted_time TIMESTAMP`**
+4. **禁止在表定义中使用 `ENGINE`/`CHARSET`/`COLLATE`**（MySQL 语法，PostgreSQL 不支持）
+5. **禁止不使用 `COMMENT ON` 注释**，每个表和列必须有注释
+6. **禁止在生产环境大表（> 10 万行）上直接 `CREATE INDEX` 不带 `CONCURRENTLY`**（会阻塞写操作）
+7. **禁止唯一约束忽略逻辑删除**，逻辑删除表的唯一索引必须使用 `WHERE deleted = 0`
+8. **禁止使用 `OFFSET` 深分页（OFFSET > 10000）**，大偏移量使用 Keyset Pagination
+9. **禁止不使用 `BIGINT`** 作为主键/外键类型
+10. **禁止在代码中拼接 SQL 字符串**，使用 MyBatis Plus `LambdaQueryWrapperX` 或参数化 XML Mapper
+11. **禁止将 `deleted` 字段定义为 `BOOLEAN` 类型**，必须使用 `SMALLINT`（0=未删除，1=已删除）并配套 `deleted_time TIMESTAMP DEFAULT NULL`。原因：`BaseDO.deleted` 为 `Boolean` 但 MyBatis-Plus 逻辑删除配置为整数 `0/1`，生成 SQL `WHERE deleted = 0`，PostgreSQL 中 `boolean = integer` 不可隐式转换会报错。系统表 `system_dict_type` 即用 `SMALLINT`，以此为统一标准。