433 lines
9.0 KiB
Markdown
433 lines
9.0 KiB
Markdown
# 电子名片系统数据库设计文档
|
||
|
||
## 1. 文档目标
|
||
|
||
本文档用于固定电子名片系统第一阶段的数据库模型，覆盖多租户后台、小程序 `AppID` 绑定、组织/用户/名片、素材、统计、审计等核心模块，并与当前产品文档、技术文档保持一致。
|
||
|
||
对应初始化脚本：
|
||
|
||
- [easycard_init.sql](/Users/slience/postgraduate/easycard/database/mysql/easycard_init.sql)
|
||
- [V1__create_core_schema.sql](/Users/slience/postgraduate/easycard/backend/easycard-boot/src/main/resources/db/migration/mysql/V1__create_core_schema.sql)
|
||
- [V2__seed_platform_base_data.sql](/Users/slience/postgraduate/easycard/backend/easycard-boot/src/main/resources/db/migration/mysql/V2__seed_platform_base_data.sql)
|
||
|
||
## 2. 设计原则
|
||
|
||
### 2.1 总体原则
|
||
|
||
- 数据库：MySQL 8.x
|
||
- 字符集：`utf8mb4`
|
||
- 排序规则：`utf8mb4_0900_ai_ci`
|
||
- 架构模式：单库单 Schema，多租户共享表结构
|
||
- 多租户隔离：业务表统一使用 `tenant_id`
|
||
- 小程序租户识别：使用 `miniapp_app_id` 映射到 `tenant_id`
|
||
|
||
### 2.2 关键约束
|
||
|
||
- 平台级数据使用 `tenant_id = 0`
|
||
- 租户业务数据必须带 `tenant_id > 0`
|
||
- 小程序 `AppID` 全平台唯一
|
||
- 一个租户在同一环境仅允许一条小程序配置
|
||
- 用户、角色、组织编码、专业领域编码等按租户唯一
|
||
|
||
### 2.3 删除策略
|
||
|
||
- 核心业务表默认使用逻辑删除字段 `deleted`
|
||
- 日志和统计明细表默认不做逻辑删除
|
||
- 需要唯一约束的业务表，唯一索引统一带上 `deleted`
|
||
|
||
### 2.4 主键策略
|
||
|
||
第一阶段采用：
|
||
|
||
- `BIGINT UNSIGNED AUTO_INCREMENT`
|
||
|
||
原因：
|
||
|
||
- 对当前规模足够简单稳定
|
||
- 便于直接落地和排查问题
|
||
- 后续如需分布式 ID，可在应用层平滑切换
|
||
|
||
### 2.5 外键策略
|
||
|
||
第一阶段不强依赖数据库物理外键，采用“应用层维护逻辑关联 + 数据库索引约束”的方式。
|
||
|
||
原因：
|
||
|
||
- 更适合多租户共享表结构
|
||
- 更利于后续表结构演进
|
||
- 避免逻辑删除和历史日志场景下的迁移成本
|
||
|
||
## 3. 核心实体关系
|
||
|
||
```mermaid
|
||
erDiagram
|
||
SYS_TENANT ||--o{ TENANT_MINIAPP_CONFIG : has
|
||
SYS_TENANT ||--o{ SYS_USER : owns
|
||
SYS_TENANT ||--o{ SYS_ROLE : owns
|
||
SYS_TENANT ||--o{ ORG_DEPARTMENT : owns
|
||
SYS_TENANT ||--|| ORG_FIRM_PROFILE : owns
|
||
SYS_TENANT ||--o{ ORG_FIRM_PRACTICE_AREA : owns
|
||
SYS_TENANT ||--o{ CARD_PROFILE : owns
|
||
SYS_TENANT ||--o{ FILE_ASSET : owns
|
||
SYS_USER ||--o{ SYS_USER_ROLE : has
|
||
SYS_ROLE ||--o{ SYS_USER_ROLE : assigned
|
||
SYS_ROLE ||--o{ SYS_ROLE_MENU : grants
|
||
SYS_MENU ||--o{ SYS_ROLE_MENU : bound
|
||
ORG_DEPARTMENT ||--o{ SYS_USER : contains
|
||
SYS_USER ||--|| CARD_PROFILE : owns
|
||
CARD_PROFILE ||--o{ CARD_PROFILE_SPECIALTY : has
|
||
ORG_FIRM_PRACTICE_AREA ||--o{ CARD_PROFILE_SPECIALTY : references
|
||
FILE_ASSET ||--o{ FILE_ASSET_USAGE : used_by
|
||
CARD_PROFILE ||--o{ CARD_VIEW_LOG : viewed
|
||
CARD_PROFILE ||--o{ CARD_SHARE_LOG : shared
|
||
CARD_PROFILE ||--o{ CARD_STAT_DAILY : aggregated
|
||
```
|
||
|
||
## 4. 模块划分
|
||
|
||
### 4.1 平台与租户
|
||
|
||
- `sys_tenant`
|
||
- `tenant_miniapp_config`
|
||
- `sys_config`
|
||
|
||
### 4.2 账号与权限
|
||
|
||
- `sys_user`
|
||
- `sys_role`
|
||
- `sys_user_role`
|
||
- `sys_menu`
|
||
- `sys_role_menu`
|
||
|
||
### 4.3 基础字典
|
||
|
||
- `sys_dict_type`
|
||
- `sys_dict_item`
|
||
|
||
### 4.4 组织与事务所信息
|
||
|
||
- `org_department`
|
||
- `org_firm_profile`
|
||
- `org_firm_practice_area`
|
||
|
||
### 4.5 名片与素材
|
||
|
||
- `card_profile`
|
||
- `card_profile_specialty`
|
||
- `file_asset`
|
||
- `file_asset_usage`
|
||
|
||
### 4.6 统计与审计
|
||
|
||
- `card_view_log`
|
||
- `card_share_log`
|
||
- `card_stat_daily`
|
||
- `sys_login_log`
|
||
- `sys_operation_log`
|
||
|
||
## 5. 关键表设计说明
|
||
|
||
## 5.1 `sys_tenant`
|
||
|
||
用途：
|
||
|
||
- 平台租户主表
|
||
- 管理事务所基础信息、到期时间、资源上限、启停用状态
|
||
|
||
关键字段：
|
||
|
||
- `tenant_code`：租户编码，平台唯一
|
||
- `tenant_name`：租户名称
|
||
- `tenant_status`：`ENABLED / DISABLED / EXPIRED`
|
||
- `user_limit`：用户上限
|
||
- `storage_limit_mb`：素材存储空间上限
|
||
|
||
## 5.2 `tenant_miniapp_config`
|
||
|
||
用途：
|
||
|
||
- 维护租户与微信小程序的映射关系
|
||
- 后端通过 `miniapp_app_id` 识别租户
|
||
|
||
关键字段：
|
||
|
||
- `tenant_id`
|
||
- `env_code`：`DEV / TEST / PROD`
|
||
- `miniapp_app_id`
|
||
- `miniapp_app_secret`
|
||
- `miniapp_original_id`
|
||
- `request_domain`
|
||
- `publish_status`：`UNCONFIGURED / DRAFT / PUBLISHED / DISABLED`
|
||
|
||
关键约束：
|
||
|
||
- `miniapp_app_id` 全局唯一
|
||
- `tenant_id + env_code + deleted` 唯一
|
||
|
||
## 5.3 `sys_user`
|
||
|
||
用途：
|
||
|
||
- 平台用户与租户用户统一账号表
|
||
|
||
关键字段：
|
||
|
||
- `tenant_id`：平台用户固定为 `0`
|
||
- `user_type`：`PLATFORM / TENANT`
|
||
- `username`
|
||
- `password_hash`
|
||
- `dept_id`
|
||
- `user_status`：`ENABLED / DISABLED / LOCKED`
|
||
- `must_update_password`
|
||
|
||
关键约束：
|
||
|
||
- `tenant_id + username + deleted` 唯一
|
||
|
||
## 5.4 `sys_role`
|
||
|
||
用途：
|
||
|
||
- 平台角色和租户角色统一管理
|
||
|
||
关键字段：
|
||
|
||
- `role_scope`：`PLATFORM / TENANT`
|
||
- `role_code`
|
||
- `role_name`
|
||
- `data_scope`：`ALL / TENANT / DEPT / SELF`
|
||
- `is_builtin`
|
||
|
||
关键约束：
|
||
|
||
- `tenant_id + role_code + deleted` 唯一
|
||
|
||
补充说明：
|
||
|
||
- 平台初始化脚本仅预置平台超级管理员角色
|
||
- `TENANT_ADMIN`、`TENANT_USER` 这类租户内置角色，应在“创建租户”流程中按租户自动生成
|
||
|
||
## 5.5 `org_department`
|
||
|
||
用途：
|
||
|
||
- 表示总部、分所、部门、业务组等组织树
|
||
|
||
关键字段：
|
||
|
||
- `parent_id`
|
||
- `dept_type`：`HEADQUARTERS / BRANCH / DEPARTMENT / GROUP`
|
||
- `dept_code`
|
||
- `dept_name`
|
||
- `leader_user_id`
|
||
- `display_order`
|
||
|
||
说明：
|
||
|
||
- 小程序前端展示办公机构列表时，可直接读取 `HEADQUARTERS / BRANCH` 类型节点
|
||
|
||
## 5.6 `org_firm_profile`
|
||
|
||
用途：
|
||
|
||
- 事务所对外展示主信息
|
||
|
||
关键字段：
|
||
|
||
- `firm_name`
|
||
- `firm_short_name`
|
||
- `logo_asset_id`
|
||
- `hero_asset_id`
|
||
- `intro`
|
||
- `hotline_phone`
|
||
- `hq_address`
|
||
- `hq_latitude`
|
||
- `hq_longitude`
|
||
|
||
关键约束：
|
||
|
||
- 一个租户仅允许一条有效事务所主页记录
|
||
|
||
## 5.7 `org_firm_practice_area`
|
||
|
||
用途：
|
||
|
||
- 租户级专业领域字典
|
||
|
||
关键字段：
|
||
|
||
- `area_code`
|
||
- `area_name`
|
||
- `display_order`
|
||
- `area_status`
|
||
|
||
## 5.8 `card_profile`
|
||
|
||
用途：
|
||
|
||
- 用户电子名片主表
|
||
|
||
关键字段：
|
||
|
||
- `user_id`
|
||
- `card_name`
|
||
- `card_title`
|
||
- `mobile`
|
||
- `email`
|
||
- `avatar_asset_id`
|
||
- `wechat_qr_asset_id`
|
||
- `bio`
|
||
- `certificate_no`
|
||
- `education_info`
|
||
- `honor_info`
|
||
- `is_public`
|
||
- `publish_status`
|
||
- `display_order`
|
||
- `view_count`
|
||
- `share_count`
|
||
|
||
关键约束：
|
||
|
||
- 一个用户默认一张名片，`tenant_id + user_id + deleted` 唯一
|
||
|
||
## 5.9 `card_profile_specialty`
|
||
|
||
用途：
|
||
|
||
- 名片与专业领域的关联表
|
||
|
||
说明：
|
||
|
||
- 保留 `specialty_name` 快照，避免租户修改专业领域名称后历史展示失真
|
||
|
||
## 5.10 `file_asset`
|
||
|
||
用途：
|
||
|
||
- 管理头像、Logo、封面图、二维码等素材
|
||
|
||
关键字段：
|
||
|
||
- `storage_provider`
|
||
- `bucket_name`
|
||
- `object_key`
|
||
- `original_name`
|
||
- `file_ext`
|
||
- `mime_type`
|
||
- `file_size`
|
||
- `file_hash`
|
||
- `access_url`
|
||
- `asset_status`
|
||
|
||
## 5.11 `file_asset_usage`
|
||
|
||
用途：
|
||
|
||
- 记录素材被哪个业务对象引用
|
||
- 支持后台查看图片使用情况
|
||
|
||
关键字段：
|
||
|
||
- `asset_id`
|
||
- `biz_type`
|
||
- `biz_id`
|
||
- `field_name`
|
||
|
||
## 5.12 `card_view_log` / `card_share_log` / `card_stat_daily`
|
||
|
||
用途：
|
||
|
||
- `card_view_log`：原始浏览明细
|
||
- `card_share_log`：原始分享明细
|
||
- `card_stat_daily`：按日聚合统计
|
||
|
||
说明：
|
||
|
||
- 原始明细用于追溯
|
||
- 聚合表用于后台统计查询
|
||
|
||
## 5.13 `sys_login_log` / `sys_operation_log`
|
||
|
||
用途：
|
||
|
||
- 平台与租户后台的登录审计
|
||
- 关键业务操作审计
|
||
|
||
说明：
|
||
|
||
- 这两张表是安全审计与问题排查的基础，不建议省略
|
||
|
||
## 6. 状态字段建议值
|
||
|
||
### 6.1 租户状态
|
||
|
||
- `ENABLED`
|
||
- `DISABLED`
|
||
- `EXPIRED`
|
||
|
||
### 6.2 用户状态
|
||
|
||
- `ENABLED`
|
||
- `DISABLED`
|
||
- `LOCKED`
|
||
|
||
### 6.3 小程序发布状态
|
||
|
||
- `UNCONFIGURED`
|
||
- `DRAFT`
|
||
- `PUBLISHED`
|
||
- `DISABLED`
|
||
|
||
### 6.4 名片发布状态
|
||
|
||
- `DRAFT`
|
||
- `PUBLISHED`
|
||
- `OFFLINE`
|
||
|
||
### 6.5 文件状态
|
||
|
||
- `UPLOADED`
|
||
- `ACTIVE`
|
||
- `ARCHIVED`
|
||
- `DELETED`
|
||
|
||
## 7. 索引设计原则
|
||
|
||
- 所有高频业务表统一创建 `tenant_id` 索引
|
||
- 所有按编码查找的字段创建唯一索引或普通索引
|
||
- 行为日志按 `tenant_id + card_id + 时间` 建索引
|
||
- 聚合统计表按 `tenant_id + stat_date`、`tenant_id + card_id + stat_date` 建索引
|
||
|
||
## 8. 初始化脚本说明
|
||
|
||
初始化脚本文件：
|
||
|
||
- [easycard_init.sql](/Users/slience/postgraduate/easycard/database/mysql/easycard_init.sql)
|
||
- [Flyway 迁移目录](/Users/slience/postgraduate/easycard/backend/easycard-boot/src/main/resources/db/migration/mysql/README.md)
|
||
|
||
脚本内容包含：
|
||
|
||
- 数据库创建
|
||
- 全部核心表 DDL
|
||
- 索引与唯一约束
|
||
- 默认平台角色初始化
|
||
- 默认基础菜单初始化
|
||
- 默认字典类型与字典项初始化
|
||
|
||
Flyway 版本化脚本拆分为：
|
||
|
||
- `V1__create_core_schema.sql`：只负责建表和索引
|
||
- `V2__seed_platform_base_data.sql`：只负责平台级基础数据
|
||
|
||
## 9. 后续扩展建议
|
||
|
||
当项目进入第二阶段，可在当前模型上继续扩展：
|
||
|
||
- 名片审核表
|
||
- 微信用户绑定表
|
||
- Excel 导入任务表
|
||
- 消息通知表
|
||
- 线索与咨询记录表
|
||
|
||
第一阶段不建议提前引入过多非核心表，优先保证主链路稳定。
|