diff --git a/_AI_USAGE_LOG.md b/_AI_USAGE_LOG.md index 08b4a10..0829e3b 100644 --- a/_AI_USAGE_LOG.md +++ b/_AI_USAGE_LOG.md @@ -75,6 +75,7 @@ | 2026-08-11 | Agent 实现 | T9（架构审查整改）：CJK 保守 token 估算（Issue11）。token.py approximate_token_count 重写：新增 _is_cjk_char（CJK 统一表意/扩展A/假名/韩文/兼容/全角六大 Unicode 范围）+ _CJK_TOKENS_PER_CHAR=1.5（旧逻辑 4 字符 1 token 对中文/日文严重低估，裁剪失效致 API 超限）；CJK 字符按 1.5 token/字符，其余仍 4 字符 1 token，最少 1 token；同步 config-design.md token_estimation 注释；新增 4 用例（纯 CJK 保守/ASCII 不回归/混合文本/全角符号）；TDD 验证 RED（（設計）4 字符仅 1 token）→ GREEN（聚焦 11 passed）→ 全量 186 passed 覆盖 100.00%（995 stmts/252 br），fail_under=99 达标 | src/genesis/inference/token.py, tests/test_inference_token.py, docs/config-design.md, _AI_USAGE_LOG.md | deepseek-v4-flash-free | | 2026-08-11 | Agent 实现 | T5（架构审查整改）：删死配置 + 同步文档（Issue5 + OV1）。config.py 删除 QdrantStoreConfig 类与 VectorStoreConfig.qdrant 字段、AppConfig.task_queue.redis_url；同步更新 6 处文档（api-design §1/§4.3/§5.2/§5.3/§6.2：TaskQueue 标注 v1 仅 InMemory、Redis/Valkey 为 v2 预留；rag-layer §9：Storage Adapter 仅 ChromaAdapter、移除切换流程/工厂 qdrant 分支；agent-runtime §3.1/§3.5；design §5.5/§8.4.1；config-design env/app.yaml/rag.yaml/docker compose；web-ui §4.1）+ tests/fixtures/rag.yaml 去 qdrant 段；历史评审记录（design-review/web-ui-review/phase1 plan）保留原样不改写；新增 3 用例（QdrantStoreConfig 已删/vector_store 无 qdrant 字段/task_queue 无 redis_url）+ 同步 2 个既有 qdrant 依赖用例；TDD 验证 RED（三处死配置存在）→ GREEN（聚焦 10 passed）→ 全量 189 passed 覆盖 100.00%（991 stmts/252 br），fail_under=99 达标 | src/genesis/config.py, tests/test_config.py, tests/fixtures/rag.yaml, docs/api-design.md, docs/rag-layer-design.md, docs/agent-runtime-design.md, docs/design.md, docs/config-design.md, docs/web-ui-design.md, _AI_USAGE_LOG.md | deepseek-v4-flash-free | | 2026-08-11 | Agent 实现 | T6+T11（架构审查整改，Lane B）：v1 rerank 精排 + bge-m3 多语言切换（Issue6 + OV2）。config.py 新增 RerankConfig（enabled=True/model=BAAI/bge-reranker-v2-m3/device=cpu）挂入 RagConfig；EmbeddingConfig.model 默认 bge-small-zh-v1.5 → BAAI/bge-m3（实际语料日文）；rag-layer-design.md 新增 §2.3 多语言与日文样本验证、§6.3 Rerank 精排（窗口=RRF top-10、候选≤top_k 跳过、故障降级 RRF 原序），原 §6.3-6.6 顺延 6.4-6.7；选型表/依赖表/manifest/流程图 bge-small-zh → bge-m3；config-design.md embedding 默认 + 新增 rerank 段；design.md §5.5 与 implementation-plan 4.3 同步；新增 tests/test_rag_design_consistency.py 一致性门禁（6 用例：代码默认/fixture 同步/4 文档用 bge-m3+reranker/无 legacy 引用）；TDD 验证 RED（默认模型仍旧+rerank 字段不存在）→ GREEN（聚焦 13 passed）→ 全量 198 passed 覆盖 100.00%（996 stmts/252 br），fail_under=99 达标 | src/genesis/config.py, tests/test_config.py, tests/test_rag_design_consistency.py, tests/fixtures/rag.yaml, docs/rag-layer-design.md, docs/config-design.md, docs/design.md, docs/implementation-plan.md, _AI_USAGE_LOG.md | deepseek-v4-flash-free | +| 2026-08-29 | 架构设计 | 前端画面审计 + 修复方案生成 + plan-eng-review 工程评审：① 静态走查 chat.html/app.py/service.py 定位 6 类问题（currentProject 未声明与 draftProject 分裂、顶栏与真实会话脱节、上传入口与项目模式互斥、预览契约返回 JSON、进度/错误不持久化、死代码）；② 生成方案文档 docs/frontend_audit_plan.md；③ plan-eng-review 评审产出 5 项发现 F1-F5，用户确认三项决策（F1 扩 scope 持久化进度/错误、F2 新会话继承已选项目、F3 抽取 chat_state.js 做 Node 单测），据此定稿方案并附 GSTACK REVIEW REPORT；④ 核实 list_messages 无 type 字段、HTMLResponse 已导入、role 列为 TEXT 可存 progress/error | docs/frontend_audit_plan.md, src/genesis/server/static/chat.html, src/genesis/server/app.py, src/genesis/server/service.py, src/genesis/chat/agent.py, _AI_USAGE_LOG.md | deepseek-v4-flash-free | | 2026-08-11 | Agent 实现 | T12（架构审查整改，P1）：URI 统一 + resolver + 强验证（OV3）。新建 src/genesis/parsers/resolver.py：parse_source_uri（解析 file.xlsx#Sheet!CellRef → SourceRef，格式非法 raise URIError）、provenance_to_uri（Provenance 还原，与 build 互逆）、resolve_source_uri（StructuredSource 内定位真实 CellValue）、validate_source_uris（批量强验证 → ValidationResult(resolved/unresolved)，格式错误或源中不存在一律 unresolved，防 QA#8 编造 URI 作弊）；统一 URI 唯一生成入口 build_source_uri（provenance.py），formatting_detector 经其生成，无散落不一致；新建 tests/test_resolver.py（13 用例：解析/往返/定位/批量验证/防御分支）；同步 design.md §9.2 机制化说明 + §6.8 第五步存在性校验引用；TDD 验证 RED（模块缺失）→ GREEN（聚焦 10 passed）→ 全量 231 passed 覆盖 100.00%（1191 stmts/298 br），fail_under=99 达标 | src/genesis/parsers/resolver.py, tests/test_resolver.py, docs/design.md, _AI_USAGE_LOG.md | deepseek-v4-flash-free | | 2026-08-11 | Agent 实现 | T13（架构审查整改，P1）：黄金集 + 评分器（OV4）。新建 src/genesis/eval/ 包：golden_set.py（GoldenCase/GoldenSet，YAML 加载，samples/ 真实脱敏样本作 input_ref 基线）、scorer.py（ChapterScorer 按 §7.2 指标体系打分）；确定性维度 traceability（resolver 验证 source_uri 可解析率）/placeholder_residue（无 {{...}} 残留）/chapter_completeness（章节覆盖期望集合）；LLM 语义维度经 llm_evaluators 钩子注入（默认中性分，待 Phase5）；新增 tests/test_eval_scorer.py（9 用例：各维度/聚合/钩子/空输入）；tests/fixtures/eval/golden_set.yaml 示例黄金集（2 case）；同步 design.md §7.5 黄金集与评分器机制化说明（定位为 CI 质量门禁）；TDD 验证 RED（模块缺失 + NameError）→ GREEN（聚焦 8 passed）→ 全量 240 passed 覆盖 100.00%（1279 stmts/308 br），fail_under=99 达标 | src/genesis/eval/__init__.py, src/genesis/eval/golden_set.py, src/genesis/eval/scorer.py, tests/test_eval_scorer.py, tests/fixtures/eval/golden_set.yaml, docs/design.md, _AI_USAGE_LOG.md | deepseek-v4-flash-free | | 2026-08-11 | Agent 实现 | T17（架构审查整改，P1）：docx 注入原型提前（OV8）。新建 src/genesis/writer/ 包：docx_injector.py（DocxInjector 用原生 python-docx 实现 §6.6 占位符注入）；Block 模型（paragraph/heading/table）；章节级 {{section:id}} → 替换为内容块 docx 元素序列，行内 {{meta}} → 元信息填充；残留检查：未替换 {{...}} 抛 DocxInjectError（与 §6.6 规范一致）；格式精度：注入 heading 继承模板 Heading 样式、原有内容样式不被破坏；新增 tests/test_docx_injector.py（5 用例：章节/行内替换/残留报错/heading 样式继承/原内容保留）；同步 design.md §6.7 渲染链路 T17 原型说明；TDD 验证 RED（模块缺失）→ GREEN（聚焦 5 passed）→ 全量 245 passed 覆盖 100.00%（1361 stmts/340 br），fail_under=99 达标 | src/genesis/writer/__init__.py, src/genesis/writer/docx_injector.py, tests/test_docx_injector.py, docs/design.md, _AI_USAGE_LOG.md | deepseek-v4-flash-free | @@ -136,3 +137,4 @@ | 2026-08-28 15:33 | 反馈迭代 | Task1 抽屉 +新建项目 加 di-create 醒目样式 + openProjectDrawer 加固(始终渲染列表) | src/genesis/server/static/chat.html | deepseek-chat | | 2026-08-28 15:33 | 反馈迭代 | Task2 删除 header h1，侧边栏品牌名加副标题「概要设计书做成Agent」 | src/genesis/server/static/chat.html | deepseek-chat | | 2026-08-28 15:33 | 反馈迭代 | Task3 折叠态切换按钮移至左下角避免遮挡 logo + 会话列表底部留白 | src/genesis/server/static/chat.html | deepseek-chat | +| 2026-08-29 14:20 | 测试验证 | 前端审计修复（docs/frontend_audit_plan.md，经 plan-eng-review 评审定稿）：静态抽取 chat_state.js 纯函数模块 + Node 单测(11 passed)；chat.html 统一 currentProject→draftProject、新会话继承已选项目(§4.2)、loadProjects 自动绑定、上传区显隐/类型映射/抽屉脏检测改用 GenesisState、loadSession 按 role 渲染 progress/error、加 h1 标题；app.py 预览改 HTMLResponse(返回渲染 HTML 而非 {html} JSON)、新增 /chat_state.js 静态路由、预览缺失返回 404(RESULT_NOT_FOUND)；agent.py 新增 _persist_progress/_store_error 将进度与错误以 role 入库(重载可见)；pytest 新增 test_frontend_audit_fixes.py(5) 并修正 test_server_api 中旧的 JSON 契约断言；全量 pytest 568 passed / 99.06% 达标 | docs/frontend_audit_plan.md; src/genesis/server/static/chat_state.js; tests/test_chat_state.js; src/genesis/server/static/chat.html; src/genesis/server/app.py; src/genesis/chat/agent.py; tests/test_frontend_audit_fixes.py; tests/test_server_api.py; _AI_USAGE_LOG.md | hy3-free | diff --git a/docs/frontend_audit_plan.md b/docs/frontend_audit_plan.md new file mode 100644 index 0000000..d8d8089 --- /dev/null +++ b/docs/frontend_audit_plan.md @@ -0,0 +1,347 @@ +# 前端画面审计与修复方案（Genesis 概要设计书生成 Agent） + +- 文档类型：实施方案（Implementation Plan） +- 关联画面：`src/genesis/server/static/chat.html`（唯一前端单页） +- 关联后端：`src/genesis/server/app.py`、`src/genesis/server/service.py`、`src/genesis/server/store.py`、`src/genesis/chat/agent.py` +- 审计结论来源：对前端单页与后端契约的静态走查 + `plan-eng-review` 工程评审 +- 目标：消除画面状态矛盾、修复前后端契约错误，并使进度/错误消息在会话重载后可见 + +--- + +## 1. 背景与目标 + +前端（`chat.html`）是内嵌于 FastAPI 的单页应用，负责项目切换、会话管理、资料上传与会话对话。 +静态走查发现多处**画面状态互相矛盾**与**前后端契约不一致**，导致用户操作路径不可预期。 + +本方案目标：在不引入新架构依赖的前提下，统一前端项目状态变量、修正上传栏逻辑、修复预览契约、补全进度/错误消息的持久化与历史渲染，并配套前端单元测试与后端契约测试。 + +经 `plan-eng-review` 评审确认的三项决策： +- **F1**：进度/错误消息本就不持久化，重载会话不会出现它们 → 本次**扩 scope 持久化**（而非简单移除渲染）。 +- **F2**：点"+新会话"**继承当前已选项目**（而非始终清空）。 +- **F3**：前端核心状态逻辑**抽取为 `chat_state.js` 模块**并做 Node 单测（真实 TDD）。 + +--- + +## 2. 现状根因分析 + +### 2.1 核心缺陷：项目状态变量分裂 +`currentProject` 在 14 处被使用（chat.html:545,547,549,558,562,565,574,697,718,720,738,740…）， +但顶部 `let` 声明块（456–464）**只声明了 `draftProject`，从未声明 `currentProject`**。 +非严格模式下它退化为隐式全局变量，初始值为 `undefined`。 + +注释 `line 457`：`draftProject = null; // 下一空白会话将绑定/已绑的项目（原 currentProject）` +说明这是一次**未完成的重命名重构**遗留。 + +后果链： +1. `loadProjects` 启动自动绑定 `if (currentProject === null …)`（line 545）因 `undefined !== null` 永不触发 → 首个项目永不自动选中。 +2. `updateUploadBar` 用 `currentProject`（line 738），但建会话/上传用 `draftProject`/`activeProject`（800,802,864）→ UI 状态与实际上传/绑定项目不一致。 +3. `newSession` 无条件 `draftProject = null`（line 761），而顶栏 `currentProject` 未被同步 → 选了项目再点"新会话"，顶栏显示已选项目、新会话却未绑定、侧边栏会话列表被清空（497）。 + +### 2.2 顶栏项目与真实会话脱节 +- 顶栏 `psName` 显示 `currentProject`，`sid-badge` 显示会话真实项目，二者可不一致。 +- 上传提示（line 740）用 `currentProject`，而实际上传用 `activeProject/draftProject` → 提示可能显示错误项目名。 + +### 2.3 上传入口与项目模式互斥、标签误导 +- 上传栏有 5 种类型（requirements/template/write_instruction/rules/existing_system，部分标"（必需）"）， + 但一旦 `activeProject || currentProject` 为真即隐藏整个下拉并强制 `requirements`（738–744, 864）→ 其余 4 种上传入口消失，与标签矛盾。 +- 项目配置抽屉用"目录路径"配置 rules/code/design，上传栏用"文件"——两套输入模型互相隐藏、不一致。 + +### 2.4 前后端契约错误：预览返回 JSON +- 前端 `send()` 预览链接 `href="/api/sessions/{sid}/result/preview"`（line 827）期望打开 HTML； +- 后端 `result_preview`（app.py:269–272）返回 `{"html": …}`，浏览器直接显示原始 JSON 文本而非文档预览。 +- `service.result_preview` 本身返回的是 HTML 字符串（service.py:291–306），被错误包裹了一层 JSON。 +- 已确认 `HTMLResponse` 已在 app.py:18 导入，无需重复导入。 + +### 2.5 进度/错误消息不持久化（评审新增，F1） +- `chat_agent.handle_message` 仅通过 `store.add_message` 持久化 `user` 与 `assistant` 消息（agent.py:24,35,55,63…）。 +- `progress` 列表仅作为 API 响应返回，**从不写入存储**；错误回复以 `assistant` 角色入库。 +- 结果：`list_messages` 返回结构为 `{role, content, action, created_at}`，**无 `type` 字段**，历史中永不出现 `progress`/`error`。 +- 因此重载会话时进度/错误既无数据也无样式——这是本次要补的缺口。 + +### 2.6 次要/死代码 +- CSS `header h1`（line 156）已定义，但 `header` 标记中无 `

`，顶栏无标题。 +- Esc 时总是 `lastTriggerEl.focus()`（857），即使未打开任何面板也会聚焦（轻微）。 + +--- + +## 3. 方案概述 + +采用**最小且完整的修复**（不重写前端，不新增运行期依赖）： + +1. 统一项目状态变量：删除 `currentProject`，全量改用 `draftProject`；切换/保存/载入/新建会话均同步 `draftProject`。 +2. 修正启动自动绑定判断：`if (draftProject === null && projects.length)`。 +3. `newSession` 保留当前已选项目（F2），仅在显式"不选择项目"时清空。 +4. `updateUploadBar` 与上传逻辑统一以 `draftProject`（= 当前/待建会话项目）为准。 +5. 后端 `result_preview` 改为 `HTMLResponse`（保留 `result_preview` 返回的 HTML 字符串）。 +6. 扩展持久化（F1）：`chat_agent` 将 `progress` 条目以 `role='progress'` 入库、错误回复以 `role='error'` 入库；`loadSession` 按 `role` 渲染进度/错误样式。 +7. 抽取核心状态逻辑到 `chat_state.js`（F3），由 chat.html 引入，配套 Node 单测。 +8. （可选）`header` 补 `

` 标题。 + +--- + +## 4. 详细改动（文件/函数级） + +### 4.1 chat.html — 变量统一（合并原 §4.3） +- 删除所有 `currentProject` 引用，替换为 `draftProject`，逐处核对语义（注意 `activeProject` 语义不同，不可混淆）。 +- 受影响位置（逐个替换，保持语义）： + - line 545：`if (draftProject === null && projects.length > 0) draftProject = projects[0].name;` + - line 547：`else if (draftProject && !projects.find(p => p.name === draftProject))` + - line 549：`draftProject = projects.length > 0 ? projects[0].name : null;` + - line 558：`psName.textContent = draftProject || '未选择';` + - line 562：`(draftProject === null ? ' active' : '')` + - line 565：`(p.name === draftProject ? ' active' : '')` + - line 574：`draftProject = it.dataset.name === '' ? null : it.dataset.name;` + - line 697：`draftProject = cfg.name;`（saveDrawerProject） + - line 718：`if (draftProject === drawerSelected)` + - line 720：`draftProject = null;` + - line 738：`if (activeProject || draftProject)` + - line 740：提示文案用 `activeProject || draftProject` + +### 4.2 chat.html — newSession 保留项目（F2） +现状（line 760–769）： +```js +async function newSession() { + sid = null; + activeProject = null; + draftProject = null; // ← 问题：无条件清空 + ... +} +``` +改为：保留 `draftProject`（当前顶栏已选项目），使新会话继承项目绑定： +```js +async function newSession() { + sid = null; + activeProject = null; + // 保留 draftProject（当前顶栏已选项目），使新会话继承项目绑定 + badge.textContent = '未创建会话'; + updateUploadBar(); + await refreshSessions(); + renderEmptyOrWelcome(); +} +``` +"不选择项目"入口：在 `renderProjectSwitcher` 的"不选择项目"点击处理中，调用 `newSession` 前先 `draftProject = null`，从而显式获得无项目会话。 + +### 4.3 app.py — 预览契约修复 +现状（269–272）： +```python +@app.get("/api/sessions/{sid}/result/preview") +def result_preview(sid: str): + html = service.result_preview(sid) + return {"html": html} +``` +改为（HTMLResponse 已在 app.py:18 导入）： +```python +@app.get("/api/sessions/{sid}/result/preview", response_class=HTMLResponse) +def result_preview(sid: str): + html = service.result_preview(sid) + return HTMLResponse(html) +``` + +### 4.4 新增文件 `src/genesis/server/static/chat_state.js`（F3） +UMD 形式，浏览器挂 `window.GenesisState`、Node 可 `require`，导出纯函数（不触碰 DOM）： +```js +(function (root, factory) { + const api = factory(); + if (typeof module !== 'undefined' && module.exports) module.exports = api; + else root.GenesisState = api; +})(typeof self !== 'undefined' ? self : this, function () { + function autoBindProject(draftProject, projects) { + if (draftProject === null && projects.length > 0) return projects[0].name; + if (draftProject && !projects.find(p => p.name === draftProject)) + return projects.length > 0 ? projects[0].name : null; + return draftProject; + } + function shouldHideUploadSelect(activeProject, draftProject) { + return Boolean(activeProject || draftProject); + } + function resolveUploadType(activeProject, draftProject, selectValue) { + return (activeProject || draftProject) ? 'requirements' : selectValue; + } + function computeDrawerSnapshot(fields) { + return fields.map(f => (f || '').trim()).join('\u0001'); + } + function isDrawerDirty(snapshotNow, saved) { + return snapshotNow !== saved; + } + function buildWelcome(draftProject) { + if (draftProject === null) return '请新建项目或者选择项目'; + return '你好！我是 Genesis 概要设计书生成 Agent。请先上传要件定义 xlsx' + + '（模板/规则/代码库已由项目「' + draftProject + '」提供），然后告诉我：' + + '「生成概要设计书」/「用中文生成」/「现在什么状态？」'; + } + return { autoBindProject, shouldHideUploadSelect, resolveUploadType, + computeDrawerSnapshot, isDrawerDirty, buildWelcome }; +}); +``` +chat.html 改动： +- `` 后或 body 末尾增加 ``（普通脚本，先于主脚本执行）。 +- `loadProjects` 的自动绑定改用 `draftProject = GenesisState.autoBindProject(draftProject, projects);` +- `updateUploadBar` 的判定改用 `GenesisState.shouldHideUploadSelect(activeProject, draftProject)`。 +- 上传按钮 `ft` 判定改用 `GenesisState.resolveUploadType(activeProject, draftProject, sel.value)`。 +- `drawerSnapshotNow` 改为调用 `GenesisState.computeDrawerSnapshot([...7个字段值])`；`isDrawerDirty` 改用 `GenesisState.isDrawerDirty(...)`。 +- `renderEmptyOrWelcome` 的文案改用 `GenesisState.buildWelcome(draftProject)`。 + +### 4.5 app.py — 提供 chat_state.js 静态路由 +```python +@app.get("/chat_state.js", response_class=HTMLResponse) +def chat_state_js(): + p = static_dir / "chat_state.js" + if not p.exists(): + raise _error(404, "NOT_FOUND", "chat_state.js 不存在") + return FileResponse(p, media_type="application/javascript") +``` + +### 4.6 进度/错误消息持久化（F1） +**后端 `chat/agent.py`：** +- 新增私有方法 `_persist_progress(session_id, progress)`： + ```python + def _persist_progress(self, session_id, progress): + for item in progress: + self.store.add_message( + session_id, "progress", + f"{item.get('step', '')}: {item.get('detail', '')}", + action=item.get("status"), + ) + ``` +- 所有 `return {"reply": ..., "progress": progress, ...}` 前调用 `self._persist_progress(session_id, progress)`。 +- 错误回复（如 `reply = f"解析失败：{e}"` 等）原以 `role="assistant"` 入库，改为 `role="error"`（保留 `action` 不变），便于前端区分样式。可加私有方法 `_store_error(session_id, reply, action)`。 +- `store.add_message` 的 `role` 列本为 `TEXT`，已可存 `'progress'`/`'error'`，**无需改表结构**。 + +**前端 `chat.html` `loadSession`（约 782–784）：** +```js +const roleMap = { user: 'user', progress: 'progress', error: 'error' }; +const role = roleMap[m.role] || 'assistant'; +addMsg(role, esc(m.content)); +``` +（历史中既有 `user`/`assistant` 消息回退为 `assistant`，向后兼容。） + +### 4.7 chat.html — 顶栏标题（可选） +在 `header`（369–380）中 `proj-switcher` 之前插入： +```html +

Genesis 概要设计书生成

+``` + +--- + +## 5. 数据流（修复后） + +``` +启动 + └─ loadProjects(): draftProject = autoBindProject(draftProject, projects) + │ （draftProject===null 且有项目 → 首项；draftProject 指向已删项目 → 回退首项） + └─ renderProjectSwitcher / updateUploadBar / refreshSessions 全部以 draftProject 为准 + +选/建项目 + └─ 顶栏切换 → draftProject = 项目名（或 null） + └─ 抽屉保存 → draftProject = 新建/编辑后的项目名 + +新建会话(newSession) + └─ 继承 draftProject（不清空）（F2） + └─ 首条消息 send() → POST /api/sessions {project: draftProject} + └─ activeProject = draftProject + +上传要件定义 + └─ ft = resolveUploadType(activeProject, draftProject, sel.value) + │ （绑定项目时恒为 'requirements'，下拉隐藏，提示"仅需上传要件定义"） + └─ 未绑定项目时显示 5 种类型下拉 + +生成流程 + └─ chat_agent 将 progress 条目以 role='progress'、错误以 role='error' 持久化（F1） + └─ send() 返回 done/writing → 渲染 下载/预览/影响调查书/QA报告 链接 + └─ 预览链接 → GET /api/sessions/{sid}/result/preview（返回 HTML，新标签页正常渲染） + +重载会话 + └─ loadSession 按 m.role 渲染 user/progress/error/assistant，进度与错误可见（F1） +``` + +--- + +## 6. 边界与异常处理 + +- **无项目场景**：`draftProject === null` 时，顶栏"未选择"、侧边栏会话列表清空、上传栏显示完整 5 种类型、欢迎语进入"请新建项目"。 +- **删除当前会话**：`deleteSession` 命中当前 `sid` → `newSession()`，继承 `draftProject`，不丢失项目上下文。 +- **删除已绑定项目**：`deleteDrawerProject` 将 `draftProject` 置 null（与"不选择项目"等价），UI 回到无项目态。 +- **抽屉未保存守卫**：`guardDrawerDirty()` 在切换/关闭前拦截，已有，保持不变。 +- **预览无结果**：后端 `result_preview` 在 `result_path` 不存在时抛 `ServiceStepError` → 前端 `send()` 捕获为 error 消息，不会渲染空链接。 +- **历史消息缺字段/旧数据**：`role` 非 user/progress/error 时回退 `assistant`；进度/错误旧会话（升级前）无此类行，不影响渲染。 +- **chat_state.js 加载失败**：若 `/chat_state.js` 404，主脚本调用 `GenesisState.xxx` 会抛错。防护：主脚本顶部加 `const S = (typeof GenesisState !== 'undefined') ? GenesisState : null;` 并在使用处判空回退到内联实现，或确保路由必存在（推荐后者，部署时文件随包提供）。 + +--- + +## 7. 测试策略（TDD） + +### 7.1 前端核心逻辑单测（Node，F3） +- 文件：`tests/test_chat_state.js`（Node `node:test` + `node:assert`），`require('../src/genesis/server/static/chat_state.js')`。 +- 用例： + 1. `autoBindProject(null, [{name:'A'},{name:'B'}])` → `'A'`（启动自动绑定首项）。 + 2. `autoBindProject('X', [{name:'A'}])` → `'A'`（指向已删项目回退首项）。 + 3. `autoBindProject('A', [{name:'A'}])` → `'A'`（保持不变）。 + 4. `shouldHideUploadSelect(null, null)` → `false`；`shouldHideUploadSelect(null, 'A')` → `true`；`shouldHideUploadSelect('A', null)` → `true`。 + 5. `resolveUploadType(null, 'A', 'template')` → `'requirements'`；`resolveUploadType(null, null, 'template')` → `'template'`。 + 6. `computeDrawerSnapshot([' a ','b'])` → `'a\u0001b'`；`isDrawerDirty('x','y')` → `true`，相等 → `false`。 + 7. `buildWelcome(null)` 含"请新建项目"；`buildWelcome('A')` 含"项目「A」"。 + +### 7.2 后端契约（pytest） +- `test_result_preview_returns_html`：请求 `GET /api/sessions/{sid}/result/preview`，断言 `content-type` 含 `text/html` 且响应体以 `` 开头（非 `{"html":`）。 +- `test_result_preview_missing`：无结果文档时返回 404（`RESULT_NOT_FOUND`）。 +- `test_persist_progress_and_error`：用 `TestClient` 走 建会话→上传要件定义→`generate`（fake engine），断言 `list_messages` 含 `role='progress'` 的条目；另测一个错误路径（如无模板时 generate）断言含 `role='error'`。 + +### 7.3 集成（端到端冒烟，pytest + TestClient） +- 建会话→上传要件定义（fake 样本）→`start-parse`→`confirm-parse`→`generate`（fake engine）→`result/preview` 返回 HTML。 +- 断言 preview 链接可达且为 HTML；断言历史消息含 progress 角色。 + +### 7.4 运行要求 +- 7.1 需要 Node 运行时；若 CI 无 Node，则该层测试跳过并在文档标注（不阻塞主流程）。 + +--- + +## 8. 性能与风险 + +- 改动均为客户端状态变量、单端点响应类型、少量消息持久化，无新增计算/网络开销。 +- 风险点：全局替换 `currentProject`→`draftProject` 需逐处核对语义，避免误改 `activeProject`。 +- 持久化进度消息会增加少量 DB 写入（每条进度 1 行），规模小，可忽略。 +- 回滚：纯前端 + 单端点 + 消息角色扩展（TEXT 列兼容），可逐文件 revert，不影响表结构。 + +--- + +## 9. 验收标准 + +1. 启动有项目时顶栏自动显示项目名，且欢迎语进入"已选项目"分支。 +2. 选/建项目后新建会话，会话正确绑定该项目，侧边栏列表按该项目过滤；点"+新会话"继承已选项目（F2）。 +3. 上传栏在绑定项目时仅显示要件定义入口；无项目时显示全部 5 种。 +4. 点击"预览"在新标签页渲染文档 HTML（不再显示 JSON）。 +5. 重新载入会话时进度/错误消息按样式正确显示（F1）。 +6. 上述 7.1–7.3 测试全部通过。 + +--- + +## 10. 后续增强（不在本次范围，F5） + +- 跨刷新持久化"选中的项目"（当前仅 session id 持久化，启动恒自动绑首项）。 +- 上传栏在已绑定项目时，将"模板/规则/代码库由项目提供"的说明文案进一步细化，消除"（必需）"标签的歧义。 + +--- + +## GSTACK REVIEW REPORT + +- 评审技能：plan-eng-review +- 评审对象：docs/frontend_audit_plan.md（本文件） +- 评审结论：DONE_WITH_CONCERNS（已解决全部阻塞项，遗留项已降级为后续增强） + +### 评审发现与处置 +| 编号 | 发现 | 严重度 | 处置 | +|------|------|--------|------| +| F1 | 进度/错误消息不持久化，原 §4.5 基于错误前提 | 严重 | 已扩 scope：§4.6 持久化 role='progress'/'error'，loadSession 按 role 渲染 | +| F2 | newSession 是否继承项目为产品决策 | 中 | 用户确认：继承已选项目（§4.2） | +| F3 | 前端测试策略含糊、不可执行 | 中 | 用户确认：抽取 chat_state.js 模块 + Node 单测（§4.4、§7.1） | +| F4 | §4.3 与 §4.1 重叠 | 轻微 | 已合并（§4.1 内含 updateUploadBar 统一） | +| F5 | 启动自动绑首项、选中项目不跨刷新持久化 | 轻微 | 降级为后续增强（§10） | + +### 已确认的前提（评审中核实） +- `list_messages` 返回 `{role, content, action, created_at}`，无 `type` 字段（store.py:119-122）。 +- `HTMLResponse` 已在 app.py:18 导入，§4.3 无需重复导入。 +- `store.add_message` 的 `role` 为 TEXT 列，可直接存 'progress'/'error'，无需改表。 + +### 剩余关注 +- 7.1 需 Node 运行时；若目标部署环境无 Node，前端单测层需在 CI 中跳过并标注（不影响后端 pytest）。 +- chat_state.js 必须由 app.py 正确以 `/chat_state.js` 提供，否则主脚本依赖缺失；测试需覆盖该路由 200。 diff --git a/src/genesis/chat/agent.py b/src/genesis/chat/agent.py index 327eb68..2fed88e 100644 --- a/src/genesis/chat/agent.py +++ b/src/genesis/chat/agent.py @@ -32,11 +32,25 @@ class ChatAgent: intent = self._parse_intent(session_id, content, rec) result = self._dispatch(session_id, intent, progress) reply, status = result["reply"], result["status"] + self._persist_progress(session_id, result["progress"]) self.store.add_message(session_id, "assistant", reply, action=intent.action) return {"reply": reply, "progress": result["progress"], "status": status} # ---------- 意图解析 ---------- + def _persist_progress(self, session_id, progress): + """将流程进度条目持久化为 role='progress' 消息，使重载会话可见（§4.6）。""" + for item in progress: + self.store.add_message( + session_id, "progress", + f"{item.get('step', '')}: {item.get('detail', '')}", + action=item.get("status"), + ) + + def _store_error(self, session_id, reply, action): + """错误回复以 role='error' 持久化，便于前端区分样式（§4.6）。""" + self.store.add_message(session_id, "error", reply, action=action) + def _parse_intent(self, session_id, content, rec): if self.fake: return parse_intent_fake(content) @@ -53,6 +67,7 @@ class ChatAgent: self.store.update_session(session_id, pending_intent="") reply = "已打回影响调查。可以回复「重新影响调查」或「开始解析」重来。" self.store.add_message(session_id, "assistant", reply, action="reject") + self._persist_progress(session_id, progress) return {"reply": reply, "progress": progress, "status": "impact_running"} if intent.action == "confirm": try: @@ -60,7 +75,8 @@ class ChatAgent: progress.append({"step": "impact", "status": "ok", "detail": "影响调查已确认"}) except Exception as e: # noqa: BLE001 reply = f"影响确认失败：{e}" - self.store.add_message(session_id, "assistant", reply, action="confirm") + self._store_error(session_id, reply, "confirm") + self._persist_progress(session_id, progress) return {"reply": reply, "progress": progress, "status": "awaiting_impact_confirm"} pending = self.store.get_session(session_id).pending_intent if pending == "generate": @@ -68,9 +84,11 @@ class ChatAgent: return self._run_generate(session_id, self.store.get_session(session_id), progress) reply = "已确认影响调查。可以回复「生成概要设计书」继续。" self.store.add_message(session_id, "assistant", reply, action="confirm") + self._persist_progress(session_id, progress) return {"reply": reply, "progress": progress, "status": "writing"} reply = "影响调查结果待确认，请回复「确认，继续」或「打回」。" self.store.add_message(session_id, "assistant", reply, action="unknown") + self._persist_progress(session_id, progress) return {"reply": reply, "progress": progress, "status": "awaiting_impact_confirm"} # ---------- 分发 ---------- @@ -108,7 +126,7 @@ class ChatAgent: rec = self._parse_and_confirm(session_id, progress) except Exception as e: # noqa: BLE001 reply = f"解析失败：{e}" - self.store.add_message(session_id, "assistant", reply, action="generate") + self._store_error(session_id, reply, "generate") return {"reply": reply, "progress": progress, "status": rec.status} if rec.status == "writing": # 无既有系统 → 直接生成 @@ -145,7 +163,7 @@ class ChatAgent: rec = self._parse_and_confirm(session_id, progress) except Exception as e: # noqa: BLE001 reply = f"解析失败：{e}" - self.store.add_message(session_id, "assistant", reply, action="parse") + self._store_error(session_id, reply, "parse") return {"reply": reply, "progress": progress, "status": rec.status} if rec.status == "awaiting_impact_confirm": reply = f"解析与影响调查已完成：{self._impact_brief(rec)}。是否确认？（回复「确认，继续」）" @@ -167,7 +185,7 @@ class ChatAgent: rec = self._parse_and_confirm(session_id, progress) except Exception as e: # noqa: BLE001 reply = f"解析失败：{e}" - self.store.add_message(session_id, "assistant", reply, action="impact") + self._store_error(session_id, reply, "impact") return {"reply": reply, "progress": progress, "status": rec.status} # _parse_and_confirm 已自动跑影响 → 直接返回反问 if rec.status == "awaiting_impact_confirm": @@ -194,7 +212,7 @@ class ChatAgent: rec = self.service.run_generate(session_id, output_language=output_language) except Exception as e: # noqa: BLE001 reply = f"生成失败：{e}" - self.store.add_message(session_id, "assistant", reply, action="generate") + self._store_error(session_id, reply, "generate") return {"reply": reply, "progress": progress, "status": rec.status} progress.append({"step": "generate", "status": "ok", "detail": "概要设计书已生成"}) try: @@ -226,7 +244,7 @@ class ChatAgent: except Exception as e: # noqa: BLE001 rec = self.store.get_session(session_id) reply = f"QA 未执行：{e}" - self.store.add_message(session_id, "assistant", reply, action="qa") + self._store_error(session_id, reply, "qa") return {"reply": reply, "progress": progress, "status": rec.status} def _status_reply(self, rec, progress): diff --git a/src/genesis/server/app.py b/src/genesis/server/app.py index bb53563..7db5d7c 100644 --- a/src/genesis/server/app.py +++ b/src/genesis/server/app.py @@ -110,6 +110,13 @@ def create_app( def index(): return chat_html + @app.get("/chat_state.js") + def chat_state_js(): + p = static_dir / "chat_state.js" + if not p.exists(): + raise _error(404, "NOT_FOUND", "chat_state.js 不存在") + return FileResponse(p, media_type="application/javascript") + # ---------- 项目配置 ---------- @app.post("/api/projects") @@ -266,10 +273,13 @@ def create_app( # ---------- 结果 ---------- - @app.get("/api/sessions/{sid}/result/preview") + @app.get("/api/sessions/{sid}/result/preview", response_class=HTMLResponse) def result_preview(sid: str): - html = service.result_preview(sid) - return {"html": html} + try: + html = service.result_preview(sid) + except ServiceStepError: + raise _error(404, "RESULT_NOT_FOUND", "结果文档不存在") + return HTMLResponse(html) @app.get("/api/sessions/{sid}/result/download") def result_download(sid: str): diff --git a/src/genesis/server/static/chat.html b/src/genesis/server/static/chat.html index 342ada2..f271d2f 100644 --- a/src/genesis/server/static/chat.html +++ b/src/genesis/server/static/chat.html @@ -367,6 +367,7 @@
+

Genesis 概要设计书生成

+