docs: README 前端构建说明 + AI 使用日志（TS 迁移）

2026-09-12 18:07:54 +08:00
parent 6793fa3658
commit 7becc8265d
3 changed files with 51 additions and 2 deletions
@@ -0,0 +1,32 @@
+# 前端 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）。