From f43101c08078f80613286dd38bf360d9adf6ffa5 Mon Sep 17 00:00:00 2001
From: yml <yml@yml.com>
Date: Thu, 21 May 2026 15:50:49 +0800
Subject: [PATCH] =?UTF-8?q?=E5=90=8E=E7=AB=AF=E8=BF=81=E7=A7=BB=E5=9F=BA?=
 =?UTF-8?q?=E7=A1=80=E5=B7=A5=E5=85=B7=E5=B1=82?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 apps/backend/src/utils/{http.js => http.ts}   | 43 +++++++------------
 .../src/utils/{logger.js => logger.ts}        |  5 +--
 docs/backend-typescript-migration-plan.md     |  9 ++++
 3 files changed, 27 insertions(+), 30 deletions(-)
 rename apps/backend/src/utils/{http.js => http.ts} (88%)
 rename apps/backend/src/utils/{logger.js => logger.ts} (98%)

diff --git a/apps/backend/src/utils/http.js b/apps/backend/src/utils/http.ts
similarity index 88%
rename from apps/backend/src/utils/http.js
rename to apps/backend/src/utils/http.ts
index 72692394..99d1f5bc 100644
--- a/apps/backend/src/utils/http.js
+++ b/apps/backend/src/utils/http.ts
@@ -1,27 +1,21 @@
-// @ts-check
-
 import { logError, logWarn } from './logger.js'
 
 const RESPONSE_TIME_ZONE = 'Asia/Shanghai'
 
-/**
- * @typedef {{
- *   statusCode?: number
- *   errorCode?: string
- *   cause?: unknown
- *   context?: unknown
- *   [key: string]: unknown
- * }} HttpErrorLike
- */
+export type HttpErrorLike = {
+  statusCode?: number
+  errorCode?: string
+  cause?: unknown
+  context?: unknown
+  [key: string]: unknown
+}
 
-/**
- * @typedef {{
- *   statusCode?: number
- *   errorCode?: string
- *   cause?: unknown
- *   context?: unknown
- * }} CreateHttpErrorOptions
- */
+type CreateHttpErrorOptions = {
+  statusCode?: number
+  errorCode?: string
+  cause?: unknown
+  context?: unknown
+}
 
 export function buildSuccessPayload(data, msg = 'ok') {
   return {
@@ -64,14 +58,9 @@ export function buildNotFoundPayload(req) {
   }
 }
 
-/**
- * @param {string} message
- * @param {CreateHttpErrorOptions} [options]
- * @returns {Error & HttpErrorLike}
- */
-export function createHttpError(message, options = {}) {
+export function createHttpError(message: string, options: CreateHttpErrorOptions = {}): Error & HttpErrorLike {
   const { statusCode = 500, errorCode = '', cause, context } = options
-  const error = /** @type {Error & HttpErrorLike} */ (new Error(message))
+  const error = new Error(message) as Error & HttpErrorLike
   error.statusCode = statusCode
   error.errorCode = errorCode || defaultErrorCodeForStatus(statusCode)
 
@@ -88,7 +77,7 @@ export function createHttpError(message, options = {}) {
 
 function classifyRouteError(error) {
   if (error && typeof error === 'object') {
-    const currentError = /** @type {HttpErrorLike} */ (error)
+    const currentError = error as HttpErrorLike
     const statusCode = Number(currentError.statusCode)
     const errorCode = String(currentError.errorCode || '').trim()
 
diff --git a/apps/backend/src/utils/logger.js b/apps/backend/src/utils/logger.ts
similarity index 98%
rename from apps/backend/src/utils/logger.js
rename to apps/backend/src/utils/logger.ts
index 117dd89e..e87f8879 100644
--- a/apps/backend/src/utils/logger.js
+++ b/apps/backend/src/utils/logger.ts
@@ -4,6 +4,7 @@ import process from 'node:process'
 import util from 'node:util'
 
 import { PROJECT_ROOT, runtimeConfig } from '../config/runtime.js'
+import type { HttpErrorLike } from './http.js'
 
 const LOG_LEVEL_PRIORITY = {
   debug: 10,
@@ -206,9 +207,7 @@ function normalizeLogValue(value) {
     return JSON.parse(
       JSON.stringify(value, (_key, current) => {
         if (current instanceof Error) {
-          const currentError = /** @type {import('./http.js').HttpErrorLike} */ (
-            /** @type {unknown} */ (current)
-          )
+          const currentError = current as Error & HttpErrorLike
           return {
             name: current.name,
             message: current.message,
diff --git a/docs/backend-typescript-migration-plan.md b/docs/backend-typescript-migration-plan.md
index 2b51901d..fb273d1d 100644
--- a/docs/backend-typescript-migration-plan.md
+++ b/docs/backend-typescript-migration-plan.md
@@ -536,6 +536,15 @@
     - `npm run typecheck`
     - `npm run build`
     - `npm test` 共 139 个用例通过
+120. 后端 HTTP / 日志工具迁移到 `.ts`：
+    - `src/utils/http.ts`
+    - `src/utils/logger.ts`
+121. 路由响应 payload、HTTP 错误分类 / 扩展字段、日志级别 / 文件名 / 过期清理 / 错误序列化已进入 TS 编译链路；`HttpErrorLike` 改为显式导出类型，logger 使用 type-only import 避免运行时循环依赖
+122. Docker 内验证通过：
+    - `src/utils/logger.test.js` 共 7 个用例通过
+    - `npm run typecheck`
+    - `npm run build`
+    - `npm test` 共 139 个用例通过
 
 ## 下一步建议