后端迁移基础工具层

apps/backend/src/utils/http.ts

@@ -1,27 +1,21 @@
-// @ts-check
-
 import { logError, logWarn } from './logger.js'
 
 const RESPONSE_TIME_ZONE = 'Asia/Shanghai'
 
-/**
+export type HttpErrorLike = {
- * @typedef {{
+  statusCode?: number
- *   statusCode?: number
+  errorCode?: string
- *   errorCode?: string
+  cause?: unknown
- *   cause?: unknown
+  context?: unknown
- *   context?: unknown
+  [key: string]: unknown
- *   [key: string]: unknown
+}
- * }} HttpErrorLike
- */
 
-/**
+type CreateHttpErrorOptions = {
- * @typedef {{
+  statusCode?: number
- *   statusCode?: number
+  errorCode?: string
- *   errorCode?: string
+  cause?: unknown
- *   cause?: unknown
+  context?: unknown
- *   context?: unknown
+}
- * }} CreateHttpErrorOptions
- */
 
 export function buildSuccessPayload(data, msg = 'ok') {
   return {
@@ -64,14 +58,9 @@ export function buildNotFoundPayload(req) {
   }
 }
 
-/**
+export function createHttpError(message: string, options: CreateHttpErrorOptions = {}): Error & HttpErrorLike {
- * @param {string} message
- * @param {CreateHttpErrorOptions} [options]
- * @returns {Error & HttpErrorLike}
- */
-export function createHttpError(message, options = {}) {
   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()
 

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} */ (
+          const currentError = current as Error & HttpErrorLike
-            /** @type {unknown} */ (current)
-          )
           return {
             name: current.name,
             message: current.message,

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 个用例通过
 
 ## 下一步建议