后端建立 TypeScript 构建链路

docs/backend-typescript-migration-plan.md

@@ -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、库存换码、自动发货补测试
 
 ## 执行原则