上传源代码版本

S3链接命名规范.md

@@ -0,0 +1,91 @@
+# 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 | 初始版本 |