后端建立 TypeScript 构建链路

2026-05-21 13:36:38 +08:00
parent 25671078d6
commit 1476522ab5
18 changed files with 798 additions and 101 deletions
@@ -73,6 +73,7 @@ docker compose -f docker-compose.dev.yml down
 ```bash
 docker compose -f docker-compose.dev.yml exec -T backend npm test
 docker compose -f docker-compose.dev.yml exec -T backend npm run typecheck
+docker compose -f docker-compose.dev.yml exec -T backend npm run build
 docker compose -f docker-compose.dev.yml exec -T frontend npm run typecheck
 docker compose -f docker-compose.dev.yml exec -T frontend npm run lint
 ```
@@ -93,7 +94,7 @@ docker compose -f docker-compose.dev.yml exec -T backend npm run db:migrate

 开发版 Compose 会把源码挂载进容器：

- 修改 `apps/backend/src`：后端容器内 `node --watch` 自动重启
+- 修改 `apps/backend/src`：后端容器内 `tsx watch` 自动重启
 - 修改 `apps/frontend/src`：Vite 自动 HMR
 - 修改 `apps/backend/subservices/ocr-worker`：下次 OCR 调用会使用挂载后的代码
 - 修改数据库 migration：重启后端会自动执行迁移
@@ -36,22 +36,25 @@ Linux 部署：

 ```bash
 npm install
+npm run build
 npm run browser:install:linux
 npm run start
 ```

-后端渐进 TypeScript 迁移已经开始，当前可执行：
+后端渐进 TypeScript 迁移已经进入源码和构建双轨模式：

 ```bash
 npm run typecheck
+npm run build
+npm test
 ```

-第一阶段目前先检查：
+当前约定：

- `src/config/runtime.js`
- `src/types/**/*.js`
-
-后续会逐步扩大到更多 routes / services / repositories，而不会先改成需要编译产物的运行模式。
+- 开发：`npm run dev` 使用 `tsx watch` 直接运行 `src`，并额外监听 `config`
+- 数据库迁移：`npm run db:migrate` 使用 `tsx`
+- 生产：`npm run build` 输出 `dist`，`npm run start` 运行 `dist/index.js`
+- 新增或迁移后端模块优先使用 `.ts`

 ## 配置

@@ -122,6 +125,7 @@ npm run typecheck
 - 后端容器启动时执行 `npm install` 和 `npm run dev`
 - OCR 子服务会在容器里执行 `pip install -e /app/subservices/ocr-worker`
 - 所以平时改 `src/`、改 OCR Python、改 `.env`，一般都不需要重建镜像
+- 生产镜像会在 build 阶段编译后端并只复制 `dist`、`config` 和运行依赖

 只有下面几类改动通常还需要 `docker compose -f docker-compose.dev.yml up -d --build backend`：

@@ -14,9 +14,453 @@
      },
      "devDependencies": {
        "@types/node": "^25.6.0",
+        "@types/pg": "^8.20.0",
+        "tsx": "^4.22.3",
        "typescript": "^6.0.2"
      }
    },
+    "node_modules/@esbuild/aix-ppc64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.28.0.tgz",
+      "integrity": "sha512-lhRUCeuOyJQURhTxl4WkpFTjIsbDayJHih5kZC1giwE+MhIzAb7mEsQMqMf18rHLsrb5qI1tafG20mLxEWcWlA==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "aix"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-arm": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.28.0.tgz",
+      "integrity": "sha512-wqh0ByljabXLKHeWXYLqoJ5jKC4XBaw6Hk08OfMrCRd2nP2ZQ5eleDZC41XHyCNgktBGYMbqnrJKq/K/lzPMSQ==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-arm64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.28.0.tgz",
+      "integrity": "sha512-+WzIXQOSaGs33tLEgYPYe/yQHf0WTU0X42Jca3y8NWMbUVhp7rUnw+vAsRC/QiDrdD31IszMrZy+qwPOPjd+rw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-x64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.28.0.tgz",
+      "integrity": "sha512-+VJggoaKhk2VNNqVL7f6S189UzShHC/mR9EE8rDdSkdpN0KflSwWY/gWjDrNxxisg8Fp1ZCD9jLMo4m0OUfeUA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/darwin-arm64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.28.0.tgz",
+      "integrity": "sha512-0T+A9WZm+bZ84nZBtk1ckYsOvyA3x7e2Acj1KdVfV4/2tdG4fzUp91YHx+GArWLtwqp77pBXVCPn2We7Letr0Q==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/darwin-x64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.28.0.tgz",
+      "integrity": "sha512-fyzLm/DLDl/84OCfp2f/XQ4flmORsjU7VKt8HLjvIXChJoFFOIL6pLJPH4Yhd1n1gGFF9mPwtlN5Wf82DZs+LQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/freebsd-arm64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.28.0.tgz",
+      "integrity": "sha512-l9GeW5UZBT9k9brBYI+0WDffcRxgHQD8ShN2Ur4xWq/NFzUKm3k5lsH4PdaRgb2w7mI9u61nr2gI2mLI27Nh3Q==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/freebsd-x64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.28.0.tgz",
+      "integrity": "sha512-BXoQai/A0wPO6Es3yFJ7APCiKGc1tdAEOgeTNy3SsB491S3aHn4S4r3e976eUnPdU+NbdtmBuLncYir2tMU9Nw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-arm": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.28.0.tgz",
+      "integrity": "sha512-CjaaREJagqJp7iTaNQjjidaNbCKYcd4IDkzbwwxtSvjI7NZm79qiHc8HqciMddQ6CKvJT6aBd8lO9kN/ZudLlw==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-arm64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.28.0.tgz",
+      "integrity": "sha512-RVyzfb3FWsGA55n6WY0MEIEPURL1FcbhFE6BffZEMEekfCzCIMtB5yyDcFnVbTnwk+CLAgTujmV/Lgvih56W+A==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-ia32": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.28.0.tgz",
+      "integrity": "sha512-KBnSTt1kxl9x70q+ydterVdl+Cn0H18ngRMRCEQfrbqdUuntQQ0LoMZv47uB97NljZFzY6HcfqEZ2SAyIUTQBQ==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-loong64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.28.0.tgz",
+      "integrity": "sha512-zpSlUce1mnxzgBADvxKXX5sl8aYQHo2ezvMNI8I0lbblJtp8V4odlm3Yzlj7gPyt3T8ReksE6bK+pT3WD+aJRg==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-mips64el": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.28.0.tgz",
+      "integrity": "sha512-2jIfP6mmjkdmeTlsX/9vmdmhBmKADrWqN7zcdtHIeNSCH1SqIoNI63cYsjQR8J+wGa4Y5izRcSHSm8K3QWmk3w==",
+      "cpu": [
+        "mips64el"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-ppc64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.28.0.tgz",
+      "integrity": "sha512-bc0FE9wWeC0WBm49IQMPSPILRocGTQt3j5KPCA8os6VprfuJ7KD+5PzESSrJ6GmPIPJK965ZJHTUlSA6GNYEhg==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-riscv64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.28.0.tgz",
+      "integrity": "sha512-SQPZOwoTTT/HXFXQJG/vBX8sOFagGqvZyXcgLA3NhIqcBv1BJU1d46c0rGcrij2B56Z2rNiSLaZOYW5cUk7yLQ==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-s390x": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.28.0.tgz",
+      "integrity": "sha512-SCfR0HN8CEEjnYnySJTd2cw0k9OHB/YFzt5zgJEwa+wL/T/raGWYMBqwDNAC6dqFKmJYZoQBRfHjgwLHGSrn3Q==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-x64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.28.0.tgz",
+      "integrity": "sha512-us0dSb9iFxIi8srnpl931Nvs65it/Jd2a2K3qs7fz2WfGPHqzfzZTfec7oxZJRNPXPnNYZtanmRc4AL/JwVzHQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/netbsd-arm64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.28.0.tgz",
+      "integrity": "sha512-CR/RYotgtCKwtftMwJlUU7xCVNg3lMYZ0RzTmAHSfLCXw3NtZtNpswLEj/Kkf6kEL3Gw+BpOekRX0BYCtklhUw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/netbsd-x64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.28.0.tgz",
+      "integrity": "sha512-nU1yhmYutL+fQ71Kxnhg8uEOdC0pwEW9entHykTgEbna2pw2dkbFSMeqjjyHZoCmt8SBkOSvV+yNmm94aUrrqw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openbsd-arm64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.28.0.tgz",
+      "integrity": "sha512-cXb5vApOsRsxsEl4mcZ1XY3D4DzcoMxR/nnc4IyqYs0rTI8ZKmW6kyyg+11Z8yvgMfAEldKzP7AdP64HnSC/6g==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openbsd-x64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.28.0.tgz",
+      "integrity": "sha512-8wZM2qqtv9UP3mzy7HiGYNH/zjTA355mpeuA+859TyR+e+Tc08IHYpLJuMsfpDJwoLo1ikIJI8jC3GFjnRClzA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openharmony-arm64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.28.0.tgz",
+      "integrity": "sha512-FLGfyizszcef5C3YtoyQDACyg95+dndv79i2EekILBofh5wpCa1KuBqOWKrEHZg3zrL3t5ouE5jgr94vA+Wb2w==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openharmony"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/sunos-x64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.28.0.tgz",
+      "integrity": "sha512-1ZgjUoEdHZZl/YlV76TSCz9Hqj9h9YmMGAgAPYd+q4SicWNX3G5GCyx9uhQWSLcbvPW8Ni7lj4gDa1T40akdlw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "sunos"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-arm64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.28.0.tgz",
+      "integrity": "sha512-Q9StnDmQ/enxnpxCCLSg0oo4+34B9TdXpuyPeTedN/6+iXBJ4J+zwfQI28u/Jl40nOYAxGoNi7mFP40RUtkmUA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-ia32": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.28.0.tgz",
+      "integrity": "sha512-zF3ag/gfiCe6U2iczcRzSYJKH1DCI+ByzSENHlM2FcDbEeo5Zd2C86Aq0tKUYAJJ1obRP84ymxIAksZUcdztHA==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-x64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.28.0.tgz",
+      "integrity": "sha512-pEl1bO9mfAmIC+tW5btTmrKaujg3zGtUmWNdCw/xs70FBjwAL3o9OEKNHvNmnyylD6ubxUERiEhdsL0xBQ9efw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
    "node_modules/@types/node": {
      "version": "25.6.0",
      "resolved": "https://registry.npmjs.org/@types/node/-/node-25.6.0.tgz",
@@ -27,6 +471,18 @@
        "undici-types": "~7.19.0"
      }
    },
+    "node_modules/@types/pg": {
+      "version": "8.20.0",
+      "resolved": "https://registry.npmjs.org/@types/pg/-/pg-8.20.0.tgz",
+      "integrity": "sha512-bEPFOaMAHTEP1EzpvHTbmwR8UsFyHSKsRisLIHVMXnpNefSbGA1bD6CVy+qKjGSqmZqNqBDV2azOBo8TgkcVow==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*",
+        "pg-protocol": "*",
+        "pg-types": "^2.2.0"
+      }
+    },
    "node_modules/accepts": {
      "version": "2.0.0",
      "resolved": "https://registry.npmjs.org/accepts/-/accepts-2.0.0.tgz",
@@ -227,6 +683,48 @@
        "node": ">= 0.4"
      }
    },
+    "node_modules/esbuild": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.28.0.tgz",
+      "integrity": "sha512-sNR9MHpXSUV/XB4zmsFKN+QgVG82Cc7+/aaxJ8Adi8hyOac+EXptIp45QBPaVyX3N70664wRbTcLTOemCAnyqw==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "bin": {
+        "esbuild": "bin/esbuild"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "@esbuild/aix-ppc64": "0.28.0",
+        "@esbuild/android-arm": "0.28.0",
+        "@esbuild/android-arm64": "0.28.0",
+        "@esbuild/android-x64": "0.28.0",
+        "@esbuild/darwin-arm64": "0.28.0",
+        "@esbuild/darwin-x64": "0.28.0",
+        "@esbuild/freebsd-arm64": "0.28.0",
+        "@esbuild/freebsd-x64": "0.28.0",
+        "@esbuild/linux-arm": "0.28.0",
+        "@esbuild/linux-arm64": "0.28.0",
+        "@esbuild/linux-ia32": "0.28.0",
+        "@esbuild/linux-loong64": "0.28.0",
+        "@esbuild/linux-mips64el": "0.28.0",
+        "@esbuild/linux-ppc64": "0.28.0",
+        "@esbuild/linux-riscv64": "0.28.0",
+        "@esbuild/linux-s390x": "0.28.0",
+        "@esbuild/linux-x64": "0.28.0",
+        "@esbuild/netbsd-arm64": "0.28.0",
+        "@esbuild/netbsd-x64": "0.28.0",
+        "@esbuild/openbsd-arm64": "0.28.0",
+        "@esbuild/openbsd-x64": "0.28.0",
+        "@esbuild/openharmony-arm64": "0.28.0",
+        "@esbuild/sunos-x64": "0.28.0",
+        "@esbuild/win32-arm64": "0.28.0",
+        "@esbuild/win32-ia32": "0.28.0",
+        "@esbuild/win32-x64": "0.28.0"
+      }
+    },
    "node_modules/escape-html": {
      "version": "1.0.3",
      "resolved": "https://registry.npmjs.org/escape-html/-/escape-html-1.0.3.tgz",
@@ -981,6 +1479,40 @@
        "node": ">=0.6"
      }
    },
+    "node_modules/tsx": {
+      "version": "4.22.3",
+      "resolved": "https://registry.npmjs.org/tsx/-/tsx-4.22.3.tgz",
+      "integrity": "sha512-mdoNxBC/cSQObGGVQ5Bpn5i+yv7j68gk3Nfm3wFjcJg3Z0Mix9jzAFfP12prmm5eVGmDKtp0yyArrs0Q+8gZHg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "esbuild": "~0.28.0"
+      },
+      "bin": {
+        "tsx": "dist/cli.mjs"
+      },
+      "engines": {
+        "node": ">=18.0.0"
+      },
+      "optionalDependencies": {
+        "fsevents": "~2.3.3"
+      }
+    },
+    "node_modules/tsx/node_modules/fsevents": {
+      "version": "2.3.3",
+      "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
+      "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+      }
+    },
    "node_modules/type-is": {
      "version": "2.0.1",
      "resolved": "https://registry.npmjs.org/type-is/-/type-is-2.0.1.tgz",
@@ -9,11 +9,13 @@
    "agiso:auto-delivery:test": "node scripts/test-agiso-auto-delivery.js",
    "cleanup:dev-data": "node scripts/cleanup-dev-data.js",
    "seed:dev-data": "node scripts/seed-dev-data.js",
-    "db:migrate": "node src/db/migrate.js",
-    "dev": "node --watch-path=src --watch-path=config --watch-preserve-output src/index.js",
-    "test": "node --test $(find src -name '*.test.js' -print)",
+    "build": "tsc -p tsconfig.build.json && rm -rf dist/db/migrations && mkdir -p dist/db && cp -R src/db/migrations dist/db/migrations",
+    "db:migrate": "tsx src/db/migrate.js",
+    "dev": "tsx watch --clear-screen=false --include config src/index.js",
+    "test": "node --import tsx --test $(find src -name '*.test.js' -print)",
    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "start": "node src/index.js"
+    "start": "node dist/index.js",
+    "start:src": "tsx src/index.js"
  },
  "dependencies": {
    "express": "^5.1.0",
@@ -22,6 +24,8 @@
  },
  "devDependencies": {
    "@types/node": "^25.6.0",
+    "@types/pg": "^8.20.0",
+    "tsx": "^4.22.3",
    "typescript": "^6.0.2"
  }
 }
@@ -21,6 +21,10 @@ start_browser_debug_services() {
  display_socket="/tmp/.X11-unix/X${display_number}"
  display_lock="/tmp/.X${display_number}-lock"

+  if [ -S "$display_socket" ] && [ ! -f "$display_lock" ]; then
+    rm -f "$display_socket"
+  fi
+
  if [ -f "$display_lock" ]; then
    display_pid=$(cat "$display_lock" 2>/dev/null || true)
    if [ -z "$display_pid" ] || ! kill -0 "$display_pid" 2>/dev/null; then
@@ -1,10 +1,11 @@
 import { Pool } from 'pg'
+import type { PoolClient, QueryResult, QueryResultRow } from 'pg'

 import { runtimeConfig } from '../config/runtime.js'

-let poolInstance = null
+let poolInstance: Pool | null = null

-export function getDb() {
+export function getDb(): Pool {
  if (!poolInstance) {
    poolInstance = new Pool({
      connectionString: String(runtimeConfig.database?.url || '').trim(),
@@ -16,12 +17,20 @@ export function getDb() {
  return poolInstance
 }

-export async function query(text, params = []) {
+export async function query(text: string, params?: unknown[]): Promise<QueryResult<any>>
+export async function query<T extends QueryResultRow>(
+  text: string,
+  params?: unknown[],
+): Promise<QueryResult<T>>
+export async function query<T extends QueryResultRow>(
+  text: string,
+  params: unknown[] = [],
+): Promise<QueryResult<T>> {
  const pool = getDb()
-  return pool.query(text, params)
+  return pool.query<T>(text, params)
 }

-export async function withTransaction(fn) {
+export async function withTransaction<T>(fn: (client: PoolClient) => Promise<T>): Promise<T> {
  const client = await getDb().connect()

  try {
@@ -37,7 +46,7 @@ export async function withTransaction(fn) {
  }
 }

-export async function closeDb() {
+export async function closeDb(): Promise<void> {
  if (!poolInstance) {
    return
  }
@@ -1,7 +1,46 @@
 import { query } from '../db/client.js'

-export async function createAdminAuditLog(input) {
-  const result = await query(
+type AdminAuditLogRow = {
+  [column: string]: unknown
+  id: number
+  actor_user_id: number | null
+  actor_username: string
+  actor_role: string
+  action: string
+  target_type: string
+  target_id: string
+  payload_json: string | Record<string, unknown>
+  created_at: string
+}
+
+type AdminAuditLogCreateInput = {
+  actorUserId?: number | string | null
+  actorUsername?: string
+  actorRole?: string
+  action: string
+  targetType: string
+  targetId: string
+  payloadJson?: string
+  createdAt: string
+}
+
+type AdminAuditLogListInput = {
+  actorUsername?: string
+  action?: string
+  targetType?: string
+  dateFrom?: string
+  dateTo?: string
+  page?: number | string
+  pageSize?: number | string
+}
+
+type AdminAuditLogListResult = {
+  items: AdminAuditLogRow[]
+  total: number
+}
+
+export async function createAdminAuditLog(input: AdminAuditLogCreateInput): Promise<AdminAuditLogRow | null> {
+  const result = await query<AdminAuditLogRow>(
    `
      INSERT INTO admin_audit_logs (
        actor_user_id,
@@ -30,14 +69,14 @@ export async function createAdminAuditLog(input) {
  return result.rows[0] || null
 }

-export async function getAdminAuditLogById(logId) {
-  const result = await query('SELECT * FROM admin_audit_logs WHERE id = $1 LIMIT 1', [Number(logId)])
+export async function getAdminAuditLogById(logId: number | string): Promise<AdminAuditLogRow | null> {
+  const result = await query<AdminAuditLogRow>('SELECT * FROM admin_audit_logs WHERE id = $1 LIMIT 1', [Number(logId)])
  return result.rows[0] || null
 }

-export async function listAdminAuditLogs(queryInput = {}) {
-  const conditions = []
-  const params = []
+export async function listAdminAuditLogs(queryInput: AdminAuditLogListInput = {}): Promise<AdminAuditLogListResult> {
+  const conditions: string[] = []
+  const params: unknown[] = []

  if (queryInput.actorUsername) {
    params.push(queryInput.actorUsername)
@@ -69,14 +108,14 @@ export async function listAdminAuditLogs(queryInput = {}) {
  const pageSize = Number(queryInput.pageSize) || 20
  const offset = (page - 1) * pageSize

-  const totalResult = await query(
+  const totalResult = await query<{ [column: string]: unknown, total: number }>(
    `SELECT COUNT(*)::int AS total FROM admin_audit_logs ${whereClause}`,
    params,
  )

  params.push(pageSize)
  params.push(offset)
-  const itemsResult = await query(
+  const itemsResult = await query<AdminAuditLogRow>(
    `
      SELECT *
      FROM admin_audit_logs
@@ -1,7 +1,38 @@
 import { query } from '../db/client.js'

-export async function createClaimToken(input) {
-  const result = await query(
+type ClaimTokenRow = {
+  [column: string]: unknown
+  id: number
+  task_id: number
+  token: string
+  status: string
+  expired_at: string
+  used_at: string | null
+  max_use_count: number
+  used_count: number
+  created_at: string
+  updated_at: string
+}
+
+type ClaimTokenCreateInput = {
+  taskId: number
+  token: string
+  status: string
+  expiredAt: string
+  usedAt?: string | null
+  maxUseCount: number
+  usedCount: number
+  createdAt: string
+  updatedAt: string
+}
+
+type ClaimTokenPatch = Partial<Pick<
+  ClaimTokenRow,
+  'status' | 'expired_at' | 'used_at' | 'max_use_count' | 'used_count' | 'updated_at'
+>>
+
+export async function createClaimToken(input: ClaimTokenCreateInput): Promise<ClaimTokenRow | null> {
+  const result = await query<ClaimTokenRow>(
    `
      INSERT INTO claim_tokens (
        task_id,
@@ -42,24 +73,24 @@ export async function createClaimToken(input) {
  return result.rows[0] || null
 }

-export async function getClaimTokenById(tokenId) {
-  const result = await query('SELECT * FROM claim_tokens WHERE id = $1 LIMIT 1', [Number(tokenId)])
+export async function getClaimTokenById(tokenId: number | string): Promise<ClaimTokenRow | null> {
+  const result = await query<ClaimTokenRow>('SELECT * FROM claim_tokens WHERE id = $1 LIMIT 1', [Number(tokenId)])
  return result.rows[0] || null
 }

-export async function findClaimTokenByToken(token) {
-  const result = await query('SELECT * FROM claim_tokens WHERE token = $1 LIMIT 1', [String(token || '').trim()])
+export async function findClaimTokenByToken(token: string): Promise<ClaimTokenRow | null> {
+  const result = await query<ClaimTokenRow>('SELECT * FROM claim_tokens WHERE token = $1 LIMIT 1', [String(token || '').trim()])
  return result.rows[0] || null
 }

-export async function updateClaimToken(tokenId, patch) {
+export async function updateClaimToken(tokenId: number | string, patch: ClaimTokenPatch): Promise<ClaimTokenRow | null> {
  const current = await getClaimTokenById(tokenId)
  if (!current) {
    return null
  }

  const next = { ...current, ...patch }
-  const result = await query(
+  const result = await query<ClaimTokenRow>(
    `
      UPDATE claim_tokens
      SET
@@ -1,38 +0,0 @@
-import { query } from '../db/client.js'
-
-export async function createTaskEvent(taskId, eventType, payload = {}, createdAt) {
-  const result = await query(
-    `
-      INSERT INTO task_events (
-        task_id,
-        event_type,
-        payload_json,
-        created_at
-      ) VALUES ($1, $2, $3::jsonb, $4)
-      RETURNING *
-    `,
-    [
-      Number(taskId),
-      String(eventType || '').trim(),
-      JSON.stringify(payload || {}),
-      createdAt,
-    ],
-  )
-
-  return result.rows[0] || null
-}
-
-export async function listTaskEventsByTaskId(taskId, { limit = 20 } = {}) {
-  const result = await query(
-    `
-      SELECT *
-      FROM task_events
-      WHERE task_id = $1
-      ORDER BY created_at DESC, id DESC
-      LIMIT $2
-    `,
-    [Number(taskId), Math.max(1, Number(limit || 20))],
-  )
-
-  return result.rows
-}
@@ -0,0 +1,59 @@
+import { query } from '../db/client.js'
+
+type TaskEventRow = {
+  [column: string]: unknown
+  id: number
+  task_id: number
+  event_type: string
+  payload_json: string | Record<string, unknown>
+  created_at: string
+}
+
+type TaskEventListOptions = {
+  limit?: number | string
+}
+
+export async function createTaskEvent(
+  taskId: number | string,
+  eventType: string,
+  payload: unknown = {},
+  createdAt: string | undefined = undefined,
+): Promise<TaskEventRow | null> {
+  const result = await query<TaskEventRow>(
+    `
+      INSERT INTO task_events (
+        task_id,
+        event_type,
+        payload_json,
+        created_at
+      ) VALUES ($1, $2, $3::jsonb, $4)
+      RETURNING *
+    `,
+    [
+      Number(taskId),
+      String(eventType || '').trim(),
+      JSON.stringify(payload || {}),
+      createdAt,
+    ],
+  )
+
+  return result.rows[0] || null
+}
+
+export async function listTaskEventsByTaskId(
+  taskId: number | string,
+  { limit = 20 }: TaskEventListOptions = {},
+): Promise<TaskEventRow[]> {
+  const result = await query<TaskEventRow>(
+    `
+      SELECT *
+      FROM task_events
+      WHERE task_id = $1
+      ORDER BY created_at DESC, id DESC
+      LIMIT $2
+    `,
+    [Number(taskId), Math.max(1, Number(limit || 20))],
+  )
+
+  return result.rows
+}
@@ -2,7 +2,17 @@ import { createHttpError } from './http.js'

 const LARGE_INTEGER_PATTERN = /(:\s*)(-?\d{16,})(\s*[,}\]])/g

-export function parseJsonObject(rawText, { preserveLargeIntegers = false, throwOnError = false } = {}) {
+type JsonObject = Record<string, unknown>
+
+type ParseJsonObjectOptions = {
+  preserveLargeIntegers?: boolean
+  throwOnError?: boolean
+}
+
+export function parseJsonObject(
+  rawText: unknown,
+  { preserveLargeIntegers = false, throwOnError = false }: ParseJsonObjectOptions = {},
+): JsonObject {
  const normalized = String(rawText || '').trim()

  if (!normalized) {
@@ -26,7 +36,7 @@ export function parseJsonObject(rawText, { preserveLargeIntegers = false, throwO
  }
 }

-export function wrapLargeIntegerLiterals(rawText) {
+export function wrapLargeIntegerLiterals(rawText: unknown): string {
  return String(rawText || '').replace(LARGE_INTEGER_PATTERN, (_match, prefix, digits, suffix) => {
    if (!shouldPreserveIntegerToken(digits)) {
      return `${prefix}${digits}${suffix}`
@@ -36,7 +46,7 @@ export function wrapLargeIntegerLiterals(rawText) {
  })
 }

-function shouldPreserveIntegerToken(rawDigits) {
+function shouldPreserveIntegerToken(rawDigits: unknown): boolean {
  const digits = String(rawDigits || '').trim()
  const unsigned = digits.startsWith('-') ? digits.slice(1) : digits

@@ -55,6 +65,6 @@ function shouldPreserveIntegerToken(rawDigits) {
  return unsigned > '9007199254740991'
 }

-function isPlainObject(value) {
+function isPlainObject(value: unknown): value is JsonObject {
  return Object.prototype.toString.call(value) === '[object Object]'
 }
@@ -1,4 +1,4 @@
-export function parseAmountToFen(value) {
+export function parseAmountToFen(value: unknown): number {
  const normalized = normalizeAmountInput(value)

  if (!normalized) {
@@ -30,7 +30,7 @@ export function parseAmountToFen(value) {
  return cents * sign
 }

-export function formatFenToAmount(value) {
+export function formatFenToAmount(value: unknown): string {
  const normalizedFen = normalizeFen(value)
  const sign = normalizedFen < 0 ? '-' : ''
  const absoluteFen = Math.abs(normalizedFen)
@@ -39,12 +39,12 @@ export function formatFenToAmount(value) {
  return `${sign}${integerPart}.${fractionPart}`
 }

-export function normalizeFen(value) {
+export function normalizeFen(value: unknown): number {
  const parsed = Number(value)
  return Number.isFinite(parsed) ? Math.round(parsed) : 0
 }

-function normalizeAmountInput(value) {
+function normalizeAmountInput(value: unknown): string {
  if (typeof value === 'number' && Number.isFinite(value)) {
    return String(value)
  }
@@ -1,9 +1,9 @@
 import crypto from 'node:crypto'

-export function randomToken(bytes = 24) {
+export function randomToken(bytes = 24): string {
  return crypto.randomBytes(bytes).toString('hex')
 }

-export function randomId(prefix, bytes = 6) {
+export function randomId(prefix: string, bytes = 6): string {
  return `${prefix}${crypto.randomBytes(bytes).toString('hex')}`
 }
@@ -1,8 +1,8 @@
-export function nowIso() {
+export function nowIso(): string {
  return new Date().toISOString()
 }

-export function addHours(baseIso, hours) {
+export function addHours(baseIso: string | null | undefined, hours: number): string {
  const baseTime = baseIso ? new Date(baseIso).getTime() : Date.now()
  return new Date(baseTime + hours * 60 * 60 * 1000).toISOString()
 }
@@ -0,0 +1,16 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": false,
+    "sourceMap": true
+  },
+  "exclude": [
+    "node_modules",
+    "data",
+    "dist",
+    "src/**/*.test.js"
+  ]
+}
@@ -12,7 +12,8 @@
    "lib": ["ES2022"]
  },
  "include": [
-    "src/**/*.js"
+    "src/**/*.js",
+    "src/**/*.ts"
  ],
  "exclude": [
    "node_modules",
@@ -33,9 +33,6 @@ COPY apps/backend/package.json apps/backend/package-lock.json ./
 RUN --mount=type=cache,target=/root/.npm \
    npm ci

-# --- Prune devDependencies after install ---
-RUN npm prune --omit=dev
-
 # --- Playwright — install Chromium with system deps (builder has full apt) ---
 ENV PLAYWRIGHT_BROWSERS_PATH=/ms-playwright
 RUN --mount=type=cache,target=/ms-playwright-cache,sharing=locked \
@@ -47,6 +44,10 @@ RUN --mount=type=cache,target=/ms-playwright-cache,sharing=locked \
 # --- Copy application source ---
 COPY apps/backend/ ./

+# --- Build application and prune devDependencies ---
+RUN npm run build \
+  && npm prune --omit=dev
+
 # --------------------------- Runtime Stage -----------------------------------
 FROM node:22-bookworm-slim AS runtime

@@ -87,9 +88,9 @@ RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
 # --- Copy artefacts from builder ---
 # Pruned node_modules (no devDeps)
 COPY --from=builder /app/node_modules ./node_modules
-# Application source (no build step — runs directly via `node src/index.js`)
+# Compiled application
 COPY --from=builder /app/package.json ./package.json
-COPY --from=builder /app/src ./src
+COPY --from=builder /app/dist ./dist
 COPY --from=builder /app/config ./config
 # Playwright browsers
 COPY --from=builder /ms-playwright /ms-playwright
@@ -1,6 +1,6 @@
 # Backend TypeScript 迁移计划

-最后更新：2026-04-14
+最后更新：2026-05-21

 ## 结论

@@ -49,14 +49,16 @@

 ## 分阶段计划

-### 阶段 1：建立类型基础设施
+### 阶段 1：建立类型基础设施和构建链路

 目标：

 - 引入后端 `tsconfig`
+- 引入后端 `tsc -> dist` 构建链路
+- 开发和测试改为通过 `tsx` 支持 JS/TS 混合源码
 - 增加 `npm run typecheck`
 - 先从最核心的共享配置和基础领域对象开始建类型
- 暂不改变现有运行方式，不引入编译产物，不影响 Docker 启动
+- 生产 Docker 镜像运行编译后的 `dist`

 范围：

@@ -70,7 +72,9 @@
 验收标准：

 - 后端可以执行 `npm run typecheck`
- 现有 `npm run dev` / `npm run start` / Docker 启动流程不受影响
+- 后端可以执行 `npm run build`
+- `npm run dev` 继续运行源码，`npm run start` 运行 `dist/index.js`
+- Docker 开发环境继续热更新，生产镜像只复制编译产物和运行依赖

 ### 阶段 2：按领域拆分超大 service

@@ -189,19 +193,39 @@
 63. 新增 `src/services/admin/admin-order-read-helpers.js` 与 `src/services/admin/admin-webhook-read-helpers.js`，订单列表汇总与 webhook 事件映射已按领域独立
 64. `admin-read-service / admin-write-service / admin-service` 已全部改为直接依赖 inventory / order / webhook / task / shared 五类 helper，读侧 helper 拆分阶段可以收口

-这一步的设计原则是“只加静态约束，不动运行链路”，所以不会影响：
+## 2026-05-21 执行进展

- `npm run dev`
- `npm run start`
- Docker 开发 / 部署
+本轮已落地：
+
+1. 新增 `tsconfig.build.json`
+2. `npm run build` 输出 `dist`，并复制数据库 migration SQL
+3. `npm run dev` 改为 `tsx watch --clear-screen=false --include config src/index.js`
+4. `npm test` 改为 `node --import tsx --test ...`
+5. `npm run db:migrate` 改为 `tsx src/db/migrate.js`
+6. `npm run start` 改为 `node dist/index.js`
+7. 生产 Dockerfile 改为 builder 阶段编译，runtime 阶段复制 `dist`
+8. 新增 `tsx` 和 `@types/pg`
+9. 首批真实源码迁移到 `.ts`：
+   - `src/db/client.ts`
+   - `src/utils/time.ts`
+   - `src/utils/random.ts`
+   - `src/utils/money.ts`
+   - `src/utils/json.ts`
+   - `src/repositories/claim-token-repo.ts`
+   - `src/repositories/task-event-repo.ts`
+   - `src/repositories/admin-audit-log-repo.ts`
+10. Docker 内验证通过：
+   - `npm run typecheck`
+   - `npm run build`
+   - `npm test`

 ## 下一步建议

 第一批继续推进时，建议按这个顺序：

-1. 为 `admin` 路由层继续补响应模型与审计 payload 的共享类型，减少 `unknown` 到处就地断言
-2. 继续补 repository / service 的边界约束，但不急着改 `.ts` 扩展名
-3. 恢复并固定 `npm --prefix apps/backend run typecheck` 为日常校验步骤，确保本地与 CI 环境都能直接执行
+1. 将 `src/types/*.js` 从 JSDoc typedef 正式改写为 `export type` 的 `.ts` 文件，并逐步更新引用
+2. 继续迁移低风险 repository：`order-item-repo`、`message-delivery-repo`、`webhook-event-repo`
+3. 拆分并迁移 `runtime.js`，把 env 解析、默认配置加载、配置合并分开
 4. 为 webhook、库存换码、自动发货补测试

 ## 执行原则