4.1 KiB
Data Model Specification
Purpose
定义系统数据模型的字段字典：实体目录、公共字段、枚举、状态机与命名约定，作为前后端字段一致性的唯一锚点。
Requirements
Requirement: 业务实体公共字段
所有业务软删实体 SHALL 携带公共字段：id（UUID v7）、tenant_code、created_at、created_by、updated_at、deleted_at；日志/会话类实体不携带 deleted_at。
Scenario: 创建记录
- WHEN 创建任一业务实体记录
- THEN 系统自动填充 id、tenant_code、created_at、created_by
Scenario: 软删
- WHEN 删除业务实体
- THEN 系统置 deleted_at 而非物理删除
Requirement: 实体目录
系统 SHALL 包含实体 tenant、user、role、resource、org、dict_type、dict_item、config、audit_log、login_log、refresh_token，以及关联表 user_role、role_resource、role_org。
Scenario: 字典拆分
- WHEN 维护数据字典
- THEN 字典分为 dict_type（类型）与 dict_item（项）两类，经 dict_type_code 关联
Requirement: 资源类型与代码
resource 实体 SHALL 通过 type 字段区分菜单(menu)、按钮(button)、接口(api)三种类型；「目录」由菜单节点是否拥有菜单子节点推导，不设独立类型。每个 resource SHALL 拥有租户内唯一的 code，作为关联键与权限标识。
Scenario: 按钮鉴权点
- WHEN 前端需要按钮级权限
- THEN 该按钮登记为 type=button 的资源，并携带 code 权限标识
Requirement: 引用键约定
所有跨实体引用 SHALL 优先使用业务键：角色、资源、组织、字典类型、租户用 code，树的父引用用 parent_code；对用户的引用 SHALL 使用用户 id。关联表 sys_user_role、sys_role_resource、sys_role_org 分别保存 user_id+role_code、role_code+resource_code、role_code+org_code；其余引用（user.org_code、dict_item.dict_type_code、resource.parent_code、org.parent_code）同理。
Scenario: 为角色分配资源
- WHEN 管理员为角色分配资源
- THEN 关联记录保存 role_code 与 resource_code
Requirement: 数据权限档位
role 实体 SHALL 通过 data_scope 字段支持全部/本部门/本部门及以下/本人/自定义五档；「自定义」经 role_org 关联表声明可见部门。
Scenario: 本部门及以下
- WHEN 角色数据权限为「本部门及以下」
- THEN 该角色用户仅可见本部门及下级部门的数据
Requirement: 命名与表前缀
所有脚手架表 SHALL 以 sys_ 前缀命名，数据库列名采用 snake_case。
Scenario: 表命名
- WHEN 新建脚手架表
- THEN 表名以 sys_ 开头，列名使用 snake_case
Requirement: 用户状态机
user 实体 SHALL 支持启用/停用/锁定状态；停用与锁定的用户 SHALL 无法登录。
Scenario: 锁定登录
- WHEN 锁定用户尝试登录
- THEN 系统拒绝登录并提示账号已锁定
Requirement: 字典实体扩展
dict_type 实体 SHALL 新增 built_in 字段（布尔，标记内置字典类型）；dict_item 实体 SHALL 新增 built_in（布尔，标记内置字典项）与 color_type（字符串，取值 primary/success/warning/danger/info，可空）字段，用于前端标签渲染与内置保护。
Scenario: 内置类型标记
- WHEN 某字典类型由系统 seed 预置
- THEN 其 built_in 为真，后端据此保护其不被删除
Scenario: 内置项颜色
- WHEN 内置字典项需要区分展示
- THEN 其 color_type 指定标签色（如启用=success、锁定=danger、停用=info）
Requirement: 内置枚举字典取值
系统 SHALL 预置 5 个内置枚举字典并锚定其取值集合：common_status={enabled,disabled}、user_status={enabled,disabled,locked}、resource_type={menu,button,api}、data_scope={all,dept,dept_and_child,self,custom}、login_status={success,fail}。
Scenario: 前端按字典渲染枚举
- WHEN 前端渲染用户/角色/资源等页面的枚举字段
- THEN 从对应内置字典读取 label 与 color_type，取值不脱离上述集合