junhong_cmp_fiber/docs/database-migration-summary.md

数据库迁移总结

迁移版本：000004_create_personal_customer_relations

执行时间：2026-01-10 执行状态：✅ 成功 执行耗时：307ms

---

创建的表

1. personal_customer_phone（个人客户手机号绑定表）

用途：存储个人客户绑定的手机号信息，支持一对多关系

字段列表：

字段名	类型	说明
id	INTEGER	主键ID
customer_id	INTEGER	个人客户ID（关联 personal_customer 表）
phone	VARCHAR(20)	手机号
is_primary	BOOLEAN	是否主手机号（默认 false）
verified_at	TIMESTAMP	验证通过时间
status	INTEGER	状态（0=禁用 1=启用，默认 1）
created_at	TIMESTAMP	创建时间
updated_at	TIMESTAMP	更新时间
deleted_at	TIMESTAMP	删除时间（软删除）

索引：

• ✅ idx_personal_customer_phone_customer_phone - 唯一索引 (customer_id, phone) WHERE deleted_at IS NULL
• ✅ idx_personal_customer_phone_phone - 普通索引 (phone)
• ✅ idx_personal_customer_phone_deleted_at - 普通索引 (deleted_at)
• ✅ personal_customer_phone_pkey - 主键索引 (id)

---

2. personal_customer_iccid（个人客户ICCID绑定表）

用途：记录个人客户使用过的 ICCID，支持多对多关系

字段列表：

字段名	类型	说明
id	INTEGER	主键ID
customer_id	INTEGER	个人客户ID（关联 personal_customer 表）
iccid	VARCHAR(20)	ICCID（20位数字）
bind_at	TIMESTAMP	绑定时间
last_used_at	TIMESTAMP	最后使用时间
status	INTEGER	状态（0=禁用 1=启用，默认 1）
created_at	TIMESTAMP	创建时间
updated_at	TIMESTAMP	更新时间
deleted_at	TIMESTAMP	删除时间（软删除）

索引：

• ✅ idx_personal_customer_iccid_customer_iccid - 唯一索引 (customer_id, iccid) WHERE deleted_at IS NULL
• ✅ idx_personal_customer_iccid_iccid - 普通索引 (iccid)
• ✅ idx_personal_customer_iccid_deleted_at - 普通索引 (deleted_at)
• ✅ personal_customer_iccid_pkey - 主键索引 (id)

---

3. personal_customer_device（个人客户设备号绑定表）

用途：记录个人客户使用过的设备号/IMEI，支持多对多关系（可选）

字段列表：

字段名	类型	说明
id	INTEGER	主键ID
customer_id	INTEGER	个人客户ID（关联 personal_customer 表）
device_no	VARCHAR(50)	设备号/IMEI
bind_at	TIMESTAMP	绑定时间
last_used_at	TIMESTAMP	最后使用时间
status	INTEGER	状态（0=禁用 1=启用，默认 1）
created_at	TIMESTAMP	创建时间
updated_at	TIMESTAMP	更新时间
deleted_at	TIMESTAMP	删除时间（软删除）

索引：

• ✅ idx_personal_customer_device_customer_device - 唯一索引 (customer_id, device_no) WHERE deleted_at IS NULL
• ✅ idx_personal_customer_device_device_no - 普通索引 (device_no)
• ✅ idx_personal_customer_device_deleted_at - 普通索引 (deleted_at)
• ✅ personal_customer_device_pkey - 主键索引 (id)

---

数据库设计原则

核心设计理念

1. 无外键约束：所有表之间不建立 Foreign Key 约束，提高灵活性和性能
2. 软删除支持：所有表都包含 deleted_at 字段，支持软删除
3. 唯一性保证：通过唯一索引（带 WHERE deleted_at IS NULL 条件）保证业务唯一性
4. 查询优化：为常用查询字段创建普通索引

业务模型关系

PersonalCustomer (1) ──< (N) PersonalCustomerPhone
PersonalCustomer (N) ──< (M) PersonalCustomerICCID
PersonalCustomer (N) ──< (M) PersonalCustomerDevice

• 个人客户 ←→ 手机号：一对多（一个客户可以绑定多个手机号）
• 个人客户 ←→ ICCID：多对多（一个客户可以使用多个 ICCID，一个 ICCID 可以被多个客户使用）
• 个人客户 ←→ 设备号：多对多（一个客户可以使用多个设备，一个设备可以被多个客户使用）

---

Makefile 命令

为了方便后续的数据库迁移操作，已添加以下 Makefile 命令：

# 执行所有待执行的迁移（升级数据库）
make migrate-up

# 回滚最后一次迁移（降级数据库）
make migrate-down

# 查看当前迁移版本
make migrate-version

# 创建新的迁移脚本
make migrate-create

---

迁移验证

表验证

✅ 个人客户相关表列表:
  - personal_customer_device
  - personal_customer_iccid
  - personal_customer_phone

索引验证

所有表的索引都已成功创建：

• ✅ 主键索引
• ✅ 唯一索引（带软删除过滤）
• ✅ 查询优化索引
• ✅ 软删除索引

---

下一步

1. 数据初始化（可选）

   • 如需初始化测试数据，可以创建 seed 脚本

2. 业务逻辑实现

   • 已完成：Service 层、Handler 层、路由注册
   • 待完成：单元测试、集成测试

3. 性能监控

   • 监控索引使用情况
   • 监控查询性能
   • 根据实际使用情况优化索引

---

注意事项

⚠️ 生产环境部署前的检查清单：

1. 确认数据库备份已完成
2. 在预发布环境测试迁移脚本
3. 确认索引创建不会影响现有查询性能
4. 准备回滚方案（已提供 .down.sql 脚本）
5. 评估迁移执行时间，选择合适的维护窗口

---

迁移完成时间：2026-01-10 文档版本：v1.0