From 2352269ba94a66782e00a9738395e2df66fa1b48 Mon Sep 17 00:00:00 2001
From: YBoy <231405196+YB0y@users.noreply.github.com>
Date: Fri, 10 Apr 2026 02:32:24 +0200
Subject: [PATCH] refactor(api): type recommend app database retrieval dicts
 with TypedDicts (#34873)

---
 .../database/database_retrieval.py            | 59 ++++++++++++++-----
 1 file changed, 44 insertions(+), 15 deletions(-)

diff --git a/api/services/recommend_app/database/database_retrieval.py b/api/services/recommend_app/database/database_retrieval.py
index 6fb90d356d..1df5fd13b6 100644
--- a/api/services/recommend_app/database/database_retrieval.py
+++ b/api/services/recommend_app/database/database_retrieval.py
@@ -1,3 +1,5 @@
+from typing import Any, TypedDict
+
 from sqlalchemy import select
 
 from constants.languages import languages
@@ -8,16 +10,43 @@ from services.recommend_app.recommend_app_base import RecommendAppRetrievalBase
 from services.recommend_app.recommend_app_type import RecommendAppType
 
 
+class RecommendedAppItemDict(TypedDict):
+    id: str
+    app: App | None
+    app_id: str
+    description: Any
+    copyright: Any
+    privacy_policy: Any
+    custom_disclaimer: str
+    category: str
+    position: int
+    is_listed: bool
+
+
+class RecommendedAppsResultDict(TypedDict):
+    recommended_apps: list[RecommendedAppItemDict]
+    categories: list[str]
+
+
+class RecommendedAppDetailDict(TypedDict):
+    id: str
+    name: str
+    icon: Any
+    icon_background: str | None
+    mode: str
+    export_data: str
+
+
 class DatabaseRecommendAppRetrieval(RecommendAppRetrievalBase):
     """
     Retrieval recommended app from database
     """
 
-    def get_recommended_apps_and_categories(self, language: str):
+    def get_recommended_apps_and_categories(self, language: str) -> RecommendedAppsResultDict:
         result = self.fetch_recommended_apps_from_db(language)
         return result
 
-    def get_recommend_app_detail(self, app_id: str):
+    def get_recommend_app_detail(self, app_id: str) -> RecommendedAppDetailDict | None:
         result = self.fetch_recommended_app_detail_from_db(app_id)
         return result
 
@@ -25,7 +54,7 @@ class DatabaseRecommendAppRetrieval(RecommendAppRetrievalBase):
         return RecommendAppType.DATABASE
 
     @classmethod
-    def fetch_recommended_apps_from_db(cls, language: str):
+    def fetch_recommended_apps_from_db(cls, language: str) -> RecommendedAppsResultDict:
         """
         Fetch recommended apps from db.
         :param language: language
@@ -41,7 +70,7 @@ class DatabaseRecommendAppRetrieval(RecommendAppRetrievalBase):
             ).all()
 
         categories = set()
-        recommended_apps_result = []
+        recommended_apps_result: list[RecommendedAppItemDict] = []
         for recommended_app in recommended_apps:
             app = recommended_app.app
             if not app or not app.is_public:
@@ -51,7 +80,7 @@ class DatabaseRecommendAppRetrieval(RecommendAppRetrievalBase):
             if not site:
                 continue
 
-            recommended_app_result = {
+            recommended_app_result: RecommendedAppItemDict = {
                 "id": recommended_app.id,
                 "app": recommended_app.app,
                 "app_id": recommended_app.app_id,
@@ -67,10 +96,10 @@ class DatabaseRecommendAppRetrieval(RecommendAppRetrievalBase):
 
             categories.add(recommended_app.category)
 
-        return {"recommended_apps": recommended_apps_result, "categories": sorted(categories)}
+        return RecommendedAppsResultDict(recommended_apps=recommended_apps_result, categories=sorted(categories))
 
     @classmethod
-    def fetch_recommended_app_detail_from_db(cls, app_id: str) -> dict | None:
+    def fetch_recommended_app_detail_from_db(cls, app_id: str) -> RecommendedAppDetailDict | None:
         """
         Fetch recommended app detail from db.
         :param app_id: App ID
@@ -89,11 +118,11 @@ class DatabaseRecommendAppRetrieval(RecommendAppRetrievalBase):
         if not app_model or not app_model.is_public:
             return None
 
-        return {
-            "id": app_model.id,
-            "name": app_model.name,
-            "icon": app_model.icon,
-            "icon_background": app_model.icon_background,
-            "mode": app_model.mode,
-            "export_data": AppDslService.export_dsl(app_model=app_model),
-        }
+        return RecommendedAppDetailDict(
+            id=app_model.id,
+            name=app_model.name,
+            icon=app_model.icon,
+            icon_background=app_model.icon_background,
+            mode=app_model.mode,
+            export_data=AppDslService.export_dsl(app_model=app_model),
+        )