91 lines
2.8 KiB
Markdown
91 lines
2.8 KiB
Markdown
# 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 | 初始版本 | |