shanxia2.0/openspec/changes/zkxw-engineering-standards/specs/database-conventions/spec.md

ADDED Requirements

Requirement: MySQL 版本

生产与标准开发环境的关系型数据库 SHALL 使用 MySQL 5.7（与《shanxia2.0需求 V0.3》§3 一致）。

Scenario: 新环境搭建文档

• WHEN 编写或更新部署文档
• THEN 文档 SHALL 声明 MySQL 5.7 及字符集/排序规则（如 utf8mb4）基线

Requirement: 公共字段集合

除需求或 OpenSpec 明确豁免的关联/日志表外，业务表 SHALL 包含以下公共字段且语义一致：id（VARCHAR(64)，UUID）、tenant_no、order_num、remark、create_by、create_dept_id、create_time、update_by、update_time、del_flag（与需求 §3 列表一致）。

Scenario: 新建业务表 DDL

• WHEN 创建新表
• THEN 表定义 SHALL 包含上述公共字段，且 del_flag 默认 0 表示未删除

Requirement: 默认租户编号 tenant_no

山峡一体化门户（本仓库）单库默认租户编号 SHALL 为 shanxia2.0（与库名、产品标识一致，区别于历史 zkxw 编码）。

含 tenant_no 的业务表在 DDL 中 SHALL 将列默认值设为 'shanxia2.0'，例如：

`tenant_no` varchar(64) NOT NULL DEFAULT 'shanxia2.0' COMMENT '租户编号',

例外：sys_tenant.tenant_no 为租户主数据业务编码，列本身不设 DEFAULT 'shanxia2.0'；种子数据中有效租户行的 tenant_no SHALL 为 shanxia2.0。

存量库从 zkxw 等历史编码迁移时，SHALL 使用 docs/sql/ 下经评审的增量脚本（如 20260530_migrate_tenant_no_to_shanxia2.0.sql），并同步更新 docs/sql/shanxia2.0.sql 全量基线导出。

Scenario: 新建含 tenant_no 的表

• WHEN 在 docs/sql/ 或迁移脚本中新增业务表且包含 tenant_no
• THEN 列定义 SHALL 使用 DEFAULT 'shanxia2.0'，且 SHALL NOT 使用 DEFAULT 'zkxw'

Scenario: 全量基线与迁移脚本一致

• WHEN 执行租户编号统一迁移或发布新环境
• THEN 库内各表 tenant_no 数据与列默认值 SHALL 与 shanxia2.0 一致；docs/sql/shanxia2.0.sql 导出 SHALL 反映该基线

Requirement: 字段顺序

表模型定义与 DDL 中，业务字段 SHALL 位于 id 之后；tenant_no、order_num、remark、create_by、create_dept_id、create_time、update_by、update_time、del_flag SHALL 位于业务字段之后（与需求 §3 一致）。

Scenario: Code review DDL

• WHEN 审查新建表 SQLAlchemy 模型或 raw SQL
• THEN 字段顺序 SHALL 符合本 requirement，除非评审记录中注明例外原因

Requirement: 逻辑删除

应用层 SHALL NOT 对业务数据执行物理删除；删除操作 SHALL 通过将 del_flag 置为 1 实现；查询默认 SHALL 排除已删除行。

Scenario: 删除用户可见记录

• WHEN 用户点击删除某条业务数据
• THEN 服务端 SHALL 更新 del_flag 而非 DELETE FROM，且列表接口默认不返回 del_flag=1

Requirement: 主键类型

主键 id SHALL 为 VARCHAR(64) NOT NULL，取值策略为 UUID（与需求 §3）。

Scenario: 插入新行

• WHEN 应用创建新实体
• THEN 写入的 id SHALL 为符合长度与格式的 UUID 字符串