# 数据库设计

## 1. 数据库概述

Crawlful Hub 项目使用 MySQL 8.0 作为数据库，采用了关系型数据库设计，确保数据的一致性和完整性。本文档详细介绍了项目的数据库表结构、索引和关系。

## 2. 数据库表结构

### 2.1 用户表（cf_user）

| 字段名 | 数据类型 | 约束 | 描述 |
|-------|---------|------|------|
| id | BIGINT | PRIMARY KEY, AUTO_INCREMENT | 用户 ID |
| tenant_id | VARCHAR(255) | NOT NULL | 租户 ID |
| username | VARCHAR(255) | NOT NULL, UNIQUE | 用户名 |
| password | VARCHAR(255) | NOT NULL | 密码（加密存储） |
| email | VARCHAR(255) | NOT NULL, UNIQUE | 邮箱 |
| role | VARCHAR(50) | | 角色 |
| created_at | DATETIME | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | DATETIME | DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 更新时间 |

### 2.2 商品表（cf_product）

| 字段名 | 数据类型 | 约束 | 描述 |
|-------|---------|------|------|
| id | BIGINT | PRIMARY KEY, AUTO_INCREMENT | 商品 ID |
| tenant_id | VARCHAR(255) | NOT NULL | 租户 ID |
| shop_id | VARCHAR(255) | | 店铺 ID |
| title | VARCHAR(255) | NOT NULL | 商品标题 |
| description | TEXT | | 商品描述 |
| main_image | VARCHAR(255) | | 商品主图 |
| platform | VARCHAR(50) | | 平台 |
| platform_product_id | VARCHAR(255) | | 平台商品 ID |
| price | DECIMAL(10,2) | | 价格 |
| cost_price | DECIMAL(10,2) | | 成本价格 |
| quantity | INT | | 数量 |
| status | VARCHAR(50) | | 状态 |
| phash | VARCHAR(255) | | 图片哈希 |
| semantic_hash | VARCHAR(255) | | 语义哈希 |
| vector_embedding | TEXT | | 向量嵌入 |
| attributes | JSON | | 属性 |
| created_at | DATETIME | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | DATETIME | DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 更新时间 |

### 2.3 订单表（cf_order）

| 字段名 | 数据类型 | 约束 | 描述 |
|-------|---------|------|------|
| id | BIGINT | PRIMARY KEY, AUTO_INCREMENT | 订单 ID |
| tenant_id | VARCHAR(255) | NOT NULL | 租户 ID |
| shop_id | VARCHAR(255) | | 店铺 ID |
| platform | VARCHAR(50) | | 平台 |
| platform_order_id | VARCHAR(255) | | 平台订单 ID |
| status | VARCHAR(50) | | 状态 |
| total_amount | DECIMAL(10,2) | | 总金额 |
| currency | VARCHAR(10) | | 货币 |
| customer_info | JSON | | 客户信息 |
| items | JSON | | 商品列表 |
| shipping_address | JSON | |  shipping 地址 |
| tracking_number | VARCHAR(255) | | 跟踪号 |
| created_at | DATETIME | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | DATETIME | DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 更新时间 |

### 2.4 支付表（cf_payment）

| 字段名 | 数据类型 | 约束 | 描述 |
|-------|---------|------|------|
| id | BIGINT | PRIMARY KEY, AUTO_INCREMENT | 支付 ID |
| tenant_id | VARCHAR(255) | NOT NULL | 租户 ID |
| order_id | BIGINT | FOREIGN KEY (order_id) REFERENCES cf_order(id) | 订单 ID |
| payment_method | VARCHAR(50) | | 支付方式 |
| amount | DECIMAL(10,2) | | 金额 |
| currency | VARCHAR(10) | | 货币 |
| status | VARCHAR(50) | | 状态 |
| transaction_id | VARCHAR(255) | | 交易 ID |
| created_at | DATETIME | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | DATETIME | DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 更新时间 |

### 2.5 物流表（cf_logistics）

| 字段名 | 数据类型 | 约束 | 描述 |
|-------|---------|------|------|
| id | BIGINT | PRIMARY KEY, AUTO_INCREMENT | 物流 ID |
| tenant_id | VARCHAR(255) | NOT NULL | 租户 ID |
| order_id | BIGINT | FOREIGN KEY (order_id) REFERENCES cf_order(id) | 订单 ID |
| shipping_method | VARCHAR(50) | | 物流方式 |
| tracking_number | VARCHAR(255) | | 跟踪号 |
| carrier | VARCHAR(50) | | 物流公司 |
| status | VARCHAR(50) | | 状态 |
| estimated_delivery_date | DATETIME | | 预计送达日期 |
| actual_delivery_date | DATETIME | | 实际送达日期 |
| created_at | DATETIME | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | DATETIME | DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 更新时间 |

### 2.6 告警表（cf_alert）

| 字段名 | 数据类型 | 约束 | 描述 |
|-------|---------|------|------|
| id | BIGINT | PRIMARY KEY, AUTO_INCREMENT | 告警 ID |
| tenant_id | VARCHAR(255) | NOT NULL | 租户 ID |
| alert_type | VARCHAR(50) | | 告警类型 |
| severity | VARCHAR(50) | | 严重程度 |
| message | TEXT | | 告警消息 |
| status | VARCHAR(50) | | 状态 |
| source | VARCHAR(255) | | 告警来源 |
| threshold | VARCHAR(255) | | 阈值 |
| actual_value | VARCHAR(255) | | 实际值 |
| created_at | DATETIME | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| resolved_at | DATETIME | | 解决时间 |

### 2.7 审计表（cf_audit）

| 字段名 | 数据类型 | 约束 | 描述 |
|-------|---------|------|------|
| id | BIGINT | PRIMARY KEY, AUTO_INCREMENT | 审计日志 ID |
| tenant_id | VARCHAR(255) | | 租户 ID |
| shop_id | VARCHAR(255) | | 店铺 ID |
| user_id | BIGINT | | 用户 ID |
| action | VARCHAR(255) | | 操作类型 |
| resource_type | VARCHAR(255) | | 资源类型 |
| resource_id | VARCHAR(255) | | 资源 ID |
| ip_address | VARCHAR(100) | | IP 地址 |
| user_agent | TEXT | | 用户代理 |
| details | TEXT | | 详细信息 |
| created_at | DATETIME | DEFAULT CURRENT_TIMESTAMP | 创建时间 |

### 2.8 配置表（cf_config）

| 字段名 | 数据类型 | 约束 | 描述 |
|-------|---------|------|------|
| id | BIGINT | PRIMARY KEY, AUTO_INCREMENT | 配置 ID |
| tenant_id | VARCHAR(255) | | 租户 ID |
| shop_id | VARCHAR(255) | | 店铺 ID |
| config_key | VARCHAR(255) | NOT NULL | 配置键 |
| config_value | VARCHAR(255) | NOT NULL | 配置值 |
| config_type | VARCHAR(50) | | 配置类型 |
| description | TEXT | | 配置描述 |
| created_at | DATETIME | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | DATETIME | DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 更新时间 |

## 3. 索引设计

### 3.1 用户表索引

| 索引名 | 字段 | 类型 | 描述 |
|-------|------|------|------|
| PRIMARY | id | PRIMARY | 主键索引 |
| idx_user_tenant_id | tenant_id | INDEX | 租户 ID 索引 |
| UNIQUE | username | UNIQUE | 用户名唯一索引 |
| UNIQUE | email | UNIQUE | 邮箱唯一索引 |

### 3.2 商品表索引

| 索引名 | 字段 | 类型 | 描述 |
|-------|------|------|------|
| PRIMARY | id | PRIMARY | 主键索引 |
| idx_product_tenant_id | tenant_id | INDEX | 租户 ID 索引 |
| idx_product_platform | platform | INDEX | 平台索引 |

### 3.3 订单表索引

| 索引名 | 字段 | 类型 | 描述 |
|-------|------|------|------|
| PRIMARY | id | PRIMARY | 主键索引 |
| idx_order_tenant_id | tenant_id | INDEX | 租户 ID 索引 |
| idx_order_platform | platform | INDEX | 平台索引 |

### 3.4 支付表索引

| 索引名 | 字段 | 类型 | 描述 |
|-------|------|------|------|
| PRIMARY | id | PRIMARY | 主键索引 |
| idx_payment_tenant_id | tenant_id | INDEX | 租户 ID 索引 |
| idx_payment_order_id | order_id | INDEX | 订单 ID 索引 |

### 3.5 物流表索引

| 索引名 | 字段 | 类型 | 描述 |
|-------|------|------|------|
| PRIMARY | id | PRIMARY | 主键索引 |
| idx_logistics_tenant_id | tenant_id | INDEX | 租户 ID 索引 |
| idx_logistics_order_id | order_id | INDEX | 订单 ID 索引 |

### 3.6 告警表索引

| 索引名 | 字段 | 类型 | 描述 |
|-------|------|------|------|
| PRIMARY | id | PRIMARY | 主键索引 |
| idx_alert_tenant_id | tenant_id | INDEX | 租户 ID 索引 |
| idx_alert_status | status | INDEX | 状态索引 |
| idx_alert_severity | severity | INDEX | 严重程度索引 |
| idx_alert_alert_type | alert_type | INDEX | 告警类型索引 |
| idx_alert_created_at | created_at | INDEX | 创建时间索引 |

### 3.7 审计表索引

| 索引名 | 字段 | 类型 | 描述 |
|-------|------|------|------|
| PRIMARY | id | PRIMARY | 主键索引 |
| idx_audit_tenant_id | tenant_id | INDEX | 租户 ID 索引 |
| idx_audit_shop_id | shop_id | INDEX | 店铺 ID 索引 |
| idx_audit_user_id | user_id | INDEX | 用户 ID 索引 |
| idx_audit_action | action | INDEX | 操作类型索引 |
| idx_audit_resource_type | resource_type | INDEX | 资源类型索引 |
| idx_audit_created_at | created_at | INDEX | 创建时间索引 |

### 3.8 配置表索引

| 索引名 | 字段 | 类型 | 描述 |
|-------|------|------|------|
| PRIMARY | id | PRIMARY | 主键索引 |
| idx_config_tenant_id | tenant_id | INDEX | 租户 ID 索引 |
| idx_config_shop_id | shop_id | INDEX | 店铺 ID 索引 |
| idx_config_key | config_key | INDEX | 配置键索引 |

## 4. 关系设计

### 4.1 表关系

- **用户与订单**：一对多关系，一个用户可以创建多个订单
- **订单与支付**：一对一关系，一个订单对应一个支付
- **订单与物流**：一对一关系，一个订单对应一个物流
- **租户与所有表**：一对多关系，一个租户可以有多个用户、商品、订单等

### 4.2 外键约束

| 表名 | 外键字段 | 引用表 | 引用字段 | 约束 |
|------|---------|--------|---------|------|
| cf_payment | order_id | cf_order | id | ON DELETE CASCADE |
| cf_logistics | order_id | cf_order | id | ON DELETE CASCADE |

## 5. 数据类型选择

### 5.1 字符串类型
- **VARCHAR**：用于存储可变长度的字符串，如用户名、邮箱等
- **TEXT**：用于存储较长的文本，如商品描述、详细信息等
- **JSON**：用于存储 JSON 格式的数据，如客户信息、商品列表等

### 5.2 数值类型
- **BIGINT**：用于存储较大的整数，如 ID 等
- **INT**：用于存储整数，如数量等
- **DECIMAL(10,2)**：用于存储金额，确保精度

### 5.3 日期类型
- **DATETIME**：用于存储日期和时间，如创建时间、更新时间等

## 6. 数据库迁移

Crawlful Hub 项目使用 Flyway 进行数据库迁移，确保数据库结构的版本控制和一致性。

### 6.1 迁移脚本

| 脚本名 | 描述 |
|-------|------|
| V1__init_schema.sql | 初始化数据库表结构 |
| V2__add_alert_table.sql | 添加告警表 |

### 6.2 迁移执行

1. 进入项目目录：
   ```bash
   cd d:\trae_projects\makemd\makemd\serverjava
   ```

2. 执行数据库迁移：
   ```bash
   mvn flyway:migrate
   ```

## 7. 性能优化

### 7.1 索引优化

- **添加适当的索引**：为频繁查询的字段添加索引
- **避免过度索引**：不要为所有字段添加索引，只为必要的字段添加
- **使用复合索引**：对于多字段查询，使用复合索引

### 7.2 查询优化

- **使用分页查询**：避免一次性加载大量数据
- **使用索引覆盖查询**：减少回表操作
- **避免全表扫描**：使用索引进行查询
- **使用预编译语句**：减少 SQL 解析时间

### 7.3 连接池优化

- **使用 HikariCP**：高性能的数据库连接池
- **配置合理的连接数**：根据系统负载配置连接数
- **设置连接超时**：避免连接占用过长时间

## 8. 安全考虑

### 8.1 数据加密

- **密码加密**：使用 BCrypt 加密用户密码
- **敏感数据加密**：对敏感数据进行加密存储

### 8.2 访问控制

- **最小权限原则**：只授予必要的数据库权限
- **使用参数化查询**：防止 SQL 注入攻击
- **定期审计**：定期审计数据库访问日志

## 9. 总结

本数据库设计文档详细介绍了 Crawlful Hub 项目的数据库表结构、索引和关系。通过合理的数据库设计，确保了系统的性能和可靠性。