From a4169e237e388fd3e766205ed7494a7808ed7cb1 Mon Sep 17 00:00:00 2001
From: wren <“porlong@qq.com”>
Date: Tue, 28 Apr 2026 12:29:01 +0800
Subject: [PATCH] fix: OSS URL store object key only, not absolute path

- OssClient.UploadBytes/UploadText now return object key (relative path)
- Add OssClient.BuildObjectKey method as canonical key builder
- OssClient.BuildObjectUrl preserved for direct-link scenarios
- OssPathUtils.BuildRuleYamlKey/BuildRuleValidationReportKey accept Region
- DB migration: convert 20 existing absolute URLs to object keys
---
 .../fastapi_common_storage/oss_client.py           | 14 ++++++++++++--
 .../fastapi_common_storage/oss_path_utils.py       | 12 +++++++-----
 2 files changed, 19 insertions(+), 7 deletions(-)

diff --git a/fastapi_common/fastapi_common_storage/oss_client.py b/fastapi_common/fastapi_common_storage/oss_client.py
index ed75b8e..0784423 100644
--- a/fastapi_common/fastapi_common_storage/oss_client.py
+++ b/fastapi_common/fastapi_common_storage/oss_client.py
@@ -73,7 +73,7 @@ class OssClient:
             length=len(Content),
             content_type=ContentType,
         )
-        return self.BuildObjectUrl(ObjectKey=ObjectKey, Bucket=TargetBucket)
+        return self.BuildObjectKey(ObjectKey)
 
     def UploadText(
         self,
@@ -174,12 +174,22 @@ class OssClient:
             return False
 
     def BuildObjectUrl(self, ObjectKey: str, Bucket: str | None = None) -> str:
-        """构造对象访问地址。"""
+        """构造对象访问地址（绝对 URL — 仅用于需要直链的场景）。
+
+        Prefer :meth:`BuildObjectKey` for stored references.
+        """
         TargetBucket = Bucket or self.bucket
         if self.baseUrl:
             return f"{self.baseUrl}/{TargetBucket}/{ObjectKey.lstrip('/')}"
         return f"oss://{TargetBucket}/{ObjectKey.lstrip('/')}"
 
+    def BuildObjectKey(self, ObjectKey: str) -> str:
+        """返回规范化的 object key（相对路径，不包含 bucket/host）。
+
+        这是推荐的存储格式——不含协议和主机名，迁移 OSS 实例时无需更新数据库。
+        """
+        return ObjectKey.lstrip("/")
+
     def PresignGetUrl(self, Source: str, Bucket: str | None = None) -> str:
         """生成对象下载签名 URL。"""
         Ref = self.ResolveObjectRef(Source=Source, Bucket=Bucket)
diff --git a/fastapi_common/fastapi_common_storage/oss_path_utils.py b/fastapi_common/fastapi_common_storage/oss_path_utils.py
index 26c0efc..86234ed 100644
--- a/fastapi_common/fastapi_common_storage/oss_path_utils.py
+++ b/fastapi_common/fastapi_common_storage/oss_path_utils.py
@@ -32,11 +32,13 @@ class OssPathUtils:
         return f"artifacts/{Region}/{RunId}/{ArtifactType}/{Detail}"
 
     @staticmethod
-    def BuildRuleYamlKey(RuleType: str, VersionNo: str) -> str:
-        """生成规则 YAML object key。"""
-        return f"rules/{RuleType}/{VersionNo}/rules.yaml"
+    def BuildRuleYamlKey(RuleType: str, VersionNo: str, *, Region: str = "") -> str:
+        """生成规则 YAML object key。Region 为空时省略前缀。"""
+        prefix = f"{Region}/" if Region else ""
+        return f"{prefix}rules/{RuleType}/{VersionNo}/rules.yaml"
 
     @staticmethod
-    def BuildRuleValidationReportKey(RuleType: str, VersionNo: str) -> str:
+    def BuildRuleValidationReportKey(RuleType: str, VersionNo: str, *, Region: str = "") -> str:
         """生成规则校验报告 object key。"""
-        return f"rules/{RuleType}/{VersionNo}/validation_report.json"
+        prefix = f"{Region}/" if Region else ""
+        return f"{prefix}rules/{RuleType}/{VersionNo}/validation_report.json"