diff --git a/产品设计文档.md b/产品设计文档.md index 0d8ccfc..c93acf2 100644 --- a/产品设计文档.md +++ b/产品设计文档.md @@ -7,6 +7,7 @@ **相关子文档:** - [洗美报告短视频成片方案(MVP)](./洗美报告短视频成片方案.md) — 过程短视频与 15s 自动成片(规划,与 §5.3 服务报告延伸能力对应) +- [数据库设计规范](./数据库设计规范.md) — 表命名、时间字段、逻辑删除、索引与演进约定 --- diff --git a/数据库设计规范.md b/数据库设计规范.md new file mode 100644 index 0000000..c15431c --- /dev/null +++ b/数据库设计规范.md @@ -0,0 +1,131 @@ +# 宠伴生活馆 - 数据库设计规范 + +> 版本:v1.0 +> 日期:2026-04-17 +> 适用范围:后端(Spring Boot + JPA + MySQL)、与数据模型相关的产品说明 + +**相关文档:** + +- [产品设计文档](./产品设计文档.md) — 业务数据模型总览 +- [前端 UI 规范](./前端UI规范.md) — 与展示无关,仅作项目索引 + +--- + +## 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 | 初稿:命名、时间、逻辑删除、索引、冗余字段 |