实现个人客户微信认证和短信验证功能
- 添加个人客户微信登录和手机验证码登录接口 - 实现个人客户设备、ICCID、手机号关联管理 - 添加短信发送服务（HTTP 客户端） - 添加微信认证服务（含 mock 实现） - 添加 JWT Token 生成和验证工具 - 创建数据库迁移脚本（personal_customer 关联表） - 修复测试文件中的路由注册参数错误 - 重构 scripts 目录结构（分离独立脚本到子目录） Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
179
docs/database-migration-summary.md
Normal file
179
docs/database-migration-summary.md
Normal file
@@ -0,0 +1,179 @@
|
||||
# 数据库迁移总结
|
||||
|
||||
## 迁移版本：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 命令：
|
||||
|
||||
```bash
|
||||
# 执行所有待执行的迁移（升级数据库）
|
||||
make migrate-up
|
||||
|
||||
# 回滚最后一次迁移（降级数据库）
|
||||
make migrate-down
|
||||
|
||||
# 查看当前迁移版本
|
||||
make migrate-version
|
||||
|
||||
# 创建新的迁移脚本
|
||||
make migrate-create
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 迁移验证
|
||||
|
||||
### 表验证
|
||||
```bash
|
||||
✅ 个人客户相关表列表:
|
||||
- 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
|
||||
Reference in New Issue
Block a user