# 标签替换系统数据库字典

## 1. 表结构概览

| 表名 | 存储引擎 | 字符集 | 排序规则 | 注释 |
|------|----------|--------|----------|------|
| label_replace_requests | InnoDB | utf8mb4 | utf8mb4_unicode_ci | 标签替换请求表 |

## 2. 表字段详情

### label_replace_requests 表

| 字段名 | 数据类型 | 长度 | 约束 | 默认值 | 注释 |
|--------|----------|------|------|--------|------|
| Id | INT UNSIGNED | 10 | PRIMARY KEY, AUTO_INCREMENT | 无 | 主键ID，自增 |
| BillOfLadingNumber | VARCHAR | 100 | NULL | 无 | 提单号 |
| MasterPackageNumber | VARCHAR | 100 | NULL | 无 | 大包号 |
| ReferenceNumber | VARCHAR | 100 | NULL | 无 | 参考号（一般表示订单号） |
| NeutralWaybillNumber | VARCHAR | 100 | NOT NULL | 无 | 中性面单单号（必填） |
| FinalMileTrackingNumber | VARCHAR | 100 | NULL | 无 | 尾程跟踪单号 |
| Label | LONGTEXT | 无 | NULL | 无 | 标签内容（一般为PDF，可能是base64或其他格式） |
| ReplaceStatus | CHAR | 1 | NOT NULL | 'Y' | 换单状态（Y表示正常换单，N表示冻结换单） |
| CreatedAt | DATETIME | 无 | NOT NULL | 无 | 创建时间 |
| UpdatedAt | DATETIME | 无 | NOT NULL | 无 | 更新时间 |

## 3. 索引信息

### label_replace_requests 表

| 索引名 | 索引类型 | 索引字段 | 注释 |
|--------|----------|----------|------|
| PRIMARY | PRIMARY | Id | 主键索引 |
| idx_neutral_waybill_number | UNIQUE | NeutralWaybillNumber | 中性面单单号唯一索引 |
| idx_created_at | INDEX | CreatedAt | 创建时间索引 |
| idx_replace_status | INDEX | ReplaceStatus | 换单状态索引 |

## 4. 表关系

| 表名 | 关联表 | 关联字段 | 关系类型 | 说明 |
|------|--------|----------|----------|------|
| label_replace_requests | 无 | 无 | 无 | 该表为独立表，无外键关系 |

## 5. 数据字典说明

### 5.1 字段详细说明

#### Id
- **类型**：INT UNSIGNED
- **约束**：主键，自增
- **说明**：唯一标识每条标签替换请求记录

#### BillOfLadingNumber
- **类型**：VARCHAR(100)
- **约束**：可为空
- **说明**：提单号，用于标识货物运输的提单

#### MasterPackageNumber
- **类型**：VARCHAR(100)
- **约束**：可为空
- **说明**：大包号，用于标识运输中的大包装单元

#### ReferenceNumber
- **类型**：VARCHAR(100)
- **约束**：可为空
- **说明**：参考号，通常用于关联订单系统的订单号

#### NeutralWaybillNumber
- **类型**：VARCHAR(100)
- **约束**：必填
- **说明**：中性面单单号，标签替换请求的核心标识，系统会根据此单号判断是否为重复请求

#### FinalMileTrackingNumber
- **类型**：VARCHAR(100)
- **约束**：可为空
- **说明**：尾程跟踪单号，用于追踪货物最后一公里的运输状态

#### Label
- **类型**：LONGTEXT
- **约束**：可为空
- **说明**：标签内容，通常为base64编码的PDF文件

#### ReplaceStatus
- **类型**：CHAR(1)
- **约束**：必填，默认值为'Y'
- **说明**：换单状态，'Y'表示正常换单，'N'表示冻结换单

#### CreatedAt
- **类型**：DATETIME
- **约束**：必填
- **说明**：记录创建时间，使用UTC时间

#### UpdatedAt
- **类型**：DATETIME
- **约束**：必填
- **说明**：记录更新时间，使用UTC时间

### 5.2 索引说明

#### PRIMARY
- **类型**：主键索引
- **字段**：Id
- **说明**：确保每条记录的唯一性，提高根据ID查询的性能

#### idx_neutral_waybill_number
- **类型**：普通索引
- **字段**：NeutralWaybillNumber
- **说明**：提高根据中性面单单号查询的性能，用于判断请求是否重复

#### idx_created_at
- **类型**：普通索引
- **字段**：CreatedAt
- **说明**：提高按创建时间排序和查询的性能

#### idx_replace_status
- **类型**：普通索引
- **字段**：ReplaceStatus
- **说明**：提高按换单状态筛选查询的性能

## 6. 数据操作规范

### 6.1 插入数据
- 必须提供NeutralWaybillNumber字段
- ReplaceStatus字段如不提供，默认为'Y'
- CreatedAt和UpdatedAt字段由应用程序自动设置为当前UTC时间

### 6.2 更新数据
- 更新时必须更新UpdatedAt字段为当前UTC时间
- 中性面单单号（NeutralWaybillNumber）一般不建议修改

### 6.3 查询数据
- 建议使用索引字段进行查询，如NeutralWaybillNumber、CreatedAt、ReplaceStatus
- 避免使用SELECT *，只查询需要的字段

### 6.4 删除数据
- 建议使用软删除（更新状态字段）而不是物理删除
- 如果必须物理删除，应谨慎操作，确保不会影响其他功能

## 7. 表使用场景

### label_replace_requests 表
- 存储标签替换请求的详细信息
- 用于记录和跟踪标签替换的历史记录
- 支持根据中性面单单号进行重复请求判断
- 支持按换单状态筛选和统计

## 8. 注意事项

1. **数据类型选择**：
   - 字符串类型使用VARCHAR而非CHAR，节省存储空间
   - 标签内容使用LONGTEXT以支持较大的base64编码内容

2. **性能优化**：
   - 已创建必要的索引以提高查询性能
   - 避免在LONGTEXT字段上创建索引

3. **数据一致性**：
   - 确保CreatedAt和UpdatedAt字段在插入和更新时正确设置
   - 中性面单单号应保持唯一性（应用程序层面保证）

4. **安全考虑**：
   - 敏感数据（如标签内容）应考虑加密存储
   - 定期清理过期数据，避免表过大影响性能

5. **扩展考虑**：
   - 表结构设计考虑了未来扩展需求，可根据业务需要添加新字段
   - 索引设计可根据实际查询需求进行调整

---

**文档更新时间**：2026-01-14
**文档版本**：1.0
**文档作者**：系统生成