docs: 更新产品设计文档及数据库设计

产品设计文档.md

@@ -7,6 +7,7 @@
 **相关子文档：**
 
 - [洗美报告短视频成片方案（MVP）](./洗美报告短视频成片方案.md) — 过程短视频与 15s 自动成片（规划，与 §5.3 服务报告延伸能力对应）
+- [数据库设计规范](./数据库设计规范.md) — 表命名、时间字段、逻辑删除、索引与演进约定
 
 ---
 

数据库设计规范.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 | 初稿：命名、时间、逻辑删除、索引、冗余字段 |