# SQL 脚本总结

## 📋 三个核心SQL脚本

### 1️⃣ 完整建表语句
**文件**: `CreateLabelPdfCacheTable_Complete.sql`

**用途**: 从零开始创建label_pdf_cache表  
**包含内容**:
- ✅ 所有18个字段定义（包括新增的OriginalUrl）
- ✅ 主键定义（Id自增）
- ✅ 唯一索引（NeutralWaybillNumber）
- ✅ 复合索引（Status, UpdatedTime）
- ✅ 单列索引（CustomerId, FinalMileTrackingNumber）
- ✅ 表注释和字段注释
- ✅ 字符集为utf8mb4_unicode_ci

**使用场景**: 新环境初始化

---

### 2️⃣ 添加OriginalUrl字段
**文件**: `AlterLabelPdfCacheAddOriginalUrl.sql`

**用途**: 为现有表添加新字段  
**包含内容**:
- ✅ 添加OriginalUrl字段（VARCHAR(500)）
- ✅ 字段位置在FileSize之后
- ✅ 添加相关索引

**使用场景**: 现有环境升级

---

### 3️⃣ 增量迁移脚本
**文件**: `AddOriginalUrlToLabelPdfCache.sql`

**用途**: 完整的数据库迁移脚本  
**包含内容**:
- ✅ 添加字段和索引的完整SQL
- ✅ 所有错误处理逻辑
- ✅ 索引优化配置

**使用场景**: 生产环境迁移

---

## 🔍 字段详细说明

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| Id | bigint | PK, Auto | 主键自增 |
| NeutralWaybillNumber | varchar(50) | UNIQUE | 中性面单号（唯一） |
| PdfBytes | longblob | NULL | PDF二进制内容 |
| PageCount | int | NULL | PDF页数 |
| FileSize | int | NULL | 文件大小（字节） |
| **OriginalUrl** | **varchar(500)** | **NULL** | **原始标签URL（新增）** |
| Status | tinyint | NOT NULL | 缓存状态 |
| RetryCount | int | NOT NULL | 重试次数 |
| LastRetryTime | datetime | NULL | 最后重试时间 |
| ErrorMessage | varchar(500) | NULL | 错误信息 |
| CreatedTime | datetime | NOT NULL | 创建时间 |
| UpdatedTime | datetime | NOT NULL | 更新时间 |
| FinalMileTrackingNumber | varchar(100) | NULL | 尾程跟踪号 |
| CustomerId | int | NULL | 客户ID |
| BarcodeNumber | varchar(100) | NULL | 条码号 |
| BarcodeType | tinyint | NOT NULL | 条码类型 |
| BarcodeConfidence | int | NULL | 识别置信度 |
| BarcodeExtractTime | datetime | NULL | 条码提取时间 |

---

## 📊 索引配置

| 索引名 | 类型 | 字段 | 说明 |
|--------|------|------|------|
| IX_NeutralWaybillNumber | UNIQUE | NeutralWaybillNumber | 唯一索引，用于快速查询 |
| IX_Status_UpdatedTime | 复合 | Status, UpdatedTime DESC | 用于按状态和更新时间查询 |
| IX_CustomerId | 单列 | CustomerId | 用于按客户查询 |
| IX_FinalMileTrackingNumber | 单列 | FinalMileTrackingNumber | 用于按尾程号查询 |

---

## ✅ 使用建议

### 新环境部署
```bash
# 步骤1: 执行完整建表语句
mysql> source CreateLabelPdfCacheTable_Complete.sql;

# 步骤2: 验证表结构
mysql> DESCRIBE label_pdf_cache;
mysql> SHOW INDEXES FROM label_pdf_cache;
```

### 现有环境升级
```bash
# 步骤1: 备份现有数据（重要！）
mysql> BACKUP TABLE label_pdf_cache TO '/backup/';

# 步骤2: 执行迁移脚本
mysql> source AlterLabelPdfCacheAddOriginalUrl.sql;

# 步骤3: 验证
mysql> SELECT COUNT(*) FROM label_pdf_cache;
mysql> SHOW COLUMNS FROM label_pdf_cache LIKE 'OriginalUrl';
```

---

## 🛡️ 注意事项

1. **备份数据** ⚠️
   - 执行ALTER语句前，务必备份现有数据
   - 建议在测试环境先执行

2. **停机计划** ⚠️
   - 如果表数据量很大，ALTER可能需要时间
   - 建议在业务低谷期执行

3. **索引优化** ⚠️
   - 新索引会增加INSERT/UPDATE成本
   - 但会大幅提升查询性能

4. **字符编码** ⚠️
   - 使用utf8mb4_unicode_ci确保中文支持
   - 所有字段都遵循此编码

---

## 📝 执行日志记录模板

```sql
-- 记录迁移执行
SELECT NOW() AS 执行时间, '开始迁移label_pdf_cache表' AS 操作;

-- 备份数据统计
SELECT COUNT(*) AS 现有记录数 FROM label_pdf_cache;

-- 执行迁移
-- [执行AlterLabelPdfCacheAddOriginalUrl.sql]

-- 验证迁移
SELECT COUNT(DISTINCT OriginalUrl) AS URL字段非空记录数 
FROM label_pdf_cache 
WHERE OriginalUrl IS NOT NULL;

-- 验证索引
SHOW INDEXES FROM label_pdf_cache;

-- 完成
SELECT NOW() AS 完成时间, '迁移完成' AS 状态;
```

---

**所有SQL脚本已准备好，根据您的环境选择合适的脚本执行即可！** ✅
