diff --git a/code/fms/FMS新系统核心表结构设计.md b/code/fms/FMS新系统核心表结构设计.md index 4f9685f7..a8fe59f8 100644 --- a/code/fms/FMS新系统核心表结构设计.md +++ b/code/fms/FMS新系统核心表结构设计.md @@ -1,3 +1,58 @@ +**本系统以 SQL 为核心驱动。设计时应优先保证查询和数据处理的灵活性,并在各模块预留 SQL 扩展能力,支持传入 SQL、动态拼接查询条件、组合查询及自定义数据处理逻辑,以便通过 SQL 快速适配和解决复杂业务场景。** + +# 数据表规范 + +本规范用于指导 AI 设计、新增和调整数据库表结构。除非已有表结构或业务要求明确指定,否则应优先遵循以下约定。 + +1. **表名规范** + - 统一使用小写 `snake_case` 命名,单词之间使用下划线分隔。 + - 系统配置、元数据和权限相关表使用 `s_` 前缀,例如 `s_module`、`s_field`。 + - 业务数据表使用 `b_` 前缀或明确的业务域前缀,例如 `b_user`、`cw_fee`。 + - 表名应表达稳定的业务含义,避免使用页面名称、路由名称或临时功能名称作为表名。 + +2. **表职责规范** + - 一张表应围绕一个明确的业务对象、配置对象或关系对象设计。 + - 系统表用于保存系统配置、元数据、权限和运行记录;业务表用于保存具体业务数据;关系表用于表达对象之间的关联关系。 + - 不要为了适配单个页面重复创建业务表;页面差异优先通过模块配置、字段布局和 SQL 组合实现。 + +3. **主键和关联字段规范** + - 每张表必须定义稳定、明确的主键。业务对象优先使用 `b_id` 作为业务编码主键;关系表可根据业务关系使用联合主键。 + - 表之间的关联字段统一使用 `<对象>_id` 或已有的 `b_module_id` 等明确命名,不使用无法判断来源的通用字段名。 + - 主键和关联字段的数据类型、长度必须保持一致。 + +4. **字段命名规范** + - 字段统一使用小写 `snake_case` 命名。 + - 主表或主业务对象字段使用 `b_` 前缀;明细、子表或扩展业务字段使用 `mx_` 前缀。 + - 系统公共字段沿用现有命名,例如 `b_id`、`b_name`、`b_bz`、`b_canuse`、`b_xh`。 + - 字段名应表达业务含义,避免使用 `value`、`data`、`type1` 等无法说明用途的名称;同一含义在不同表中应使用统一命名。 + +5. **通用字段规范** + - 启用/停用统一使用 `b_canuse`,取值为 `0/1`。 + - 排序字段统一使用 `b_xh`,默认值为 `0`;需要稳定排序时增加业务主键作为次排序字段。 + - 名称、备注和多语言文本使用 `nvarchar`;编码、状态、类型和 SQL 标识类字段使用 `varchar`。 + - 日期时间优先使用 `datetime2`;金额、数量等数值字段根据业务精度明确设置 `precision` 和 `scale`。 + - 是否允许为空、默认值和数据库默认值必须根据业务语义明确设置,不能无理由全部允许为空或全部设置默认值。 + +6. **字段与布局规范** + - 数据字段定义、列表布局、编辑布局和查询布局分开保存,避免把页面展示规则硬编码到业务表中。 + - 字段配置、字段分组和用户个性化配置必须通过 `b_module_id` 与所属数据模块关联。 + - 页面差异优先通过字段布局、查询条件和 SQL 组合实现,不通过复制数据表实现。 + +7. **SQL 驱动规范** + - 查询和数据处理应优先采用可组合的 SQL 方案,避免把业务逻辑固化在单个页面或固定查询中。 + - 各模块应预留 SQL 扩展入口,支持传入 SQL、动态拼接 `where` 条件、选择字段、排序、分页、关联查询和组合查询。 + - 当通用配置无法覆盖业务场景时,优先通过 SQL 视图、查询 SQL、条件片段或数据处理 SQL 扩展,不要立即新增重复表或重复模块。 + - SQL 参数、查询字段、排序字段和关联关系应使用明确的元数据或配置进行描述,保证 AI 能够根据模块定义生成和组合查询。 + +8. **索引和约束规范** + - 主键、外键关联字段、常用查询条件、排序字段和唯一业务键应根据实际查询场景建立索引。 + - 索引应服务于明确的查询或关联场景,避免无依据地为每个字段单独建索引。 + - 数据库层只保留主键、联合主键、索引和必要的唯一约束;唯一约束可用于保证业务键或组合业务键不重复。 + - 除主键、唯一约束和索引外,不增加 `CHECK`、触发器等业务规则约束。字段取值、字段组合、状态流转和其他业务校验统一交给业务层处理。 + - 非空和默认值属于字段定义的一部分,应根据业务语义设置;不要使用数据库约束代替业务逻辑。 + + + # FMS 新系统核心表结构 ## 1. 用户表 diff --git a/code/fms/FMS新系统核心表结构设计V2.md b/code/fms/FMS新系统核心表结构设计V2.md new file mode 100644 index 00000000..d6c1620c --- /dev/null +++ b/code/fms/FMS新系统核心表结构设计V2.md @@ -0,0 +1,697 @@ +# FMS 新系统核心表结构设计 V2 + +> 本文用于记录新版核心表结构方案,当前不包含权限设计。旧版文档保留作为历史参考。 + +**本系统以 SQL 为核心驱动。设计时应优先保证查询和数据处理的灵活性,并在各模块预留 SQL 扩展能力,支持传入 SQL、动态拼接查询条件、组合查询及自定义数据处理逻辑,以便通过 SQL 快速适配和解决复杂业务场景。** + +## 1. 数据表规范 + +本规范用于指导 AI 设计、新增和调整数据库表结构。除非已有表结构或业务要求明确指定,否则应优先遵循以下约定。 + +### 1.1 表名规范 + +- 统一使用小写 `snake_case` 命名,单词之间使用下划线分隔。 +- 系统配置、元数据和权限相关表使用 `s_` 前缀,例如 `s_module`、`s_field`。 +- 业务数据表使用 `b_` 前缀或明确的业务域前缀,例如 `b_user`、`cw_fee`。 +- 表名应表达稳定的业务含义,避免使用页面名称、路由名称或临时功能名称作为表名。 + +### 1.2 表职责规范 + +- 一张表应围绕一个明确的业务对象、配置对象或关系对象设计。 +- 系统表用于保存系统配置、元数据、权限和运行记录;业务表用于保存具体业务数据;关系表用于表达对象之间的关联关系。 +- 不要为了适配单个页面重复创建业务表;页面差异优先通过模块配置、JSON 布局和 SQL 组合实现。 +- 核心、稳定且需要被 SQL 查询的数据使用关系表;层级化、变化频繁的界面配置和用户偏好使用 JSON。 + +### 1.3 主键和关联字段规范 + +- 每张表必须定义稳定、明确的主键。业务对象优先使用 `b_id` 作为业务编码主键;关系表可根据业务关系使用联合主键。 +- 表之间的关联字段使用 `<对象>_id` 或已有的 `b_module_id` 等明确命名,不使用无法判断来源的通用字段名。 +- 主键和关联字段的数据类型、长度必须保持一致。 +- 本设计不依赖数据库外键约束保证关联完整性,关联存在性和删除规则由业务层处理。 + +### 1.4 字段命名规范 + +- 字段统一使用小写 `snake_case` 命名。 +- 主表或主业务对象字段使用 `b_` 前缀;明细、子表或扩展业务字段使用 `mx_` 前缀。 +- 系统公共字段沿用现有命名,例如 `b_id`、`b_name`、`b_bz`、`b_canuse`、`b_xh`。 +- 字段名应表达业务含义,避免使用 `value`、`data`、`type1` 等无法说明用途的名称;同一含义在不同表中应使用统一命名。 + +### 1.5 通用字段规范 + +- 启用和停用统一使用 `b_canuse`,取值为 `0/1`。 +- 排序字段统一使用 `b_xh`,默认值为 `0`;需要稳定排序时增加业务主键作为次排序字段。 +- 名称、备注和多语言文本使用 `nvarchar`;编码、状态、类型和 SQL 标识类字段使用 `varchar`。 +- 日期时间优先使用 `datetime2`;金额、数量等数值字段根据业务精度明确设置 `precision` 和 `scale`。 +- 是否允许为空及默认值应根据业务语义明确设置,不能无理由全部允许为空或全部设置默认值。 + +### 1.6 通用系统审计字段 + +- 通用创建人使用 `b_created_by`,保存用户编码,不保存用户名称。 +- 通用创建时间使用 `b_created_at`,类型使用 `datetime2`。 +- 通用最后修改人使用 `b_updated_by`,保存最后修改用户编码,不保存用户名称。 +- 通用最后修改时间使用 `b_updated_at`,类型使用 `datetime2`。 +- 以上字段按表的实际审计需求选用;创建人、修改人和对应时间应保持成对出现。 +- 这些字段只表示系统层面的创建和修改信息,不替代业务字段中的录入人、审核人、负责人或当前操作人。 + +### 1.7 树结构规范 + +- 需要维护层级、支持新增和移动的树,统一采用“邻接表为主 + `b_depth`、`b_path` 冗余”的方案。 +- `b_parent_id` 是树结构的权威关系,表示当前节点的直接父节点;`b_depth` 和 `b_path` 是由业务层维护的派生字段。 +- 根节点的 `b_parent_id` 为 `NULL`,`b_depth` 从 `0` 开始计算。 +- `b_path` 使用稳定节点编码组成,并在每个节点编码前后保留 `/` 分隔符,例如 `/sea/container/`;节点编码创建后原则上不可修改。 +- `b_path` 用于前缀查询子树,`b_parent_id` 配合递归 CTE 用于查询父级、祖先和复杂层级关系。 +- 新增和移动节点时,必须在同一业务事务中同步更新当前节点及其全部后代的 `b_depth` 和 `b_path`。 +- 业务层必须校验节点不能指向自身,不能形成循环;这些规则不使用数据库 `CHECK` 或触发器约束。 +- 当冗余字段可能不一致时,以 `b_parent_id` 为准,并提供按父子关系重建 `b_depth`、`b_path` 的维护能力。 +- 模块树和菜单树使用该规范;JSON 内的布局树只在 JSON 内维护,不额外建立树表;主子表、引用和多对多关系使用 `s_relation`,不使用树字段表达。 + +### 1.8 JSON 配置规范 + +- SQL Server 使用 `nvarchar(max)` 保存 JSON,由业务层负责序列化、反序列化和结构校验。 +- JSON 配置如果存在结构升级需求,可以在顶层包含 `schemaVersion`,用于业务层迁移;不单独在数据库表中保存重复的版本字段。 +- JSON 中通过字段编码引用 `s_field`,不得重复定义数据库类型、长度、精度等核心字段元数据。 +- 布局 JSON 保存完整的模块默认配置;用户偏好 JSON 只保存相对默认配置的偏离量。 +- 表单显示、只读、必填、禁用、条件显示、默认值、选项、格式化和字段计算等界面行为配置放在对应的布局 JSON 中,不放入 `s_field`。 +- 读取用户配置时,先加载模块默认配置,再应用用户偏好覆盖;恢复默认时删除对应偏好或清空偏离配置。 +- JSON 可以扩展新属性,但不得随意改变已有属性语义;不再使用的属性由业务层兼容或迁移。 + +### 1.9 SQL 驱动规范 + +- 查询和数据处理优先采用可组合的 SQL 方案,避免把业务逻辑固化在单个页面或固定查询中。 +- 各模块应预留 SQL 扩展入口,支持传入 SQL、动态拼接 `where` 条件、选择字段、排序、分页、关联查询和组合查询。 +- 通用配置无法覆盖业务场景时,优先通过 SQL 视图、查询 SQL、条件片段或数据处理 SQL 扩展,不要立即新增重复表或重复模块。 +- SQL 参数、查询字段、排序字段和关联关系应由明确的模块元数据描述,使 AI 能根据模块定义生成和组合 SQL。 +- SQL 配置只描述可复用的数据处理能力,具体运行参数由调用方传入。 + +### 1.10 索引和约束规范 + +- 主键、关联字段、常用查询条件、排序字段和唯一业务键应根据实际查询场景建立索引。 +- 索引应服务于明确的查询或关联场景,避免无依据地为每个字段单独建立索引。 +- 数据库层只保留主键、联合主键、索引和必要的唯一约束;唯一约束可用于保证业务键或组合业务键不重复。 +- 不增加 `CHECK`、触发器等业务规则约束。字段取值、字段组合、状态流转、关联完整性和其他业务校验统一交给业务层处理。 +- 非空和默认值属于字段定义的一部分,应根据业务语义设置,不使用数据库约束代替业务逻辑。 + +## 2. 总体设计 + +新版结构强化“模块”概念,同时避免为字段布局和表单结构建立过多关系表。 + +```text +s_module +├── module 业务模块,可包含下级 module、data 或 virtual +├── data 数据模块,对应表、视图或查询 SQL,拥有字段定义 +└── virtual 虚拟模块,不要求对应标准数据表,可由 SQL 或业务实现驱动 +``` + +“子模块”不是模块类型,由 `b_parent_id` 表达任意层级的父子关系。 + +核心存储原则: + +| 内容 | 存储方式 | 说明 | +| --- | --- | --- | +| 模块定义 | 关系表 | 系统核心业务结构 | +| 字段定义 | 关系表 | 参与 SQL 生成、保存和数据处理 | +| 列表布局 | JSON | 支持列分组、冻结、格式化和扩展属性 | +| 表单布局 | JSON | 支持分组、栅格、选项卡和条件显示 | +| 查询配置 | JSON | 支持同字段多条件、条件组和嵌套逻辑 | +| 字段分组 | 布局 JSON 节点 | 不再建立独立字段分组表 | +| 用户偏好 | JSON 偏离量 | 只保存用户相对默认配置的修改 | +| 多语言 | 关系表 | 支持按语言查询、导入、导出和回退 | +| 字段权限 | 单独设计 | 不属于本文范围,不与界面布局混合 | + +## 3. 用户 + +```sql +-- 用户表 +create table dbo.b_user ( + b_id varchar(50) not null primary key, -- 用户编码(业务键主键) + b_name nvarchar(100) null, -- 用户名 + b_bz nvarchar(400) null, -- 备注 + b_password nvarchar(255) not null, -- 密码 + b_canuse tinyint not null default 1, -- 是否启用(0/1) + b_logintime int not null default 0 -- 登录次数 +); +``` + +## 4. 模块 + +### 4.1 模块定义 + +```sql +-- 模块定义表 +create table dbo.s_module ( + b_id varchar(50) not null primary key, -- 模块编码(业务键主键) + b_parent_id varchar(50) null, -- 父模块编码,NULL 表示根节点 + b_depth int not null default 0, -- 树层级,根节点为 0 + b_path varchar(1000) not null, -- 根到当前节点的路径,例如 /sea/container/ + b_name nvarchar(200) not null, -- 模块名称 + b_i18n varchar(150) null, -- 多语言资源键 + b_module_type varchar(20) not null, -- module / data / virtual + b_view_table varchar(128) null, -- 默认查询表或视图 + b_save_table varchar(128) null, -- 默认保存目标表 + b_key_field varchar(50) null, -- 主键字段 + b_order_sql varchar(500) null, -- 默认排序 SQL + b_query_sql nvarchar(max) null, -- 可选查询 SQL 或 SQL 模板 + b_delete_policy varchar(20) null, -- 删除策略编码,由业务层解释 + b_edit_mode varchar(20) null, -- table / sql / custom + b_config_json nvarchar(max) null, -- 低频模块扩展配置 + b_canuse tinyint not null default 1, -- 是否启用(0/1) + b_xh int not null default 0, -- 同级显示顺序 + b_bz nvarchar(2000) null -- 备注 +); + +create index ix_s_module_parent + on dbo.s_module (b_parent_id, b_canuse, b_depth, b_xh, b_id); + +create index ix_s_module_path + on dbo.s_module (b_path, b_canuse, b_id); + +create index ix_s_module_type + on dbo.s_module (b_module_type, b_canuse, b_xh, b_id); + +create index ix_s_module_view_table + on dbo.s_module (b_view_table, b_canuse, b_id); + +create index ix_s_module_save_table + on dbo.s_module (b_save_table, b_canuse, b_id); +``` + +### 4.2 模块类型约定 + +#### `module` + +- 表示业务模块或业务域,例如海运、空运、财务、客户管理。 +- 可以包含下级 `module`、`data` 和 `virtual`。 +- 默认不配置字段、查询表、保存表和主键字段。 +- 可作为模块级配置、统计、导航上下文和权限继承的边界。 + +#### `data` + +- 表示具体数据对象,例如海运主单、集装箱、费用明细。 +- 必须配置 `b_view_table` 或 `b_query_sql` 作为查询来源。 +- 可以配置 `b_save_table` 作为默认保存目标。 +- `b_key_field` 表示该数据对象的主键字段;没有稳定主键的查询数据可以为空。 +- 字段定义保存在 `s_field`,界面配置保存在 `s_module_schema`。 +- 主子表和引用关系通过 `s_relation` 表达,不使用模块树表达。 + +#### `virtual` + +- 表示不适合使用标准数据表和通用 CRUD 表达的业务能力。 +- 可以由查询 SQL、组合 SQL、专用接口或业务处理器实现。 +- 可以拥有字段定义和界面配置,但不强制配置 `b_save_table`。 +- 没有标准保存表时,保存和业务动作由 SQL 或业务处理器实现。 + +模块类型、父子组合、字段适用规则和 SQL 配置的完整性由业务层校验,不建立 `CHECK` 约束。 + +### 4.3 模块树与数据关系边界 + +- `b_parent_id`、`b_depth`、`b_path` 共同构成模块树,其中 `b_parent_id` 是权威关系,后两者是冗余查询字段。 +- `b_path` 使用 `/` 包裹节点编码,例如 `/sea/`、`/sea/container/`;查询模块子树时使用路径前缀匹配。 +- `module` 可以包含下级 `module`、`data` 和 `virtual`;`data` 和 `virtual` 默认作为叶子节点。 +- 新增或移动模块时,业务层必须在同一事务中更新当前模块及全部后代的 `b_depth` 和 `b_path`。 +- 不允许模块指向自身或形成循环;`b_id` 创建后原则上不可修改;这些规则由业务层校验。 +- `b_depth`、`b_path` 与 `b_parent_id` 不一致时,以 `b_parent_id` 为准并重建冗余字段。 +- 数据之间的主子表、引用和多对多关系统一由 `s_relation` 表达。 +- 模块级扩展配置使用 `b_config_json`,只保存低频、非核心的扩展属性,不重复保存字段定义、权限或界面布局。 + +### 4.4 查询来源优先级 + +数据加载时按以下规则确定默认查询来源: + +1. 配置 `b_query_sql` 时,使用查询 SQL 或 SQL 模板; +2. 未配置 `b_query_sql` 时,使用 `b_view_table`; +3. 两者均未配置时,由虚拟模块的业务实现负责提供数据; +4. 调用方传入的筛选、字段、排序和分页配置在默认查询来源上继续组合。 + +保存时按以下规则确定默认保存方式: + +1. `data` 模块配置 `b_save_table` 时,默认写入该表; +2. `b_edit_mode = 'sql'` 时,由业务层使用模块对应的 SQL 保存逻辑; +3. `b_edit_mode = 'custom'` 时,由业务处理器负责保存; +4. `virtual` 模块不要求具备通用保存能力。 + +## 5. 字段定义 + +字段定义保持关系表结构。数据库表或视图是物理字段结构的来源,`s_field` 只保存模块使用字段时所需的业务元数据和来源映射。 + +当前阶段不在 `s_field` 中保存数据库类型、长度、精度、小数位等物理结构信息。保存器或 SQL 生成器需要这些信息时,直接读取数据库表或视图的实际结构;后续确定元数据同步方案后再补充持久化字段。 + +```sql +-- 字段定义表 +create table dbo.s_field ( + b_module_id varchar(50) not null, -- 所属 data / virtual 模块编码 + b_field varchar(50) not null, -- 模块字段编码或查询结果别名 + b_source_field varchar(128) null, -- 来源字段;计算字段可为空 + b_name nvarchar(200) not null, -- 字段名称 + b_i18n varchar(150) null, -- 多语言资源键 + b_type varchar(30) not null, -- 业务类型 + b_canuse tinyint not null default 1, -- 是否启用(0/1) + b_xh int not null default 0, -- 默认顺序 + primary key (b_module_id, b_field) +); + +create index ix_s_field_module_order + on dbo.s_field (b_module_id, b_canuse, b_xh, b_field); + +create index ix_s_field_source + on dbo.s_field (b_module_id, b_source_field); +``` + +字段同步约定: + +- `data` 模块可以从 `b_view_table` 或 `b_query_sql` 的结果结构增量同步字段。 +- 同步负责发现来源字段和维护 `b_source_field` 映射,不覆盖人工维护的字段名称和业务类型。 +- 数据库中已删除的字段不直接物理删除,可由业务层标记为停用并提示人工确认。 +- 计算字段、关联显示字段和虚拟字段可以人工登记,其 `b_source_field` 可以为空,并通过模块查询 SQL 或界面配置 JSON 产生。 +- 字段是否可以直接写入、是否只读以及是否需要自定义保存逻辑,不在 `s_field` 中增加固定模式字段;由表单 JSON、模块保存配置或业务处理器根据具体场景处理。 + +## 6. 模块界面配置 + +列表布局、表单布局、查询配置和字段分组统一保存为 JSON,不再建立以下独立表: + +```text +s_field_group +s_field_view +s_field_edit +s_field_query +``` + +```sql +-- 模块界面配置表 +create table dbo.s_module_schema ( + b_module_id varchar(50) not null, -- 所属 data / virtual 模块编码 + b_schema_type varchar(20) not null, -- view / edit / query + b_schema_json nvarchar(max) not null, -- 完整 JSON 配置 + b_canuse tinyint not null default 1, -- 是否启用(0/1) + b_updated_at datetime2 null, -- 最后更新时间 + primary key (b_module_id, b_schema_type) +); + +create index ix_s_module_schema_type + on dbo.s_module_schema ( + b_module_id, + b_schema_type, + b_canuse + ); +``` + +每个模块默认维护三行配置,分别对应列表、表单和查询: + +```text +view +edit +query +``` + +当前阶段不维护同一类型的多套命名配置。若未来确实需要多套列表、表单或查询方案,再增加配置编码字段,或在 JSON 内增加方案节点。 + +### 6.1 列表配置示例 + +```json +{ + "schemaVersion": 1, + "columns": [ + { + "field": "b_no", + "visible": true, + "width": 140, + "fixed": "left" + }, + { + "type": "group", + "title": "费用信息", + "i18n": "group.cw_fee.amount", + "children": [ + { "field": "mx_amount", "width": 120, "format": "money" }, + { "field": "mx_currency", "width": 90 } + ] + } + ] +} +``` + +### 6.2 表单配置示例 + +```json +{ + "schemaVersion": 1, + "children": [ + { + "type": "group", + "title": "基础信息", + "i18n": "group.sea_main.basic", + "children": [ + { + "type": "row", + "children": [ + { "field": "b_no", "span": 12, "readonly": true }, + { "field": "b_name", "span": 12, "required": true } + ] + } + ] + } + ] +} +``` + +表单 JSON 可以描述字段的展示和交互行为,例如: + +```json +{ + "field": "mx_amount", + "readonly": true, + "visibleWhen": { "field": "mx_type", "operator": "eq", "value": "tax" }, + "formula": "mx_qty * mx_price" +} +``` + +其中 `readonly`、`required`、`disabled`、`visibleWhen`、`defaultValue`、`options`、`format` 和 `formula` 都属于界面配置,不放入 `s_field`。如果计算字段需要作为查询结果参与 SQL、排序或筛选,应在模块的 `b_query_sql` 中定义,而不是依赖表单 JSON。 + +### 6.3 查询配置示例 + +```json +{ + "schemaVersion": 1, + "quick": ["b_no", "b_name", "b_status"], + "groups": [ + { + "logic": "and", + "conditions": [ + { "field": "b_status", "operator": "eq" }, + { + "logic": "or", + "conditions": [ + { "field": "b_no", "operator": "like" }, + { "field": "b_name", "operator": "like" } + ] + } + ] + } + ] +} +``` + +## 7. 用户个性化 + +原有列表字段偏好和查询字段偏好合并为一张表。用户偏好只保存相对模块默认配置的偏离量,不复制完整模块配置。 + +```sql +-- 用户模块偏好表 +create table dbo.s_user_module_pref ( + b_user_id varchar(50) not null, -- 用户编码 + b_module_id varchar(50) not null, -- 模块编码 + b_pref_json nvarchar(max) not null, -- 用户偏离配置 JSON + b_updated_at datetime2 null, -- 最后更新时间 + primary key (b_user_id, b_module_id) +); + +create index ix_s_user_module_pref_module + on dbo.s_user_module_pref (b_module_id, b_user_id); +``` + +偏好示例: + +```json +{ + "schemaVersion": 1, + "view": { + "default": { + "hidden": ["b_bz"], + "order": ["b_no", "b_name", "b_status"], + "width": { + "b_no": 160, + "b_name": 240 + } + } + }, + "query": { + "default": { + "quick": ["b_no", "b_status"] + } + } +} +``` + +合并规则: + +1. 读取 `s_module_schema` 中的模块默认配置; +2. 读取当前用户的 `s_user_module_pref.b_pref_json`; +3. 按配置类型应用偏离量; +4. 已停用、已删除或无权限的字段不得因用户偏好重新出现; +5. 恢复默认时删除当前模块偏好记录,或删除 JSON 中对应配置片段。 + +## 8. 自动编码 + +```sql +-- 自动编码表 +create table dbo.s_autocode ( + b_module_id varchar(50) not null, -- data 模块编码 + b_field varchar(50) not null, -- 编码字段 + b_prefix nvarchar(200) not null default N'', -- 编码前缀 + b_dateformat varchar(30) not null default 'yyyyMM', -- 日期格式 + b_separator nvarchar(20) not null default N'-', -- 分隔符 + b_seqwidth int not null default 5, -- 序号宽度 + b_resettype varchar(10) not null default 'month', -- 重置类型 + b_startvalue bigint not null default 1, -- 起始值 + b_currentperiod varchar(20) null, -- 当前周期 + b_currentvalue bigint not null default 0, -- 当前值 + b_canuse tinyint not null default 1, -- 是否启用(0/1) + primary key (b_module_id, b_field) +); +``` + +编码格式、重置类型和字段适用性由业务层校验。 + +## 9. 模块关系 + +模块树只表达业务模块层级,主子表、引用和多对多关系统一由 `s_relation` 表达。 + +```sql +-- 模块关系表 +create table dbo.s_relation ( + b_module_id varchar(50) not null, -- 源 data 模块编码 + b_target_module_id varchar(50) not null, -- 目标 data 模块编码 + b_relation_type varchar(20) not null, -- one_to_one / one_to_many / many_to_many + b_field varchar(50) not null, -- 源字段 + b_target_field varchar(50) not null, -- 目标字段 + b_foreign_side varchar(10) null, -- 外键所在侧 + b_junction_module_id varchar(50) null, -- 中间表模块编码 + b_junction_field varchar(50) null, -- 中间表源字段 + b_junction_target_field varchar(50) null, -- 中间表目标字段 + b_ownership varchar(20) not null default 'reference', -- reference / composition + b_owner_side varchar(10) null, -- 属主侧 + b_delete_policy varchar(20) null, -- 删除策略编码 + b_order_module_id varchar(50) null, -- 排序所属模块编码 + b_order_field varchar(50) null, -- 排序字段 + b_condition_sql nvarchar(max) null, -- 附加关联条件 SQL + b_canuse tinyint not null default 1, -- 是否启用(0/1) + b_xh int not null default 0, -- 显示顺序 + primary key (b_module_id, b_field, b_target_module_id, b_target_field) +); + +create index ix_s_relation_module + on dbo.s_relation (b_module_id, b_canuse, b_xh, b_field, b_target_module_id); + +create index ix_s_relation_target + on dbo.s_relation (b_target_module_id, b_canuse, b_module_id); +``` + +## 10. 菜单 + +菜单负责导航和页面入口,模块负责业务结构和数据能力。一个菜单可以使用多个 `data` 或 `virtual` 模块,一个模块也可以被多个菜单复用。 + +```sql +-- 菜单表 +create table dbo.s_menu ( + b_id varchar(50) not null primary key, -- 菜单编码(业务键主键) + b_parent_id varchar(50) null, -- 父菜单编码,NULL 表示根节点 + b_depth int not null default 0, -- 树层级,根节点为 0 + b_path varchar(1000) not null, -- 根到当前菜单的路径,例如 /system/user/ + b_name nvarchar(200) not null, -- 菜单名称 + b_i18n varchar(150) null, -- 多语言资源键 + b_menu_type varchar(20) not null, -- directory / page / external + b_route varchar(500) null, -- 页面路由或外链地址 + b_icon varchar(50) null, -- 图标 + b_xh int not null default 0, -- 显示顺序 + b_canuse tinyint not null default 1 -- 是否启用(0/1) +); + +create index ix_s_menu_parent + on dbo.s_menu (b_parent_id, b_canuse, b_depth, b_xh, b_id); + +create index ix_s_menu_path + on dbo.s_menu (b_path, b_canuse, b_id); + +create index ix_s_menu_route + on dbo.s_menu (b_route, b_canuse, b_id); + +-- 菜单使用模块关系表 +create table dbo.s_menu_module ( + b_menu_id varchar(50) not null, -- 菜单编码 + b_module_id varchar(50) not null, -- 页面实际使用的 data / virtual 模块编码 + b_xh int not null default 0, -- 页面内模块顺序 + b_canuse tinyint not null default 1, -- 是否启用(0/1) + primary key (b_menu_id, b_module_id) +); + +create index ix_s_menu_module_module + on dbo.s_menu_module (b_module_id, b_canuse, b_menu_id); +``` + +菜单树同样使用 `b_parent_id` 作为权威关系,并冗余维护 `b_depth`、`b_path`。菜单节点新增、移动和删除时,由业务层同步处理后代节点路径和层级;菜单编码创建后原则上不可修改。 + +业务模块上下文可以根据所绑定数据模块的父级模块获得;暂不增加独立的菜单上下文字段。 + +## 11. 多语言 + +多语言继续使用关系表。模块、字段和 JSON 布局节点只保存资源键,具体语言文本统一保存到 `s_i18n`。资源通过 `b_source`、`b_source_id` 标识来源,便于按来源维护和级联清理。 + +```sql +-- 多语言类型表 +create table dbo.s_i18n_type ( + b_id varchar(20) not null primary key, -- 类型编码 + b_name nvarchar(200) not null, -- 类型名称 + b_canuse tinyint not null default 1, -- 是否启用(0/1) + b_default tinyint not null default 0, -- 是否默认(0/1) + b_xh int not null default 0 -- 显示顺序 +); + +-- 多语言资源表 +create table dbo.s_i18n ( + b_key varchar(150) not null, -- 资源键 + b_locale varchar(20) not null, -- 语言区域 + b_value nvarchar(1000) not null, -- 翻译值 + b_source varchar(20) not null, -- 来源类型,例如 module / common + b_source_id varchar(50) null, -- 来源对象编码;module 来源时保存模块编码 + b_canuse tinyint not null default 1, -- 是否启用(0/1) + primary key (b_key, b_locale) +); + +create index ix_s_i18n_source + on dbo.s_i18n (b_source, b_source_id, b_key, b_locale); + +create index ix_s_i18n_locale + on dbo.s_i18n (b_locale, b_canuse, b_key); +``` + +## 12. 日志 + +```sql +-- 技术日志表 +create table dbo.s_log_technical ( + b_id uniqueidentifier not null primary key, -- 日志 ID(UUIDv7) + b_user_id varchar(50) null, -- 用户编码 + b_sourcetype varchar(20) null, -- 来源类型 + b_loglevel varchar(16) not null, -- 日志级别 + b_logcategory varchar(64) null, -- 日志分类 + b_operation varchar(100) null, -- 操作 + b_module_id varchar(50) null, -- 模块编码 + b_request_id varchar(64) null, -- 请求 ID + b_trace_id varchar(64) null, -- 链路 ID + b_server_node varchar(128) null, -- 服务节点 + b_duration_ms bigint null, -- 耗时(毫秒) + b_result_code varchar(50) null, -- 结果码 + b_error_code varchar(50) null, -- 错误码 + b_error_message nvarchar(4000) null, -- 错误信息 + b_exception_text nvarchar(max) null, -- 异常文本 + b_context_text nvarchar(max) null, -- 上下文文本 + b_occurdatetime datetime2 default sysutcdatetime() -- 发生时间 +); + +-- 登录日志表 +create table dbo.s_log_login ( + b_id uniqueidentifier not null primary key, -- 日志 ID(UUIDv7) + b_user_id varchar(50) null, -- 用户编码 + b_login_type varchar(20) not null, -- 登录类型 + b_login_result tinyint not null default 0, -- 登录结果(0/1) + b_fail_reason nvarchar(400) null, -- 失败原因 + b_ip varchar(50) null, -- IP + b_ip_location nvarchar(400) null, -- IP 归属地 + b_browser varchar(100) null, -- 浏览器 + b_browser_version varchar(50) null, -- 浏览器版本 + b_os varchar(100) null, -- 操作系统 + b_os_version varchar(50) null, -- 系统版本 + b_device_type varchar(20) null, -- 设备类型 + b_user_agent nvarchar(max) null, -- UserAgent + b_session_id varchar(50) null, -- 会话 ID + b_request_id varchar(64) null, -- 请求 ID + b_trace_id varchar(64) null, -- 链路 ID + b_occurdatetime datetime2 default sysutcdatetime() -- 发生时间 +); + +-- 审计日志表 +create table dbo.s_log_audit ( + b_id uniqueidentifier not null primary key, -- 日志 ID(UUIDv7) + b_event_code varchar(50) not null, -- 事件编码 + b_module_id varchar(50) null, -- 模块编码 + b_data_id varchar(50) null, -- 数据 ID + b_business_no varchar(50) null, -- 业务单号 + b_operation varchar(100) null, -- 操作 + b_operator_id varchar(50) null, -- 操作人 ID + b_operator_name nvarchar(200) null, -- 操作人名称 + b_source_type varchar(20) not null default 'user', -- 来源类型 + b_visibility varchar(20) not null default 'internal', -- 可见性 + b_request_id varchar(64) null, -- 请求 ID + b_trace_id varchar(64) null, -- 链路 ID + b_payload_text nvarchar(max) null, -- 载荷文本 + b_occurdatetime datetime2 default sysutcdatetime() -- 发生时间 +); + +-- 审计字段明细表 +create table dbo.s_log_audit_field ( + b_id uniqueidentifier not null primary key, -- 日志 ID(UUIDv7) + b_event_id uniqueidentifier not null, -- 审计事件 ID + b_module_id varchar(50) null, -- 模块编码 + b_data_id varchar(50) null, -- 数据 ID + b_field varchar(50) not null, -- 字段编码 + b_field_label nvarchar(200) null, -- 字段名称 + b_before_value nvarchar(max) null, -- 变更前值 + b_after_value nvarchar(max) null, -- 变更后值 + b_before_display nvarchar(1000) null, -- 变更前显示值 + b_after_display nvarchar(1000) null, -- 变更后显示值 + b_visibility varchar(20) not null default 'internal' -- 可见性 +); + +create index ix_s_log_technical_occur + on dbo.s_log_technical (b_occurdatetime, b_id); + +create index ix_s_log_technical_trace + on dbo.s_log_technical (b_trace_id, b_occurdatetime); + +create index ix_s_log_login_occur + on dbo.s_log_login (b_occurdatetime, b_id); + +create index ix_s_log_login_user + on dbo.s_log_login (b_user_id, b_occurdatetime); + +create index ix_s_log_audit_occur + on dbo.s_log_audit (b_occurdatetime, b_id); + +create index ix_s_log_audit_module + on dbo.s_log_audit (b_module_id, b_data_id, b_occurdatetime); + +create index ix_s_log_audit_field_event + on dbo.s_log_audit_field (b_event_id, b_id); +``` + +## 13. 业务表主键约定 + +业务表使用应用层生成的雪花 ID。需要跨系统公开、离线生成或按时间有序的标识时,可以单独评估 UUIDv7,但同一业务域内应保持一致。 + +```sql +-- 业务表示例 +create table dbo.b_example ( + b_id bigint not null primary key, -- 主键(应用层雪花 ID) + b_inputuser_id varchar(50) null, -- 录入用户 ID + b_inputdatetime datetime2 default sysutcdatetime() -- 录入时间 +); +``` + +## 14. 当前不包含的内容 + +以下内容单独设计,不在本文中定义: + +- 菜单、模块和动作权限; +- 字段权限和数据范围; +- 角色及用户授权; +- JSON 配置的前端设计器实现; +- 通用 SQL 网关的具体接口协议。