# S3链接命名规范

## 1. 目的

本文档旨在规范S3兼容存储的文件命名规则，确保前端预生成的S3链接与后端实际生成的链接一致，从而实现将S3链接直接存储在出货交接单的POD字段中。

## 2. 命名规则

### 2.1 基本格式

```
{endpoint}/{prefix}{handoverNumber}_{uniqueId}_{originalFileName}
```

### 2.2 各部分说明

- **endpoint**: S3兼容存储的端点，固定为 `https://pod.us-ord-1.linodeobjects.com`
- **prefix**: 前缀，根据文件类型和年月生成
  - 到货交接单: `arrivalhandover/{yearMonth}/`
  - 出货交接单: `shippinghandover/{yearMonth}/`
  - 其他: `pod/`
- **handoverNumber**: 交接单号，用于标识文件所属的交接单
- **uniqueId**: 唯一标识符，使用GUID格式，确保文件名唯一
- **originalFileName**: 原始文件名，保持文件的原始扩展名

### 2.3 示例

```
https://pod.us-ord-1.linodeobjects.com/shippinghandover/202603/BOL-GOFO-20260313123456_550e8400-e29b-41d4-a716-446655440000_example.jpg
```

## 3. 实现方式

### 3.1 前端实现

1. **预生成S3链接**
   - 在用户选择或粘贴图片时，前端根据命名规则预生成S3链接
   - 生成唯一ID时使用GUID格式
   - 将预生成的链接添加到POD链接输入框中

2. **上传文件**
   - 上传文件时，将交接单号和唯一ID传递给后端
   - 确保后端使用相同的命名规则生成文件名

### 3.2 后端实现

1. **接收参数**
   - 接收文件、类型、交接单号和唯一ID列表
   - 如果提供了唯一ID，使用前端传递的ID生成文件名
   - 如果未提供唯一ID，生成新的GUID

2. **生成文件名**
   - 按照命名规则生成文件名
   - 确保生成的链接与前端预生成的链接一致

## 4. 验证方法

1. **前端验证**
   - 检查预生成的S3链接格式是否符合规范
   - 验证链接是否包含交接单号、唯一ID和原始文件名

2. **后端验证**
   - 检查生成的文件名是否与前端传递的唯一ID一致
   - 验证生成的链接是否与前端预生成的链接一致

3. **数据库验证**
   - 检查存储在数据库中的POD链接是否与实际上传的文件链接一致

## 5. 注意事项

1. **唯一性**
   - 确保每个文件都有唯一的文件名，避免覆盖现有文件
   - 使用GUID作为唯一ID，确保全球唯一性

2. **一致性**
   - 前端和后端必须使用相同的命名规则
   - 确保生成的链接格式完全一致

3. **安全性**
   - 确保S3链接具有适当的访问权限
   - 避免在链接中包含敏感信息

4. **可维护性**
   - 命名规则应易于理解和维护
   - 确保代码中的命名规则与文档保持一致

## 6. 版本历史

| 版本 | 日期 | 说明 |
|------|------|------|
| 1.0 | 2026-03-13 | 初始版本 |