refactor(api): type _build_log_dict return with LogDict TypedDict (#34983)

Co-authored-by: Asuka Minato <i@asukaminato.eu.org>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

api/core/logging/structured_formatter.py

@@ -3,7 +3,7 @@
 import logging
 import traceback
 from datetime import UTC, datetime
-from typing import Any, TypedDict
+from typing import Any, NotRequired, TypedDict
 
 import orjson
 
@@ -16,6 +16,19 @@ class IdentityDict(TypedDict, total=False):
     user_type: str
 
 
+class LogDict(TypedDict):
+    ts: str
+    severity: str
+    service: str
+    caller: str
+    message: str
+    trace_id: NotRequired[str]
+    span_id: NotRequired[str]
+    identity: NotRequired[IdentityDict]
+    attributes: NotRequired[dict[str, Any]]
+    stack_trace: NotRequired[str]
+
+
 class StructuredJSONFormatter(logging.Formatter):
     """
     JSON log formatter following the specified schema:
@@ -55,9 +68,9 @@ class StructuredJSONFormatter(logging.Formatter):
 
             return json.dumps(log_dict, default=str, ensure_ascii=False)
 
-    def _build_log_dict(self, record: logging.LogRecord) -> dict[str, Any]:
+    def _build_log_dict(self, record: logging.LogRecord) -> LogDict:
         # Core fields
-        log_dict: dict[str, Any] = {
+        log_dict: LogDict = {
             "ts": datetime.now(UTC).isoformat(timespec="milliseconds").replace("+00:00", "Z"),
             "severity": self.SEVERITY_MAP.get(record.levelno, "INFO"),
             "service": self._service_name,