LabelChange-server/S3链接命名规范.md

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	初始版本