一、核心术语与概念 术语 英文 说明 租户（Tenant） tenant 金蝶云平台本身，作为超级租户存在 商户（Merchant） merchant 在金蝶云平台注册并使用金蝶星辰服务的企业客户 二、命名规范 2.1 通用规则 规范项 规范值 说明 字符范围 小写字母、数字、下划线 禁止使用大写字母、驼峰命名、特殊字符 命名长度 ≤ 30 字符 表名、字段名 保留字 禁止使用 如 order、group、desc 等 MySQL 保留关键字 2.2 表命名规范 统一采用 “模块前缀_实体名称” 格式（全小写，下划线分隔），表名使用单数形式。 模块 前缀 表名示例 2.3 字段命名规范 字段类型 命名规范 数据类型 说明 主键 id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT 统一命名 业务编码 code VARCHAR(32) NOT NULL 业务唯一标识 租户编码（L1隔离） tenant_code VARCHAR(32) NOT NULL 所有表必须包含，关联 sys_tenant.code 商户编码（L2隔离） merchant_code VARCHAR(32) DEFAULT NULL 商户业务表包含，关联 sys_merchant.code。 组织编码（L3隔离） org_code VARCHAR(32) DEFAULT NULL 按需包含，关联 org_organization.code 逻辑外键 {关联表名}_code VARCHAR(32) 单数形式，如 user_code、role_code 创建时间 created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP 审计字段 更新时间 updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP 审计字段 删除时间（软删除） deleted_at DATETIME DEFAULT NULL NULL=未删除 创建人 created_by VARCHAR(32) DEFAULT NULL 关联 sys_user.code 更新人 updated_by VARCHAR(32) DEFAULT NULL 关联 sys_user.code 删除人 deleted_by VARCHAR(32) DEFAULT NULL 关联 sys_user.code 审批状态（业务表） approval_status VARCHAR(20) NOT NULL DEFAULT 'draft' 所有审批业务表必须包含，关联字典 approval_status 审批实例关联（业务表） wf_instance_code VARCHAR(32) DEFAULT NULL 所有审批业务表必须包含，关联 wf_instance.code 状态字段 status VARCHAR(10) NOT NULL 关联字典表 类型字段 {业务}_type VARCHAR(20) NOT NULL 关联字典表 布尔字段 is_{状态} 或 {业务}_flag VARCHAR(10) NOT NULL DEFAULT 'false' 关联字典 yes_no 2.4 索引命名规范 表名简称规则：{表名简称} 为表名去掉模块前缀后的核心实体名。 索引类型 命名格式 示例 主键索引 默认使用 id PRIMARY KEY (id) 唯一索引 uk_{表名简称}_{字段名} uk_user_mobile、uk_tenant_username 普通索引 idx_{表名简称}_{字段名} idx_purchase_order_customer_code 组合索引 idx_{表名简称}_{字段1}_{字段2} idx_purchase_order_tenant_status 全文索引 ft_{表名简称}_{字段名} ft_help_article_title_content 索引命名约束： 约束项 说明 组合索引字段名 按实际业务含义缩写，避免索引名超长 总长度 索引名总长度 ≤ 64 字符 三、表设计通用规范 3.1 存储引擎与字符集 规范项 规范值 说明 存储引擎 InnoDB 支持事务、行级锁 字符集 utf8mb4 支持完整 Unicode（含 Emoji） 排序规则 utf8mb4_0900_ai_ci 基于 Unicode 9.0，不区分大小写 sql ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='表注释'; 3.2 必备审计字段 每张业务表必须包含以下审计字段： sql `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', `updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', `deleted_at` DATETIME DEFAULT NULL COMMENT '删除时间（NULL表示未删除）', `created_by` VARCHAR(32) DEFAULT NULL COMMENT '创建人编码，关联 sys_user.code', `updated_by` VARCHAR(32) DEFAULT NULL COMMENT '更新人编码，关联 sys_user.code', `deleted_by` VARCHAR(32) DEFAULT NULL COMMENT '删除人编码，关联 sys_user.code' 3.3 数据隔离层级（多层隔离架构） 隔离层级 字段名 数据类型 约束 说明 金蝶级（L1） tenant_code VARCHAR(32) NOT NULL 所有表必须包含，关联 sys_tenant.code 商户级（L2） merchant_code VARCHAR(32) 根据业务需要 关联 sys_merchant.code。 组织级（L3） org_code VARCHAR(32) DEFAULT NULL 按需包含，关联 org_organization.code 多层隔离：租户级（tenant_code）+ 商户级（merchant_code）双隔离 3.4 主键规范 sql `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '主键', PRIMARY KEY (`id`) 3.5 编码字段（code）规范 sql `code` VARCHAR(32) NOT NULL COMMENT '业务编码（租户+商户内唯一）', UNIQUE KEY `uk_{表名简称}_code` (`tenant_code`, `merchant_code`, `code`) 3.6 逻辑外键规范 规范项 说明 格式 {关联表名}_code（单数形式），如 user_code、role_code 注释要求 必须注明关联的目标表，如 COMMENT='用户编码，关联 sys_user.code' 索引要求 必须建立普通索引 物理外键 禁止使用 FOREIGN KEY 约束，由应用层保证引用完整性 3.7 软删除规范 规范项 说明 主数据表 必须包含 deleted_at 字段，查询时默认过滤 deleted_at IS NULL 关联表 多对多关联表使用物理删除（DELETE），不包含 deleted_at 字段 四、审批业务表特殊规范 4.1 审批关联字段（强制） 所有需要审批的业务表必须包含以下两个字段： sql `approval_status` VARCHAR(20) NOT NULL DEFAULT 'draft' COMMENT '审批状态，关联字典 approval_status。取值：draft-草稿，pending-审批中，approved-已通过，rejected-已驳回，recalled-已撤回', `wf_instance_code` VARCHAR(32) DEFAULT NULL COMMENT '关联的流程实例编码，关联 wf_instance.code' 涉及业务表清单： 模块 表名 说明 五、字段类型与字典规范 5.1 数值类型 业务含义 推荐类型 说明 主键/外键ID BIGINT UNSIGNED 支持海量数据 金额/单价 DECIMAL(18,4) 精确小数，避免浮点误差 税率/百分比 DECIMAL(10,4) 如 13.0000% 数量 DECIMAL(18,4) 支持精确数量 排序号 INT 显示顺序控制 5.2 字符串类型 业务含义 推荐类型 说明 编码/编号 VARCHAR(32) 业务编码统一长度 名称 VARCHAR(200) 名称、简短描述 长文本 TEXT 或 LONGTEXT 备注、JSON 扩展字段 手机号/邮箱 VARCHAR(50) 联系方式 地址 VARCHAR(300) 详细地址 5.3 字典字段规范 规范项 说明 状态字段 使用 status VARCHAR(10) NOT NULL 类型字段 使用 {业务}_type VARCHAR(20) NOT NULL 布尔字段 使用 VARCHAR(10) NOT NULL DEFAULT 'false'，关联字典 yes_no 审批状态字段 使用 approval_status VARCHAR(20) NOT NULL DEFAULT 'draft'，关联字典 approval_status 禁止 ENUM 统一使用 VARCHAR + 字典表（sys_dict_type、sys_dict_item）管理 sql -- ✅ 正确示例 `status` VARCHAR(10) NOT NULL DEFAULT 'enabled' COMMENT '状态，关联字典 status。取值：enabled-启用，disabled-禁用', `approval_status` VARCHAR(20) NOT NULL DEFAULT 'draft' COMMENT '审批状态，关联字典 approval_status。取值：draft-草稿，pending-审批中，approved-已通过，rejected-已驳回，recalled-已撤回', `is_default` VARCHAR(10) NOT NULL DEFAULT 'false' COMMENT '是否默认，关联字典 yes_no。取值：true-是，false-否', 六、索引设计规范 规范项 说明 必须有主键 每张表都必须有 id 主键 逻辑外键建索引 所有 {关联表}_code 字段必须建立普通索引 唯一性约束 code、手机号等业务唯一字段必须建立唯一索引 组合索引 遵循“最左前缀”原则，tenant_code 和 merchant_code 放在最左侧 索引数量 单表索引数量建议不超过 5个 全文索引 适用于大文本字段（如文章标题、内容）的模糊搜索场景 七、注释规范（强制） 7.1 表注释 所有表必须有 COMMENT，说明表用途 关联表需说明关联关系 7.2 字段注释 字段类型 注释要求 示例 主键 说明是主键 COMMENT='主键' 业务编码 说明编码用途 COMMENT='用户编码（租户+商户内唯一）' 逻辑外键 注明关联的目标表 COMMENT='租户编码，关联 sys_tenant.code' 字典字段 注明关联的字典类型和取值说明 COMMENT='状态，关联字典 status。取值：enabled-启用，disabled-禁用' 审批状态 注明关联的字典类型和取值说明 COMMENT='审批状态，关联字典 approval_status。取值：draft-草稿，pending-审批中，approved-已通过，rejected-已驳回，recalled-已撤回' 金额字段 注明单位和精度 COMMENT='总金额，单位：元，精度两位' JSON字段 说明存储内容格式 COMMENT='扩展信息（JSON格式）' 布尔字段 说明 true/false 含义 COMMENT='是否默认地址，关联字典 yes_no。取值：true-是，false-否' 八、图标字段规范 规范项 说明 图标库 Bootstrap Icons 类名格式 bi bi-xxx（如 bi bi-people、bi bi-shop） sql `icon` VARCHAR(50) DEFAULT 'bi bi-grid' COMMENT '图标（Bootstrap Icons 类名，如 bi bi-people）', 九、建库与建表语句规范 规范项 要求 建库语句 CREATE DATABASE IF NOT EXISTS 建表语句 CREATE TABLE IF NOT EXISTS 文件开头 SET NAMES utf8mb4; SET FOREIGN_KEY_CHECKS = 0; 文件结尾 SET FOREIGN_KEY_CHECKS = 1; 引擎 明确指定 ENGINE=InnoDB 字符集 明确指定 CHARSET=utf8mb4 排序规则 明确指定 COLLATE=utf8mb4_0900_ai_ci 十、数据初始化规范 规范项 说明 系统预置数据 字典类型、字典项、系统角色、系统权限 幂等性 初始化脚本可重复执行，不产生重复数据 使用 INSERT IGNORE 避免重复插入导致错误 默认租户 系统预置数据使用 kingdee 作为默认租户编码 十一、表分类与隔离层级总览 分类 表特征 表名示例 十二、设计原则总结 原则 说明 租户隔离 所有表必须包含 tenant_code，实现金蝶级数据隔离 商户隔离 所有商户业务表必须包含 merchant_code，实现商户级数据隔离 业务表审批关联 所有审批业务表必须包含 approval_status + wf_instance_code 两个字段 业务表干净 业务表只含审批状态和流程实例关联，审批过程由独立审批表管理 逻辑外键 统一使用 {关联表}_code，禁止物理外键 软删除 主数据表使用 deleted_at，关联表物理删除 字典管理 统一使用 VARCHAR + 字典表，禁止 ENUM