From 7becc8265d446c44d0bb2d06e4e3f8fc94738479 Mon Sep 17 00:00:00 2001
From: lhl <liuhaili1203@126.com>
Date: Sat, 12 Sep 2026 18:07:54 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20README=20=E5=89=8D=E7=AB=AF=E6=9E=84?=
 =?UTF-8?q?=E5=BB=BA=E8=AF=B4=E6=98=8E=20+=20AI=20=E4=BD=BF=E7=94=A8?=
 =?UTF-8?q?=E6=97=A5=E5=BF=97=EF=BC=88TS=20=E8=BF=81=E7=A7=BB=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md                                     | 19 +++++++++--
 _AI_USAGE_LOG.md                              |  2 ++
 .../plans/2026-09-12-frontend-ts-esbuild.md   | 32 +++++++++++++++++++
 3 files changed, 51 insertions(+), 2 deletions(-)
 create mode 100644 docs/superpowers/plans/2026-09-12-frontend-ts-esbuild.md

diff --git a/README.md b/README.md
index 5a54c5a..2ce4541 100644
--- a/README.md
+++ b/README.md
@@ -125,7 +125,7 @@ python scripts/run_trial.py `
 
 ## Web 服务（聊天式交互，成果物 03）
 
-Genesis 提供 **FastAPI Web 服务 + 内嵌零构建聊天前端**（DeepSeek 式对话页面）：用户用自然语言下达指令，
+Genesis 提供 **FastAPI Web 服务 + TypeScript/esbuild 打包的聊天前端**（DeepSeek 式对话页面）：用户用自然语言下达指令，
 后台自动驱动「解析 →（影响调查）→ 生成 → QA」整条工作流；影响调查完成时会先反问确认，确认后继续生成。
 
 ```powershell
@@ -136,11 +136,26 @@ python scripts/serve.py --fake
 python scripts/serve.py
 ```
 
+### 前端构建（TypeScript + esbuild）
+
+前端源码在 `frontend/`（TypeScript）；打包产物已入库于 `src/genesis/server/static/chat.js`。
+修改前端后需重新构建：
+
+```powershell
+cd frontend
+npm install            # 首次
+npm run build          # 打包到 ../src/genesis/server/static/chat.js
+npm run typecheck      # tsc --noEmit 类型检查
+npm test               # 纯逻辑单测（node --test，Node >= 23.6）
+```
+
+> 仅运行 Web 服务无需 Node：`chat.js` 已入库，`python scripts/serve.py` 可直接使用。
+
 - 访问 `http://127.0.0.1:8000/` 进入聊天页面；API 文档 `http://127.0.0.1:8000/docs`
 - 聊天页面支持：📎 上传要件定义/模板/规则/既有系统 zip、自然语言指令（`生成概要设计书` / `用中文生成` /
   `现在什么状态？` / `做影响调查` / `运行QA校验`）、影响确认反问（`确认，继续` / `打回`）、结果下载与预览
 - 左侧**会话历史侧边栏**：按会话名/项目列出历史会话，点击即可恢复消息；顶部仅显示会话名（自动取要件定义文件名）
-- **项目级配置**：侧边栏「项目配置」面板可登记模板/做成说明书/规则/既有系统代码库/设计文档目录，绑定项目的会话
+- **项目级配置**：侧边栏项目行 ⚙ 或「＋ 追加项目」打开右侧配置抽屉，登记模板/做成说明书/规则/既有系统代码库/设计文档目录，绑定项目的会话
   只需上传要件定义，其余复用项目配置（`POST /api/projects` 等）；`design_docs_dir` 中的设计文档会作为**影响调查的
   确定性交叉引用证据**（无 LLM、纯字符串匹配）写入影响调查书
 - 主要 API 端点：
diff --git a/_AI_USAGE_LOG.md b/_AI_USAGE_LOG.md
index 46a8106..7baa913 100644
--- a/_AI_USAGE_LOG.md
+++ b/_AI_USAGE_LOG.md
@@ -157,3 +157,5 @@
 | 2026-09-12 17:09 | 反馈迭代 | 侧边栏重构：项目树(项目/其他会话分组)+⚙配置+追加项目(+)+点项目名选中并展开/收起；移除会话历史菜单与底部新建项目按钮及项目管理菜单 | src/genesis/server/static/chat.html; src/genesis/server/static/chat.css; src/genesis/server/static/chat.js; src/genesis/server/static/chat_state.js | deepseek-chat |
 | 2026-09-12 17:09 | 反馈迭代 | 气泡对齐输入框(--composer-gutter)+删除assistant头像点+气泡可铺满；发送后清除空态；F1显式不选项目持久化(explicitNone)+groupSessionsByProject | src/genesis/server/static/chat.js; src/genesis/server/static/chat_state.js; tests/test_chat_state.js | deepseek-chat |
 | 2026-09-12 17:50 | 反馈迭代 | 新增 favicon.svg + chat.html icon link + app.py /favicon.ico 204 + _asset_names + 2 测试；抽屉删除左侧项目列表、宽度抽 --drawer-w:520px、新增蒙版 rgba(0,0,0,.5)(点蒙版关闭带脏守卫)、窄屏隐藏蒙版 | src/genesis/server/app.py; src/genesis/server/static/favicon.svg; src/genesis/server/static/chat.html; src/genesis/server/static/chat.css; src/genesis/server/static/chat.js; tests/test_server_api.py | deepseek-chat |
+| 2026-09-12 18:07 | 架构设计 | 前端迁移 TypeScript + esbuild：frontend/ 工程(src/tests) + 单一 ESM 产物 chat.js(入库) + typecheck/node --test | frontend/**; src/genesis/server/static/chat.js; src/genesis/server/static/chat.html; src/genesis/server/app.py | deepseek-chat |
+| 2026-09-12 18:07 | 测试验证 | Python 测试改指向 /static/chat.js；删除旧 chat_state.js/chat_ws.js 与旧 Node 测试；README 增前端构建说明 | tests/test_frontend_audit_fixes.py; tests/test_progress_e2e.py; README.md | deepseek-chat |
diff --git a/docs/superpowers/plans/2026-09-12-frontend-ts-esbuild.md b/docs/superpowers/plans/2026-09-12-frontend-ts-esbuild.md
new file mode 100644
index 0000000..d3444c3
--- /dev/null
+++ b/docs/superpowers/plans/2026-09-12-frontend-ts-esbuild.md
@@ -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）。