jw-beauty/docs/design/04-数据库表结构设计.md

数据库表结构设计

基于 软件系统说明.docx 整理。本文档用于把已知数据实体推进到表级字段草案，便于后续直接转成 DDL。

本文档仍然遵循一个原则：不把文档未确认的业务规则写成既定事实。以下字段草案中，凡是来源仅为"推导"而非"文档原文确认"的，会标明"待确认"。所有表名、字段名均为设计阶段讨论名，不代表最终数据库列名。

全局设计约定

以下约定建议在所有表统一采用：

• 主键：统一使用自增 id，类型 BIGINT UNSIGNED，具体方案待确认
• 时间字段：created_at、updated_at，类型 DATETIME，时区统一为待确认
• 软删：建议统一使用 deleted_at，值为 NULL 表示未删除，具体策略待确认
• 字符集：建议统一 utf8mb4
• 审计：建议所有表至少保留 created_at 和 updated_at

已确认逻辑表

• users
• devices
• bindings
• subscriptions
• sessions
• treatment_records
• pd_data
• operation_logs

表级字段草案

users

承载用户身份与账号信息。

字段名	建议类型	是否必填	默认值	来源	说明
id	BIGINT UNSIGNED	是	自增	约定	主键
openid	VARCHAR(128)	是	无	推导	微信用户唯一标识，待确认字段名
union_id	VARCHAR(128)	否	NULL	推导	微信开放平台跨应用标识，待确认是否需要
nickname	VARCHAR(64)	否	NULL	推导	用户昵称，待确认是否存储
avatar_url	VARCHAR(512)	否	NULL	推导	用户头像地址，待确认是否存储
phone	VARCHAR(32)	否	NULL	推导	手机号，待确认是否需要
status	TINYINT UNSIGNED	是	1	推导	用户状态枚举，待确认
created_at	DATETIME	是	CURRENT_TIMESTAMP	约定	创建时间
updated_at	DATETIME	是	CURRENT_TIMESTAMP ON UPDATE	约定	更新时间
deleted_at	DATETIME	否	NULL	约定	软删时间

建议唯一索引：openid

建议状态枚举（待确认）：

值	含义
1	正常
2	禁用
3	注销

devices

承载设备主数据。

字段名	建议类型	是否必填	默认值	来源	说明
id	BIGINT UNSIGNED	是	自增	约定	主键
device_sn	VARCHAR(64)	是	无	推导	设备序列号，作为设备唯一业务标识，待确认字段名和格式
product_id	VARCHAR(64)	是	无	文档确认	IoT 平台产品 ID
device_name	VARCHAR(128)	是	无	文档确认	IoT 平台设备名称
firmware_version	VARCHAR(32)	否	NULL	推导	当前固件版本
hardware_version	VARCHAR(32)	否	NULL	推导	硬件版本
status	TINYINT UNSIGNED	是	1	推导	设备状态枚举，待确认
activated_at	DATETIME	否	NULL	推导	首次激活时间
created_at	DATETIME	是	CURRENT_TIMESTAMP	约定	创建时间
updated_at	DATETIME	是	CURRENT_TIMESTAMP ON UPDATE	约定	更新时间
deleted_at	DATETIME	否	NULL	约定	软删时间

建议唯一索引：device_sn

建议状态枚举（待确认）：

值	含义
1	未激活
2	已激活
3	禁用
4	故障

bindings

承载用户与设备的绑定关系。

字段名	建议类型	是否必填	默认值	来源	说明
id	BIGINT UNSIGNED	是	自增	约定	主键
user_id	BIGINT UNSIGNED	是	无	推导	关联 users.id
device_id	BIGINT UNSIGNED	是	无	推导	关联 devices.id
status	TINYINT UNSIGNED	是	1	推导	绑定状态枚举，待确认
bound_at	DATETIME	是	CURRENT_TIMESTAMP	推导	绑定时间
unbound_at	DATETIME	否	NULL	推导	解绑时间
created_at	DATETIME	是	CURRENT_TIMESTAMP	约定	创建时间
updated_at	DATETIME	是	CURRENT_TIMESTAMP ON UPDATE	约定	更新时间

建议索引：user_id + status，device_id + status

建议状态枚举（待确认）：

值	含义
1	有效
2	已解绑

待确认关系约束：

• 同一时刻一个用户是否只能绑定一台设备
• 同一时刻一台设备是否只能绑定一个用户
• 解绑后是否保留历史记录

subscriptions

承载试用与正式订阅信息。

字段名	建议类型	是否必填	默认值	来源	说明
id	BIGINT UNSIGNED	是	自增	约定	主键
user_id	BIGINT UNSIGNED	是	无	推导	关联 users.id，待确认是否同时关联设备
device_id	BIGINT UNSIGNED	否	NULL	推导	关联 devices.id，待确认是否需要
type	TINYINT UNSIGNED	是	无	推导	订阅类型枚举
status	TINYINT UNSIGNED	是	1	推导	订阅状态枚举
started_at	DATETIME	是	无	推导	生效时间
expired_at	DATETIME	是	无	推导	到期时间
source	VARCHAR(32)	否	NULL	推导	来源说明，如 trial_grant、manual_create、purchase，待确认
source_id	VARCHAR(64)	否	NULL	推导	来源关联 ID，如订单号，待确认是否有订单概念
created_at	DATETIME	是	CURRENT_TIMESTAMP	约定	创建时间
updated_at	DATETIME	是	CURRENT_TIMESTAMP ON UPDATE	约定	更新时间

建议索引：user_id + status，user_id + type

建议类型枚举（待确认）：

值	含义
1	试用
2	正式
3	赠送

建议状态枚举（待确认）：

值	含义
1	有效
2	已过期
3	已停用

sessions

承载一次治疗会话的过程态。

字段名	建议类型	是否必填	默认值	来源	说明
id	BIGINT UNSIGNED	是	自增	约定	主键
user_id	BIGINT UNSIGNED	是	无	推导	关联 users.id
device_id	BIGINT UNSIGNED	是	无	推导	关联 devices.id
status	TINYINT UNSIGNED	是	1	推导	会话状态枚举
started_at	DATETIME	否	NULL	推导	会话开始时间
ended_at	DATETIME	否	NULL	推导	会话结束时间
created_at	DATETIME	是	CURRENT_TIMESTAMP	约定	创建时间
updated_at	DATETIME	是	CURRENT_TIMESTAMP ON UPDATE	约定	更新时间

建议索引：user_id + status，device_id

建议状态枚举（待确认）：

值	含义
1	进行中
2	已完成
3	已中断
4	失败

待确认边界：sessions 与 treatment_records 是否一对一。

treatment_records

承载治疗结果记录。

字段名	建议类型	是否必填	默认值	来源	说明
id	BIGINT UNSIGNED	是	自增	约定	主键
session_id	BIGINT UNSIGNED	是	无	推导	关联 sessions.id，待确认一对一还是一对多
user_id	BIGINT UNSIGNED	是	无	推导	关联 users.id，冗余查询用
device_id	BIGINT UNSIGNED	是	无	推导	关联 devices.id，冗余查询用
duration_seconds	INT UNSIGNED	否	NULL	推导	治疗时长秒数，待确认字段名和单位
mode	TINYINT UNSIGNED	否	NULL	推导	治疗模式，待确认枚举
result_summary	VARCHAR(512)	否	NULL	推导	结果摘要，待确认格式
sync_status	TINYINT UNSIGNED	是	1	推导	同步状态，用于追踪异步写入
synced_at	DATETIME	否	NULL	推导	同步完成时间
started_at	DATETIME	否	NULL	推导	治疗开始时间
ended_at	DATETIME	否	NULL	推导	治疗结束时间
created_at	DATETIME	是	CURRENT_TIMESTAMP	约定	创建时间
updated_at	DATETIME	是	CURRENT_TIMESTAMP ON UPDATE	约定	更新时间

建议索引：user_id + started_at，session_id，sync_status

建议同步状态枚举（待确认）：

值	含义
1	待同步
2	已同步
3	同步失败

pd_data

承载与 PD 相关的数据。

当前只知道该表存在，字段无法推导。

字段名	建议类型	是否必填	默认值	来源	说明
id	BIGINT UNSIGNED	是	自增	约定	主键
session_id	BIGINT UNSIGNED	否	NULL	推导	关联 sessions.id，待确认
device_id	BIGINT UNSIGNED	否	NULL	推导	关联 devices.id，待确认
data_payload	待定义	待定义	待定义	待定义	数据内容，格式和结构完全未确认
recorded_at	DATETIME	否	NULL	推导	采集时间
created_at	DATETIME	是	CURRENT_TIMESTAMP	约定	创建时间

待确认：

• PD 的含义和数据来源
• 是否为高频时序数据
• 是否需要单独存储引擎
• 是否按会话切片

operation_logs

承载操作日志。

字段名	建议类型	是否必填	默认值	来源	说明
id	BIGINT UNSIGNED	是	自增	约定	主键
operator_type	TINYINT UNSIGNED	是	无	推导	操作者类型，区分管理员和系统
operator_id	BIGINT UNSIGNED	否	NULL	推导	操作者 ID，关联 users 或后台管理员表
target_type	VARCHAR(32)	是	无	推导	操作对象类型，如 user、device、subscription、binding
target_id	BIGINT UNSIGNED	否	NULL	推导	操作对象 ID
action	VARCHAR(32)	是	无	推导	操作类型，如 create、update、delete、bind、unbind
before_snapshot	TEXT	否	NULL	推导	操作前数据快照，待确认格式
after_snapshot	TEXT	否	NULL	推导	操作后数据快照，待确认格式
ip_address	VARCHAR(64)	否	NULL	推导	操作来源 IP
user_agent	VARCHAR(256)	否	NULL	推导	操作来源客户端标识
remark	VARCHAR(256)	否	NULL	推导	备注说明
created_at	DATETIME	是	CURRENT_TIMESTAMP	约定	创建时间

建议索引：target_type + target_id，operator_type + operator_id，created_at

建议操作者类型枚举（待确认）：

值	含义
1	管理员
2	系统自动

实体关系总结

关系	左侧	右侧	类型	待确认
用户绑定设备	users	devices	通过 bindings 多对多	是，实际可能接近一对一
用户拥有订阅	users	subscriptions	一对多	否
设备关联订阅	devices	subscriptions	待确认	是，是否需要关联
用户发起会话	users	sessions	一对多	否
设备执行会话	devices	sessions	一对多	否
会话产生记录	sessions	treatment_records	待确认	是，一对一还是一对多
会话产生 PD 数据	sessions	pd_data	待确认	是
操作日志记录对象	operation_logs	各业务表	多态关联	否

每张表仍需补齐的设计项

后续推进到 DDL 时，每张表至少还需要：

• 确认主键方案
• 确认字段类型和长度
• 确认枚举值
• 确认时区约定
• 确认软删策略
• 补充 DDL
• 补充索引设计
• 补充迁移脚本

当前结论

当前说明已经足够把数据库推进到"字段草案"层。所有标为"推导"的字段都需要在下一步被确认或修正。最优先要确认的是 users 与 devices 的绑定约束、subscriptions 的归属模型、sessions 与 treatment_records 的关系。