2026Technology-Competition/docs/superpowers/plans/2026-09-12-frontend-ts-esbuild.md

前端 TypeScript + esbuild 迁移计划

决策：Q1(a) 单文件 ESM chat.js；Q2 esbuild；Q3 构建产物入库；Q4 node --test + Node 原生 TS（禁 enum/namespace 等不可擦除语法）。

目标结构

frontend/
  package.json / tsconfig.json / esbuild.config.mjs
  src/{types,api,dom,state,ws,main}.ts
  tests/{state,ws}.test.ts

• 构建产物：src/genesis/server/static/chat.js（ESM，入库）。
• chat_state.js / chat_ws.js 删除（并入 bundle）。
• chat.html：<script type="module" src="/static/chat.js?v=__ASSET_VER__">。
• app.py _asset_names → chat.html, chat.css, chat.js, favicon.svg。
• Python 测试 /static/chat_state.js、/static/chat_ws.js → 改指向 /static/chat.js。
• 旧 tests/test_chat_state.js、tests/test_chat_ws.js → 迁移到 frontend/tests/*.test.ts。

任务

1. 工具链：package.json / tsconfig(strict) / esbuild.config.mjs。
2. 基础设施：types.ts / api.ts / dom.ts。
3. 迁移 state.ts（纯函数）+ tests/state.test.ts。
4. 迁移 ws.ts + tests/ws.test.ts。
5. 迁移 main.ts（业务 + DOM，类型化）。
6. 构建产物、改 chat.html、删旧 js、改 app.py _asset_names。
7. 改 Python 测试 + 删旧 Node 测试。
8. npm run typecheck + npm test + python -m pytest（≥99%）。
9. 文档/日志/提交。

风险

• strict 下 DOM 引用需类型化（用 must/maybe 助手）。
• Node 原生 TS 依赖 Node ≥23.6（本机 24）。