From f26bde22505ab2e001a5841f2f442296eebd507c Mon Sep 17 00:00:00 2001
From: jxxghp <jxxghp@gmail.com>
Date: Sun, 23 Aug 2026 00:54:01 +0800
Subject: [PATCH] refactor: inject api prefix into router startup

---
 app/startup/lifecycle/__init__.py                      |  2 +-
 app/startup/routers_initializer.py                     | 10 +++++-----
 .../architecture/configuration-debt-baseline.json      |  5 ++---
 tests/test_router_aggregation.py                       | 10 ++++++++++
 4 files changed, 18 insertions(+), 9 deletions(-)

diff --git a/app/startup/lifecycle/__init__.py b/app/startup/lifecycle/__init__.py
index 75ed6f5f8..4f3bf3bd6 100644
--- a/app/startup/lifecycle/__init__.py
+++ b/app/startup/lifecycle/__init__.py
@@ -197,7 +197,7 @@ def build_lifecycle_components(app: FastAPI) -> tuple[LifecycleComponent, ...]:
         LifecycleComponent(
             name="路由",
             dependencies=("数据库连接预算",),
-            start=lambda: init_routers(app),
+            start=lambda: init_routers(app, settings.API_V1_STR),
             start_order=60,
             start_timeout_seconds=30,
         ),
diff --git a/app/startup/routers_initializer.py b/app/startup/routers_initializer.py
index 6a31759f6..0c17efb2a 100644
--- a/app/startup/routers_initializer.py
+++ b/app/startup/routers_initializer.py
@@ -1,11 +1,11 @@
 from fastapi import FastAPI
 
-from app.runtime.config import settings
-
-
-def init_routers(app: FastAPI):
+def init_routers(app: FastAPI, api_prefix: str = "/api/v1"):
     """
     初始化路由
+
+    :param app: 需要挂载路由的 FastAPI 应用
+    :param api_prefix: v1 API 根路径，由启动组合根传入
     """
     from app.api.router_specs import API_V1_ROUTER_SPECS
     from app.api.servarr import arr_router
@@ -14,7 +14,7 @@ def init_routers(app: FastAPI):
     for spec in API_V1_ROUTER_SPECS:
         app.include_router(
             spec.router,
-            prefix=f"{settings.API_V1_STR}{spec.prefix}",
+            prefix=f"{api_prefix}{spec.prefix}",
             tags=list(spec.tags),
         )
     # Radarr、Sonarr路由
diff --git a/tests/fixtures/architecture/configuration-debt-baseline.json b/tests/fixtures/architecture/configuration-debt-baseline.json
index 69f9d4f05..cac371264 100644
--- a/tests/fixtures/architecture/configuration-debt-baseline.json
+++ b/tests/fixtures/architecture/configuration-debt-baseline.json
@@ -9,7 +9,7 @@
     "root": "app"
   },
   "settings_imports": {
-    "count": 125,
+    "count": 124,
     "files": [
       "app/adapters/cache/backends.py",
       "app/adapters/cache/redis.py",
@@ -134,8 +134,7 @@
       "app/startup/domain_initializer.py",
       "app/startup/lifecycle/__init__.py",
       "app/startup/modules_initializer.py",
-      "app/startup/plugins_initializer.py",
-      "app/startup/routers_initializer.py"
+      "app/startup/plugins_initializer.py"
     ]
   },
   "system_config_oper_constructions": {
diff --git a/tests/test_router_aggregation.py b/tests/test_router_aggregation.py
index 4f00253bb..c97dba247 100644
--- a/tests/test_router_aggregation.py
+++ b/tests/test_router_aggregation.py
@@ -159,3 +159,13 @@ def test_compatibility_api_router_keeps_public_contract():
         )
     }
     assert expected_paths <= paths
+
+
+def test_init_routers_accepts_composition_root_api_prefix():
+    """路由初始化应使用组合根传入的 API 前缀。"""
+    from app.startup.routers_initializer import init_routers
+
+    app = FastAPI()
+    init_routers(app, "/custom/v1")
+
+    assert "/custom/v1/system/ping" in app.openapi()["paths"]