# 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、notice，以及关联表 user_role、role_resource、role_org、notice_read。

#### Scenario: 字典拆分
- **WHEN** 维护数据字典
- **THEN** 字典分为 dict_type（类型）与 dict_item（项）两类，经 dict_type_code 关联

### Requirement: 通知实体
系统 SHALL 包含 `notice` 实体（公告/通知：id、tenant_code、title、content、status、created_by、created_at、deleted_at）与 `notice_read` 关联表（notice_id + user_id + read_at，唯一 tenant_code+notice_id+user_id），用于站内通知与已读追踪。

#### Scenario: 发布通知
- **WHEN** 管理员发布一条通知
- **THEN** 写入 notice，status=enabled 时对本租户所有用户可见

#### Scenario: 记录已读
- **WHEN** 用户阅读某通知
- **THEN** 写入 notice_read 记录其 read_at

### 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 通过 `status` 字段支持启用/停用（管理员手动启停），并通过独立的 `locked_at`（锁定时间，可空）与 `lock_reason`（锁定原因，可空）表示安全锁定；「锁定」由 `locked_at` 非空推导，`status` 仅存 enabled/disabled。停用或锁定的用户 SHALL 均无法登录。

#### Scenario: 锁定登录
- **WHEN** 锁定用户（locked_at 非空）尝试登录
- **THEN** 系统拒绝登录并提示账号已锁定

#### Scenario: 停用登录
- **WHEN** 停用用户（status=disabled）尝试登录
- **THEN** 系统拒绝登录并提示账号已停用

### Requirement: 待改密标记
user 实体 SHALL 通过 `must_change_password`（布尔，默认 false）标记待改密状态：管理员重置密码、租户初始化下发随机密码、创建用户（默认）时置 true；创建用户时管理员可显式关闭；用户自行改密成功后置 false。

#### Scenario: 临时密码置标记
- **WHEN** 管理员重置密码或初始化租户下发临时密码
- **THEN** 该用户 must_change_password 为 true

#### Scenario: 创建用户默认强制改密
- **WHEN** 管理员创建用户（未显式关闭「首登强制改密」）
- **THEN** 该用户 must_change_password 为 true；显式关闭则为 false

#### Scenario: 改密清除标记
- **WHEN** 用户修改本人密码成功
- **THEN** 该用户 must_change_password 置为 false

### 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，取值不脱离上述集合