4.9 KiB
4.9 KiB
宠伴生活馆 - 数据库设计规范
版本：v1.0
日期：2026-04-17
适用范围：后端（Spring Boot + JPA + MySQL）、与数据模型相关的产品说明
相关文档：
1. 目标
- 表结构可读、可演进，多人协作时不靠口头约定。
- 与 Java 实体、JPA 映射一致，减少「库里有、代码里没有」的漂移。
- 业务删除以逻辑删除为主，保留审计与恢复空间。
2. 技术前提
| 项 | 约定 |
|---|---|
| 数据库 | MySQL 8.x（建议 utf8mb4 / utf8mb4_unicode_ci） |
| ORM | Spring Data JPA（Hibernate） |
| 时区 | 连接串带 serverTimezone=Asia/Shanghai，应用侧统一东八区语义 |
| 结构演进 | 开发环境可用 spring.jpa.hibernate.ddl-auto=update；生产环境建议改为 validate 或 none，配合显式迁移脚本 |
3. 命名规范
3.1 表名
- 使用小写 + 下划线，业务表统一加前缀
t_。
示例：t_user、t_store、t_appointment、t_report、t_pet。 - 关联表、中间表同样遵循：
t_xxx_yyy或业务可读缩写。
3.2 字段名
- 数据库列：snake_case（
user_id、create_time）。 - Java 实体：camelCase，通过
@Column(name = "xxx")与列名对齐。 - 外键含义字段统一命名为
xxx_id（如store_id、user_id、pet_id）。
3.3 避免保留字与模糊命名
- 避免单独使用
order、group、status等易冲突名时，在业务上可加前缀或放在明确表上下文中；若已使用，保持全项目一致即可。
4. 主键与类型
| 类型 | 约定 |
|---|---|
| 主键 | BIGINT 自增；JPA 使用 @GeneratedValue(strategy = GenerationType.IDENTITY) |
| 金额 | 若后续涉及订单金额，优先用分整型或 DECIMAL，不以 DOUBLE 存金额 |
| 布尔 | MySQL 用 TINYINT(1)；JPA 用 Boolean，必要时 columnDefinition = "TINYINT(1) DEFAULT 0" 与库一致 |
| 文本 | 短字符串 VARCHAR；长描述、备注可用 TEXT（以实体为准） |
5. 时间字段
create_time：创建时间，插入时赋值，一般不在业务修改流程中更新。update_time：最后更新时间，任意业务更新时刷新。- Java 类型统一
LocalDateTime。 - 不在数据库层用
ON UPDATE CURRENT_TIMESTAMP替代应用赋值，除非团队明确约定（当前项目以应用赋值为主）。
6. 逻辑删除（软删除）
6.1 字段约定
- 列名：
deleted - 含义：
0/false表示未删除，1/true表示已删除。 - 新建行必须为未删除；应用层
save时显式setDeleted(false)，避免空值歧义。
6.2 使用范围（本项目）
以下核心业务实体已统一带逻辑删除，列表与详情查询默认只包含 deleted = false 的记录：
- 门店
t_store - 用户
t_user - 宠物
t_pet - 预约
t_appointment - 报告
t_report
6.3 业务规则
- 禁止在业务 Service 中对上述实体使用物理
deleteById（除非运维级清理且走专门流程）。 - 删除操作：将
deleted置为true，并更新update_time。 - 所有自定义查询（JPQL / 原生 SQL）必须显式带上
deleted条件，避免漏过滤。 - 唯一性约束（如手机号唯一）若与软删除并存，需在业务或迁移层设计「仅对未删除行唯一」或预留恢复策略；新增表时提前评审。
6.4 后续扩展（可选）
- 回收站 / 恢复：将
deleted改回false并刷新update_time。 - 删除人 / 删除时间：若审计要求提高，可增加
deleted_at、deleted_by（非当前必选项）。
7. 索引
- 外键及高频筛选字段建立索引：如
user_id、store_id、status、时间排序字段等。 - 联合索引遵循最左前缀：查询条件里经常一起出现的列再组合（如
store_id + status + appointment_time）。 - 命名建议：
idx_<表简写>_<字段简写>，与实体@Index保持一致，便于对照。
8. 冗余字段
- 允许在读多写少、展示为主的表做冗余（如报告中的宠物名、服务类型、预约时间、技师名），以减少联表。
- 冗余字段须在注释或设计文档中标明「来源表 + 字段」，变更来源数据时评估是否同步更新（或由业务流程保证一次性写入）。
9. 与代码的同步
- 新增/变更列：先改 实体类，再让迁移或
ddl-auto落库，避免手写库结构与实体不一致。 - Code Review 检查点：字段名、是否逻辑删除、索引是否与查询一致。
10. 修订记录
| 版本 | 日期 | 说明 |
|---|---|---|
| v1.0 | 2026-04-17 | 初稿：命名、时间、逻辑删除、索引、冗余字段 |