feat: add document versioning and list API

fastapi_common/fastapi_common_storage/oss_path_utils.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import re
 from pathlib import Path
 
 
@@ -16,10 +17,18 @@ class OssPathUtils:
         Version: str,
         FileRole: str,
         FileName: str,
+        Year: int | None = None,
+        Month: int | None = None,
     ) -> str:
         """生成业务文档 object key。"""
         Ext = Path(FileName).suffix or ""
-        return f"bdocs/{Region}/{TypeCode}/{DocumentId}/{Version}/{FileRole}{Ext}"
+        safe_stem = OssPathUtils.BuildSafeFileStem(FileName)
+        year_prefix = f"{Year:04d}" if Year is not None else "unknown-year"
+        month_prefix = f"{Month:02d}" if Month is not None else "unknown-month"
+        return (
+            f"bdocs/{Region}/{TypeCode}/{year_prefix}/{month_prefix}/"
+            f"{DocumentId}/{Version}/{FileRole}__{safe_stem}{Ext}"
+        )
 
     @staticmethod
     def BuildArtifactKey(
@@ -42,3 +51,12 @@ class OssPathUtils:
         """生成规则校验报告 object key。"""
         prefix = f"{Region}/" if Region else ""
         return f"{prefix}rules/{RuleType}/{VersionNo}/validation_report.json"
+
+    @staticmethod
+    def BuildSafeFileStem(FileName: str) -> str:
+        """生成适合放进 object key 的可读文件名主体。"""
+        stem = Path(FileName).stem.strip() or "upload"
+        stem = re.sub(r"[\\/:*?\"<>|]+", "_", stem)
+        stem = re.sub(r"\s+", "_", stem)
+        stem = re.sub(r"_+", "_", stem).strip("_")
+        return (stem or "upload")[:96]