# 数据库ERD图设计文档

## 1. 概述

本文档描述了 Crawlful Hub 系统的数据库实体关系图 (ERD)，展示了系统中各个表之间的关系和依赖。

## 2. 核心实体关系

```mermaid
erDiagram
    %% 租户与店铺
    cf_tenant ||--o{ cf_shop : has
    cf_tenant ||--o{ cf_user : has
    cf_tenant ||--o{ cf_audit_log : logs
    
    %% 店铺相关
    cf_shop ||--o{ cf_product : manages
    cf_shop ||--o{ cf_order : processes
    cf_shop ||--o{ cf_advertisement : runs
    cf_shop ||--o{ cf_certificate : holds
    
    %% 用户与权限
    cf_user ||--o{ cf_user_role : assigns
    cf_role ||--o{ cf_user_role : has
    cf_role ||--o{ cf_role_permission : grants
    cf_permission ||--o{ cf_role_permission : includes
    
    %% 商品与订单
    cf_product ||--o{ cf_order_item : contains
    cf_product ||--o{ cf_advertisement : promotes
    
    %% 订单相关
    cf_order ||--o{ cf_order_item : consists_of
    
    %% 广告相关
    cf_advertisement ||--o{ cf_ad_metrics : tracks
    
    %% 合规相关
    cf_certificate ||--o{ cf_compliance_rule : requires
    
    %% 安全与测试
    cf_security_test ||--o{ cf_security_scan : includes
    cf_p0_check ||--o{ cf_regression_test : triggers
```

## 3. 表关系详细说明

### 3.1 租户管理

| 表名 | 关系 | 描述 |
|------|------|------|
| `cf_tenant` | 1:N | 一个租户可以拥有多个店铺、用户和审计日志 |
| `cf_shop` | N:1 | 多个店铺属于同一个租户 |
| `cf_user` | N:1 | 多个用户属于同一个租户 |

### 3.2 店铺管理

| 表名 | 关系 | 描述 |
|------|------|------|
| `cf_shop` | 1:N | 一个店铺可以管理多个商品、处理多个订单、运行多个广告、持有多个证书 |
| `cf_product` | N:1 | 多个商品属于同一个店铺 |
| `cf_order` | N:1 | 多个订单由同一个店铺处理 |
| `cf_advertisement` | N:1 | 多个广告由同一个店铺运行 |
| `cf_certificate` | N:1 | 多个证书属于同一个店铺 |

### 3.3 用户与权限

| 表名 | 关系 | 描述 |
|------|------|------|
| `cf_user` | N:N | 用户与角色之间的多对多关系，通过 `cf_user_role` 表关联 |
| `cf_role` | N:N | 角色与权限之间的多对多关系，通过 `cf_role_permission` 表关联 |
| `cf_permission` | N:N | 权限与角色之间的多对多关系，通过 `cf_role_permission` 表关联 |

### 3.4 商品与订单

| 表名 | 关系 | 描述 |
|------|------|------|
| `cf_product` | 1:N | 一个商品可以出现在多个订单中作为订单项 |
| `cf_order` | 1:N | 一个订单可以包含多个订单项 |
| `cf_order_item` | N:1 | 多个订单项属于同一个订单和同一个商品 |

### 3.5 广告管理

| 表名 | 关系 | 描述 |
|------|------|------|
| `cf_advertisement` | 1:N | 一个广告可以有多个指标记录 |
| `cf_ad_metrics` | N:1 | 多个指标记录属于同一个广告 |

### 3.6 合规管理

| 表名 | 关系 | 描述 |
|------|------|------|
| `cf_compliance_rule` | 1:N | 一个合规规则可以要求多个证书 |
| `cf_certificate` | N:1 | 多个证书满足同一个合规规则 |

### 3.7 安全与测试

| 表名 | 关系 | 描述 |
|------|------|------|
| `cf_security_test` | 1:N | 一个安全测试可以包含多个安全扫描 |
| `cf_p0_check` | 1:N | 一个P0检查可以触发多个回归测试 |

## 4. 外键关系表

| 外键 | 引用表 | 引用字段 | 描述 | 级联操作 |
|------|--------|----------|------|----------|
| `cf_shop.tenant_id` | `cf_tenant` | `id` | 店铺所属租户 | CASCADE |
| `cf_user.tenant_id` | `cf_tenant` | `id` | 用户所属租户 | CASCADE |
| `cf_audit_log.tenant_id` | `cf_tenant` | `id` | 审计日志所属租户 | CASCADE |
| `cf_product.tenant_id` | `cf_tenant` | `id` | 商品所属租户 | CASCADE |
| `cf_product.shop_id` | `cf_shop` | `id` | 商品所属店铺 | CASCADE |
| `cf_order.tenant_id` | `cf_tenant` | `id` | 订单所属租户 | CASCADE |
| `cf_order.shop_id` | `cf_shop` | `id` | 订单所属店铺 | CASCADE |
| `cf_order_item.order_id` | `cf_order` | `id` | 订单项所属订单 | CASCADE |
| `cf_order_item.product_id` | `cf_product` | `id` | 订单项所属商品 | SET NULL |
| `cf_advertisement.tenant_id` | `cf_tenant` | `id` | 广告所属租户 | CASCADE |
| `cf_advertisement.shop_id` | `cf_shop` | `id` | 广告所属店铺 | CASCADE |
| `cf_advertisement.product_id` | `cf_product` | `id` | 广告推广的商品 | SET NULL |
| `cf_ad_metrics.ad_id` | `cf_advertisement` | `id` | 指标所属广告 | CASCADE |
| `cf_certificate.tenant_id` | `cf_tenant` | `id` | 证书所属租户 | CASCADE |
| `cf_certificate.shop_id` | `cf_shop` | `id` | 证书所属店铺 | CASCADE |
| `cf_user_role.user_id` | `cf_user` | `id` | 用户角色关联 | CASCADE |
| `cf_user_role.role_id` | `cf_role` | `id` | 角色用户关联 | CASCADE |
| `cf_role_permission.role_id` | `cf_role` | `id` | 角色权限关联 | CASCADE |
| `cf_role_permission.permission_id` | `cf_permission` | `id` | 权限角色关联 | CASCADE |

## 5. 实体属性说明

### 5.1 核心实体

| 实体 | 主要属性 | 描述 |
|------|----------|------|
| `cf_tenant` | `id`, `name`, `domain`, `status` | 租户信息，包含基本信息和状态 |
| `cf_shop` | `id`, `tenant_id`, `name`, `platform`, `platform_shop_id` | 店铺信息，包含平台信息和认证信息 |
| `cf_user` | `id`, `tenant_id`, `username`, `email`, `password_hash`, `role` | 用户信息，包含认证信息和角色 |
| `cf_product` | `id`, `tenant_id`, `shop_id`, `platform`, `product_id`, `title`, `price`, `stock` | 商品信息，包含基本信息和库存 |
| `cf_order` | `id`, `tenant_id`, `shop_id`, `platform`, `platform_order_id`, `customer_id`, `total`, `status` | 订单信息，包含客户信息和状态 |

### 5.2 关系实体

| 实体 | 主要属性 | 描述 |
|------|----------|------|
| `cf_user_role` | `id`, `user_id`, `role_id` | 用户与角色的关联 |
| `cf_role_permission` | `id`, `role_id`, `permission_id` | 角色与权限的关联 |
| `cf_order_item` | `id`, `order_id`, `product_id`, `quantity`, `unit_price`, `total_price` | 订单项信息 |
| `cf_ad_metrics` | `id`, `ad_id`, `date`, `impressions`, `clicks`, `conversions`, `spend`, `revenue` | 广告指标信息 |

## 6. 业务流程关系

### 6.1 订单处理流程

1. **创建订单**：`cf_order` ← `cf_user`
2. **添加订单项**：`cf_order_item` ← `cf_order` + `cf_product`
3. **更新库存**：`cf_product` ← `cf_order_item`
4. **记录审计**：`cf_audit_log` ← `cf_order`

### 6.2 广告管理流程

1. **创建广告**：`cf_advertisement` ← `cf_shop` + `cf_product`
2. **收集指标**：`cf_ad_metrics` ← `cf_advertisement`
3. **分析数据**：基于 `cf_ad_metrics` 数据进行分析

### 6.3 合规检查流程

1. **上传证书**：`cf_certificate` ← `cf_shop`
2. **检查合规**：基于 `cf_compliance_rule` 检查 `cf_certificate`
3. **生成报告**：基于检查结果生成合规报告

## 7. 数据完整性约束

### 7.1 唯一性约束

| 表名 | 唯一约束 | 描述 |
|------|----------|------|
| `cf_tenant` | `name`, `domain`, `contact_email` | 租户名称、域名和联系邮箱唯一 |
| `cf_shop` | `(platform, platform_shop_id)` | 平台店铺ID唯一 |
| `cf_user` | `username`, `email` | 用户名和邮箱唯一 |
| `cf_product` | `(platform, product_id)` | 平台商品ID唯一 |
| `cf_order` | `(platform, platform_order_id)` | 平台订单ID唯一 |
| `cf_ad_metrics` | `(ad_id, date)` | 广告每日指标唯一 |
| `cf_user_role` | `(user_id, role_id)` | 用户角色组合唯一 |
| `cf_role_permission` | `(role_id, permission_id)` | 角色权限组合唯一 |

### 7.2 非空约束

所有外键字段、主键字段以及业务关键字段都设置了非空约束，确保数据完整性。

## 8. 索引策略

### 8.1 主键索引

所有表的 `id` 字段都设置为主键，自动创建主键索引。

### 8.2 外键索引

所有外键字段都创建了索引，以提高关联查询性能。

### 8.3 业务索引

| 表名 | 索引字段 | 描述 |
|------|----------|------|
| `cf_tenant` | `domain`, `status` | 加速租户域名查询和状态筛选 |
| `cf_shop` | `platform`, `status` | 加速平台店铺查询和状态筛选 |
| `cf_user` | `username`, `email`, `role` | 加速用户登录和角色查询 |
| `cf_product` | `category`, `brand`, `status` | 加速商品分类和品牌查询 |
| `cf_order` | `status`, `customer_id` | 加速订单状态和客户查询 |
| `cf_advertisement` | `campaign_id`, `status` | 加速广告活动和状态查询 |
| `cf_ad_metrics` | `date` | 加速日期范围查询 |
| `cf_compliance_rule` | `platform`, `product_category` | 加速平台和分类规则查询 |
| `cf_audit_log` | `action`, `resource_type`, `created_at` | 加速审计日志查询 |

## 9. 总结

本ERD图设计文档展示了 Crawlful Hub 系统的数据库结构和实体关系，为系统开发和维护提供了清晰的参考。通过合理的表设计和关系定义，确保了数据的完整性和一致性，同时优化了查询性能。
