diff --git a/.superpowers/sdd/progress.md b/.superpowers/sdd/progress.md index a7aeebd..efa3557 100644 --- a/.superpowers/sdd/progress.md +++ b/.superpowers/sdd/progress.md @@ -20,3 +20,6 @@ M3.1 IE Task 4: complete (commit per git log, review clean; Minor backlog: retry M3.1 IE Task 4: complete (commit add7b15, review clean; Minor: 5xx chain message redundancy, test comment mismatch 0.01, un-typed 3xx/malformed-JSON JSONDecodeError passthrough - leave to Task5/engine fold) M3.1 IE Task 5: complete (commit 8bc5e5e, review clean 3 deviations all justified; Minor: for-loop var name in failed chat, test import hygiene, raw-template leak known tradeoff, api-design patch +source column slight overreach) M3.1 IE final review: base 2fbff07..8bc5e5e -> With fixes; fixed 2 Important (LLMResponseError wrap for malformed 2xx, explicit 2xx check re 3xx); Issue3 chat_structured no model fallback confirmed intentional per plan L1142 (v1 single-model, prod passes explicit model); Minors logged (LLMResponseError now live, truncation in chat_structured, prompt renderer duplicate import, prompts-dir load not v1, no context manager, last-error only) +RETRO 2026-08-09: snapshot saved (.superpowers/sdd/retro-2026-08-09.json); first recorded for this workspace +M3.1 backlog clean (cb2deda): chat_structured truncation, engine test import hygiene, client context manager; remaining backlog: [none critical] +WEB UI REVIEW 2026-08-09 (docs/web-ui-design-review-v1.1.md): v1.0→v1.1, 7 findings all fixed (F1 write_instruction file_type + api §2.2, F2 TaskQueue abstraction, F3 settings page, F4 preview path, F5 conflict card, F6 history page, F7 a11y); synced design.md §8 mirror diff --git a/_AI_USAGE_LOG.md b/_AI_USAGE_LOG.md index 906513a..78aa5f5 100644 --- a/_AI_USAGE_LOG.md +++ b/_AI_USAGE_LOG.md @@ -51,3 +51,4 @@ (End of file - total 50 lines) | 2026-08-09 10:50 | 反馈迭代 | 里程碑3.1 backlog 清理（retro 3 项）：① chat_structured 增加 token 超限检测（渲染后估算超限→truncate_cb→重渲染，与 chat 流程一致）TDD RED→GREEN 新增 test_chat_structured_truncation_callback_triggered；② 清理 test_inference_engine.py 未用导入（pytest/json/ChatMessage）；③ HttpLLMClient 增加上下文管理器（__enter__/__exit__ 退出时关闭底层 httpx.Client 释放连接）TDD 新增 test_client_context_manager_closes_transport；pytest 全量 119 passed 覆盖 100.00%，fail_under=99 达标；提交见 git log | src/genesis/inference/engine.py, src/genesis/inference/client.py, tests/test_inference_engine.py, tests/test_inference_client.py, _AI_USAGE_LOG.md | deepseek-v4-flash-free | +| 2026-08-09 11:20 | 反馈迭代 | Web UI 设计评审（v1.0→v1.1，7 项发现全修）：以大赛手册+api-design 为权威基准审查 web-ui-design.md——F1 上传区补「概要设计做成说明书」独立 write_instruction file_type（api-design §2.2 连带扩展）+ 命名统一；F2 §4.1 任务队列 Redis 写死→抽象 TaskQueue（InMemory 默认/Redis/Valkey 可选）；F3 新增设置页 §3.6；F4 预览路径改 ContentBlock→chapter_html+docx；F5 生成页新增规则冲突浮动卡片（WS conflict_pending→conflicts/{id}/resolve）；F6 新增会话历史页 §3.7；F7 新增 §7 无障碍与设计规范。同步 design.md §8 简版镜像（上传区/预览/队列/导航历史/冲突卡片/设置历史简版//history 命令）；产出评审报告 docs/web-ui-design-review-v1.1.md；docs/design.md、docs/api-design.md 连带修订 | docs/web-ui-design.md, docs/web-ui-design-review-v1.1.md, docs/api-design.md, docs/design.md, _AI_USAGE_LOG.md | deepseek-v4-flash-free | diff --git a/docs/api-design.md b/docs/api-design.md index 336c0d5..025ce90 100644 --- a/docs/api-design.md +++ b/docs/api-design.md @@ -55,7 +55,14 @@ FastAPI Orchestrator（单进程，默认） | Method | Path | 说明 | 请求体 | 响应 | 触发状态转移 | |--------|------|------|--------|------|-------------| -| POST | `/api/sessions/{id}/files` | 上传文件（multipart） | `file` + `file_type`（requirements/template/rules/existing_system） | `{file_id, file_name, size}` | `uploading` 保持 | +| POST | `/api/sessions/{id}/files` | 上传文件（multipart） | `file` + `file_type`（`requirements`/`template`/`write_instruction`/`rules`/`existing_system`） | `{file_id, file_name, size}` | `uploading` 保持 | + +> `file_type` 取值说明（v1.1 修订，随 web-ui-design §3.1 补齐大赛输入资料）： +> - `requirements` — 要件定义 Excel（核心数据源） +> - `template` — 概要设计模板 docx（输出结构/样式） +> - `write_instruction` — 概要设计做成说明书 docx（各章作成指引；RAG 归类 Type A 写入规则，Parser 解析） +> - `rules` — 记入规则 / 图表规则等规则文档（可多个） +> - `existing_system` — 现系统源码或既有设计书（追加/改修场景） | POST | `/api/sessions/{id}/start-parse` | 开始解析（全部文件上传完成后） | `{}` | `{task_id}`（解析异步执行） | `uploading → parsing` | | GET | `/api/sessions/{id}/parse-result` | 获取解析结果 | — | `{structured_summary, sheets, template_sections}` | 只读 | diff --git a/docs/design.md b/docs/design.md index 1ab53d2..819a411 100644 --- a/docs/design.md +++ b/docs/design.md @@ -1027,7 +1027,7 @@ QA 输出: ``` ┌─────────────────────────────────────────────────────────────┐ -│ Genesis [上传] [解析] [影响调查] [生成] [结果] [设置] │ ← 顶部导航 +│ Genesis [上传] [解析] [影响调查] [生成] [结果] [历史] [设置] │ ← 顶部导航 ├─────────────────────────────────────────────────────────────┤ │ │ │ ┌─ 对话区域 ──────────────────────────────────────────┐ │ @@ -1070,9 +1070,9 @@ QA 输出: │ │ .docx (Word) │ │ │ └─────────────────────────────────────┘ │ │ │ -│ 📁 写入规则 (推荐, 可多个) │ +│ 📁 记入规则 (推荐, 可多个) │ │ 📁 图表规则 (推荐) │ -│ 📁 做成说明书 (推荐) │ +│ 📁 做成说明书 (推荐, 独立类型) │ │ │ │ 📁 现有系统文件 (任意, 追加/改修场景使用) │ │ │ @@ -1085,7 +1085,7 @@ QA 输出: 上传规则： - 要件定义文件至少一个 - 模板文件必须是一个 .docx -- 规则文档可多个，也可零个（规则手册已存在时） +- 做成说明书 / 记入规则 / 图表规则 均可多个，也可零个（规则手册已存在时）；做成说明书使用独立 `file_type=write_instruction`（api-design §2.2） - 现系统文件仅在追加/改修场景时需要 - 文件大小限制：最大100MB - 支持拖拽上传、点击上传、取消上传 @@ -1181,10 +1181,25 @@ QA 输出: │ 适用规则: 写入规则_v3 │ │ │ │ [中途中断] [查看日志] │ +│ │ +│ ┌─ 规则冲突 (浮动卡片) ───────────────────┐ │ +│ │ ⚠ 检测到规则冲突（DB设计章） │ │ +│ │ 记入规则 2.3「表头仅加粗」 │ │ +│ │ 图表规则 2.3「表头加粗+下划线」 │ │ +│ │ [采用「记入规则」] [采用「图表规则」] [标注] │ │ +│ └──────────────────────────────────────┘ │ └─────────────────────────────────────────────┘ ``` -交互说明：用户可保持此画面打开同时进行其他工作。生成完成时通知。选择中断时，已完成的章节保留。 +交互说明：用户可保持此画面打开同时进行其他工作。生成完成时通知。选择中断时，已完成的章节保留。规则冲突由 WS 事件 `conflict_pending` 触发浮动卡片，决策后调用 `/api/rules/conflicts/{id}/resolve` 继续生成。 + +#### 页面6: 设置 +> +> 简版：规则手册版本管理（versions / 更新 / 回滚）+ LLM 配置只读摘要（脱敏）。见 `docs/web-ui-design.md` §3.6。 + +#### 页面7: 会话历史 +> +> 简版：会话列表（恢复 / 删除 / 新建），对应 `GET /api/sessions`。见 `docs/web-ui-design.md` §3.7。 #### 页面5: 结果预览与下载 @@ -1199,7 +1214,7 @@ QA 输出: │ └────────────────────────────────────────┘ │ │ │ │ ┌─ 预览 ──────────────────────────┐ │ -│ │ (docx → HTML → 浏览器内渲染) │ │ +│ │ (ContentBlock → HTML 渲染) │ │ │ │ [章标题] [段落] [表] ... │ │ │ └────────────────────────────────────────┘ │ │ │ @@ -1218,7 +1233,7 @@ QA 输出: #### 8.4.1 任务管理 ``` -Task Queue (Redis) +TaskQueue（抽象接口，默认 InMemoryQueue，生产可切 Redis/Valkey） ├── task:generate-chapter-1 │ status: completed │ result: {chapter: "功能一览", html: "...", time_ms: 23000} @@ -1305,6 +1320,7 @@ CREATE TABLE session_files ( /impact → 跳转到影响调查画面 /generate → 跳转到生成执行画面 /result → 跳转到结果画面 +/history → 跳转到历史会话页 /settings → 跳转到设置画面 /status → 显示当前生成任务的状态 /cancel → 取消当前生成 diff --git a/docs/web-ui-design-review-v1.1.md b/docs/web-ui-design-review-v1.1.md new file mode 100644 index 0000000..b58954b --- /dev/null +++ b/docs/web-ui-design-review-v1.1.md @@ -0,0 +1,121 @@ +# Web UI 设计评审报告（v1.0 → v1.1） + +> 版本: v1.1 | 日期: 2026-08-09 | 状态: 评审完成 + 修订已完成 +> +> 评审对象：`docs/web-ui-design.md` v1.0 +> 权威基准：大赛手册（`docs/design.md` §3.3 输入资料清单 / `docs/sample-spec.md`）+ 后端接口（`docs/api-design.md`）+ 编排（`docs/agent-runtime-design.md`） +> 评审视角：跨文档一致性 + 设计质量（无障碍 / AI-slop / UX） +> 严重级：**P0=大赛基准缺陷** **P1=接口/设计缺陷** **P2=建议** + +--- + +## 评审结论摘要 + +| 项 | 发现 | 严重度 | 处置 | +|----|------|--------|------| +| F1 | 上传区缺「概要设计做成说明书」+ 与 design.md §8 命名不一致 | P0 | 已修：补充独立 `write_instruction` 类型（web-ui §3.1、design §8、api-design §2.2） | +| F2 | §4.1 任务队列写死 Redis，与「抽象 TaskQueue + InMemory 默认」决策冲突 | P1 | 已修：改为抽象接口表述 | +| F3 | 设置页缺失（导航/斜杠命令存在，但无页面设计） | P1 | 已修：新增 §3.6 设置页 | +| F4 | §3.5 预览路径标注「docx → HTML」，与 ContentBlock 管线不一致 | P1 | 已修：改为 ContentBlock → chapter_html + docx | +| F5 | 规则冲突决策 UI 缺失（api/WS 有接口但无页面） | P1 | 已修：生成页新增冲突浮动卡片 | +| F6 | 会话历史入口缺失（api 有 sessions 列表但 UI 无入口） | P1 | 已修：新增 §3.7 历史页 | +| F7 | 无障碍与设计规范缺失、emoji 无规范说明 | P2 | 已修：新增 §7 | + +--- + +## 二、详细发现 + +### F1（P0）上传区输入资料不完整 + 命名不一致 + +**证据** +- 大赛输入资料（`docs/design.md` §3.3）：要件定义 / 概要设计模板 / **做成说明书** / 记入规则 / 图表规则 / 现系统源码与设计书 +- `docs/sample-spec.md` 样本集含 `概要設計做成説明書.docx` +- `web-ui-design.md` §3.1 只有「要件定义 / 设计书模板 / 记录规则文档 / 图表规则 / 现有系统文件」——**做成说明书缺失** +- 命名不一致：web-ui「记录规则文档」vs design.md §8「写入规则 vs 做成说明书」 + +**修订** +- `web-ui-design.md` §3.1：上传区补齐「概要设计做成说明书（推荐）」，命名统一为「要件定义 / 设计书模板 / 做成说明书 / 记入规则 / 图表规则 / 现有系统文件」 +- 做成说明书以独立 `file_type=write_instruction` 提交（api-design §2.2 扩展） +- `design.md` §8 页面1 同步 + +--- + +### F2（P1）任务队列写死 Redis + +**证据** +- `web-ui-design.md` §4.1 与 `design.md` §8.4.1 均写作「Task Queue (Redis)」 +- `api-design.md` §1 架构决策（已与用户确认）：抽象 `TaskQueue` + `InMemoryQueue` 默认 + `RedisQueue`/`ValkeyQueue` 可选 +- `design-review.md` P1-1 已于 2026-07-30 修完 runtime 侧，但 web-ui / design §8 漏同步 + +**修订** +- 两文档 §4.1 / §8.4.1 改为「抽象 TaskQueue，默认 InMemory，可切 Redis/Valkey」 + +--- + +### F3（P1）设置页无设计 + +**证据** +- 顶部导航含 [设置]、斜杠命令含 /settings +- `api-design.md` §2.7 有 `/api/rules/versions`、`/update`、`/rollback`；§2.8 有 `/api/settings` +- `web-ui-design.md` §3 仅有页面 1-5 + +**修订**：新增 §3.6 设置页（规则版本管理 + LLM 配置只读摘要脱敏） + +--- + +### F4（P1）预览渲染路径不一致 + +**证据** +- `web-ui-design.md` §3.5 与 `design.md` §8 页面5 均写「docx → HTML → 浏览器内渲染」 +- `design.md` §7 决策：LLM 输出 ContentBlock → `chapter_html`（前端预览）+ docx（下载） +- `api-design.md` §2.6：`GET /result/preview` 返回 `{html}` + +**修订**：两处均改为「ContentBlock → HTML 渲染」，下载走 `/result/download`（docx） + +--- + +### F5（P1）规则冲突决策 UI 缺失 + +**证据** +- `api-design.md` §2.7 提供 `POST /api/rules/conflicts/{id}/resolve`；§3.2 WS 事件 `conflict_pending {conflict_id, topic, chapter_id}` +- `agent-runtime-design.md` §3.3 人工介入点包含「规则冲突确认」 +- 但 web-ui 5 页均无冲突决策界面 + +**修订**：生成执行页（页面4）新增规则冲突浮动卡片（WS 触发；不阻塞；决策后该章继续） + +--- + +### F6（P1）会话历史列表入口缺失 + +**证据** +- `api-design.md` §2.1 提供 `GET /api/sessions` 与 `DELETE /api/sessions/{id}`（会话列表/删除） +- web-ui 仅有 §5.2 会话恢复一句话，无列表页 + +**修订**：新增 §3.7 会话历史页（列表 / 恢复 / 删除 / 新建） + +--- + +### F7（P2）无障碍 / 规范 / emoji 说明缺失 + +**证据**：上传全拖拽、表格逐条修正等大量交互；无键盘可达、焦点可见、触控目标、色盲、对比度说明；绘图大量 emoji（🤖📁✅） + +**修订**：新增 §7 无障碍与设计规范（键盘可达、focus ring、≥44px、色盲安全、WCAG AA、骨架屏、具体错误文案、emoji 仅线框示意） + +--- + +## 2. 修订文件清单 + +| 文件 | 变更 | +|------|------| +| `docs/web-ui-design.md` | v1.0 → v1.1（F1-F7 全修订；新增设置/历史页、冲突卡片、无障碍章、端点对应表） | +| `docs/api-design.md` | §2.2 `file_type` 枚举扩展 `write_instruction` + 注释（F1 连带） | +| `docs/design.md` | §8 简版镜像同步（上传区、预览路径、队列抽象、导航历史、冲突卡片、设置/历史页简版、/history 命令） | +| `docs/web-ui-design-review-v1.1.md` | 本报告 | + +--- + +## 3. 遗留建议（不阻塞） + +- **RAG 层分类确认**：`write_instruction`（做成说明书）在 Parser 归类 Type A 写入规则（rag-layer §1.1）— 已存在对应约定，无额外工作 +- **验收建议**：实现 Phase 6（Web UI）时以上述 v1.1 为唯一依据；后续若做大版本 UI 改版，可再用 design-review 视觉审计（需已运行站点） +- **历史页「删除」二次确认**：防误伤生成成果（v1.1 §3.7 已标注） \ No newline at end of file diff --git a/docs/web-ui-design.md b/docs/web-ui-design.md index 90b012b..efd6add 100644 --- a/docs/web-ui-design.md +++ b/docs/web-ui-design.md @@ -1,6 +1,15 @@ # Web UI 设计文档 -> 版本: v1.0 | 日期: 2026-07-21 | 状态: 初版 +> 版本: v1.1 | 日期: 2026-08-09 | 状态: 复审修订版 +> +> 本次修订（v1.0 → v1.1）：按 `docs/web-ui-design-review-v1.1.md` 评审结果修订—— +> ① 上传区补齐「概要设计做成说明书」（独立 `write_instruction` 类型，api-design §2.2 连带扩展） +> ② 命名统一（记入规则 / 图表规则 / 做成说明书） +> ③ §4.1 任务队列改为抽象 TaskQueue（InMemory 默认，Redis/Valkey 可选） +> ④ §3.5 预览路径改为 ContentBlock → chapter_html + docx +> ⑤ 新增设置页（§3.6）与会话历史页（§3.7） +> ⑥ 生成页新增规则冲突浮动卡片（WS conflict_pending 触发） +> ⑦ 新增无障碍与设计规范（§7） --- @@ -8,11 +17,13 @@ 概要设计书自动生成 Agent 的 Web UI 是用户与系统交互的唯一界面，承担以下功能： -- 文件上传（要件定义、模板、规则文档、现系统文件） +- 文件上传（要件定义、模板、做成说明书、规则文档、现系统文件） - 各步骤的确认与修正（解析结果、影响调查结果、生成结果） - 生成进度实时展示 +- 规则冲突的决策 - 最终设计书的预览与下载 -- 规则手册管理（更新、版本查看） +- 规则手册管理（更新、版本查看、回退） +- 会话历史（恢复、删除） - 多用户支持（数据隔离） --- @@ -23,7 +34,7 @@ ``` ┌─────────────────────────────────────────────────────────────┐ -│ Genesis [上传] [解析] [影响调查] [生成] [结果] [设置] │ ← 顶部导航 +│ Genesis [上传] [解析] [影响调查] [生成] [结果] [历史] [设置] │ ← 顶部导航 ├─────────────────────────────────────────────────────────────┤ │ │ │ ┌─ 对话区域 ──────────────────────────────────────────┐ │ @@ -51,12 +62,13 @@ ``` ① 上传 → ② 解析确认 → ③ 影响调查确认 → ④ 生成执行 → ⑤ 结果预览 -(文件选择) (Sheet判定等) (关联・不确定处) (进度显示) (设计书浏览/下载) +(文件选择) (Sheet判定等) (关联・不确定处) (进度/冲突) (设计书浏览/下载) ``` - 每步骤有"确认"按钮，确认后进入下一步 -- 可通过左侧导航跳转到任意已完成的步骤（支持回退） +- 通过顶部导航可跳转到**任意已完成步骤**（状态机允许的回退路径，见 api-design §2.5 rollback 端点） - 当前步骤高亮显示 +- **历史页**提供已完成/进行中会话的列表入口与恢复（见 §3.7） --- @@ -78,22 +90,27 @@ │ │ │ 📁 设计书模板 (必须) │ │ ┌─────────────────────────────────────┐ │ -│ │ .docx (Word) │ │ +│ │ .docx (Word) │ │ │ └─────────────────────────────────────┘ │ │ │ -│ 📁 记录规则文档 (推荐) │ +│ 📁 概要设计做成说明书 (推荐) │ │ ┌─────────────────────────────────────┐ │ -│ │ .docx / .xlsx / .pptx (可多个) │ │ +│ │ .docx (Word) · 各章作成指引 │ │ +│ └─────────────────────────────────────┘ │ +│ │ +│ 📁 记入规则 (推荐, 可多个) │ +│ ┌─────────────────────────────────────┐ │ +│ │ .docx / .xlsx / .pptx │ │ │ └─────────────────────────────────────┘ │ │ │ │ 📁 图表规则 (推荐) │ │ ┌─────────────────────────────────────┐ │ -│ │ .docx / .xlsx / .pptx │ │ +│ │ .docx / .xlsx / .pptx │ │ │ └─────────────────────────────────────┘ │ │ │ │ 📁 现有系统文件 (任意, 追加/改修场景使用) │ │ ┌─────────────────────────────────────┐ │ -│ │ .java/.xml/.yml 源代码 或 │ │ +│ │ .java/.xml/.yml 源代码 或 │ │ │ │ 既有设计书 (.docx/.xlsx) │ │ │ └─────────────────────────────────────┘ │ │ │ @@ -106,11 +123,14 @@ **上传规则：** - 要件定义文件至少一个 - 模板文件必须是一个 .docx +- 做成说明书可零个（系统有内建默认指引时）；上传时以 `write_instruction` 类型标记（api-design §2.2） - 规则文档可多个，也可零个（规则手册已存在时） - 现系统文件仅在追加/改修场景时需要 -- 文件大小限制：最大100MB +- 文件大小限制：最大 100MB - 支持拖拽上传、点击上传、取消上传 +**对齐**：`POST /api/sessions/{id}/files`（`file_type`：`requirements` / `template` / `write_instruction` / `rules` / `existing_system`） + **斜杠命令：** `/upload` 等同于"上传文件区域获得焦点" --- @@ -126,11 +146,11 @@ │ ┌────────┬────────────┬────────┬─────────┐ │ │ │ Sheet名│ 类型判定 │ 修正 │ 行数/列数│ │ │ ├────────┼────────────┼────────┼─────────┤ │ -│ │ 功能一览 │ ✅ FUNCTION │ [修正]│ 150x5 │ │ -│ │ 画面一览 │ ✅ SCREEN │ [修正]│ 30x4 │ │ -│ │ 账票一览 │ ✅ REPORT │ [修正]│ 12x6 │ │ -│ │ DB定义 │ ✅ DATABASE │ [修正]│ 20x8 │ │ -│ │ 自由记述 │ ⚠ 自由记述型│ [修正]│ 45行 │ │ +│ │ 功能一览 │ ✅ FUNCTION │ [修正]│ 150x5 │ │ +│ │ 画面一览 │ ✅ SCREEN │ [修正]│ 30x4 │ │ +│ │ 账票一览 │ ✅ REPORT │ [修正]│ 12x6 │ │ +│ │ DB定义 │ ✅ DATABASE │ [修正]│ 20x8 │ │ +│ │ 画面对应 │ ⚠ 自由记述型│ [修正]│ 45行 │ │ │ └────────┴────────────┴────────┴─────────┘ │ │ ※ 取消线行将从生成对象中排除 │ │ │ @@ -156,10 +176,12 @@ ``` **交互说明：** -- Sheet类型判定由 AI 自动，但用户可以点击"修正"手动更改 +- Sheet 类型判定由 AI 自动，但用户可以手动更改 - 章节构成由模板自动解析，但用户可以追加/删除章节 - 现有系统信息仅在追加/改修场景显示 +**对齐原有：** `GET /api/sessions/{id}/parse-result`、`POST /api/sessions/{id}/confirm-parse`、`POST /api/sessions/{id}/reparse` + --- ### 3.3 页面3: 影响调查确认 @@ -186,7 +208,7 @@ │ 根据: 仅名称相似 │ │ → [追加] [否决] [修正] │ │ ❓ 批注「另纸参照」的另纸未找到 │ -│ → [输入回答] [跳过] │ +│ → [输入回答] [跳过] │ │ │ │ ── 质量指标 ── │ │ ⚠ 孤立要素: F012 与任何要素均无关联 │ @@ -200,11 +222,13 @@ - 一栏显示全部关联（无 auto-pass） - 仅高亮关注未确定项目 - 各关联的追加/删除/种类变更/证据修正是个别交互 -- 修正履历显示在画面底部 +- 修正履历显示在画面对应 + +**对齐原有：** `GET /api/sessions/{id}/impact-result`、`POST /api/sessions/{id}/impact-edits`、`POST /api/sessions/{id}/confirm-impact`、`POST /api/sessions/{id}/reject-impact` --- -### 3.4 页面4: 生成执行 +### 3.4 页面4: 生成执行（含规则冲突决策） ``` ┌─────────────────────────────────────────────┐ @@ -215,9 +239,9 @@ │ │ │ ✅ 功能一览 - 完成 (23秒) │ │ ✅ 画面一览 - 完成 (18秒) │ -│ ⠋ DB设计 - 生成中... │ +│ ⠋ DB设计 - 生成中... │ │ ⬜ 账票一览 - 等待 │ -│ ⬜ IF定义 - 等待 │ +│ ⬜ IF定义 - 等待 │ │ ⬜ 非功能要件 - 等待 │ │ │ │ 已过时间: 41秒 / 预计时间: ~3分 │ @@ -225,11 +249,17 @@ │ ────────────────────────────────────── │ │ DB设计章 生成中: │ │ 关联要素: F001, F003, TB001, TB002 │ -│ 适用规则: 写入规则_v3 │ -│ │ -│ ────────────────────────────────────── │ +│ 适用规则: 写入规则_v3 │ │ │ │ [中途中断] [查看日志] │ +│ │ +│ ┌─ 规则冲突 (浮动卡片) ───────────────────┐ │ +│ │ ⚠ 检测到规则冲突（DB设计章） │ │ +│ │ 记入规则 2.3「表头仅加粗」 │ │ +│ │ 图表规则 2.3「表头加粗+下划线」 │ │ +│ │ [采用「记入规则」] [采用「图表规则」] │ │ +│ │ [两规则都标注给人工] │ │ +│ └──────────────────────────────────────┘ │ └─────────────────────────────────────────────┘ ``` @@ -238,6 +268,9 @@ - 生成完成时通过浏览器通知（或 WebSocket 推送）告知 - 选择中断时，已完成的章节保留，其余作为未完成保存 - 中断后恢复时，从已完成的章节继续生成 +- **规则冲突**：由 WebSocket 事件 `conflict_pending {conflict_id, topic, chapter_id}` 触发浮动卡片（不阻塞其余进度展示）；用户决策后调用 `POST /api/rules/conflicts/{id}/resolve`，该章在决策后才继续（未决策时该章保持 waiting） + +**对齐原有：** `POST /api/sessions/{id}/generate`、`GET /api/sessions/{id}/generation-status`、`POST /api/sessions/{id}/regenerate-chapter`、`POST /api/rules/conflicts/{id}/resolve` --- @@ -249,57 +282,132 @@ ├─────────────────────────────────────────────┤ │ │ │ ┌─ QA报告 ──────────────────────────┐ │ +│ │ ⏳ QA 校验中… │ │ +│ │ 📊 检查项 7/10 完成 │ │ +│ ├─────────────────────────────────────┤ │ +│ │ (完成后) │ │ │ │ ✅ 全部10项检查通过 │ │ │ │ 内容准确性: 通过 │ │ │ │ 关联一致性: 通过 │ │ │ │ 规则遵守度: 警告 1件 │ │ -│ │ → 「功能概要应包含影响范围」 │ │ +│ │ 警告 1件: →「功能概要应包含影响范围」 │ │ │ └────────────────────────────────────────┘ │ │ │ │ ┌─ 预览 ──────────────────────────┐ │ -│ │ (docx → HTML → 浏览器内渲染) │ │ -│ │ 1. 目的 │ │ -│ │ 本系统是... │ │ +│ │ (章内容块 → HTML → 浏览器内渲染) │ │ +│ │ 1. 目的 │ │ +│ │ 本系统是... │ │ │ │ │ │ -│ │ 2. 功能一览 │ │ +│ │ 2. 功能一览 │ │ │ │ ┌──────┬────────┬───────┐ │ │ │ │ │功能ID │ 功能名 │ 概要 │ │ │ │ │ ├──────┼────────┼───────┤ │ │ -│ │ │F001 │用户 │... │ │ │ +│ │ │F001 │用户注册 │... │ │ │ │ │ └──────┴────────┴───────┘ │ │ -│ │ ... │ │ +│ │ ... │ │ │ └────────────────────────────────────────┘ │ │ │ │ ┌─ 下载区域 ──────────────────────────┐ │ -│ │ 📥 下载设计书 (.docx) │ │ -│ │ 📥 下载QA报告 (.json) │ │ -│ │ 📥 下载影响调查书 (.json) │ │ +│ │ 📥 下载设计书 (.docx) │ │ +│ │ 📥 下载QA报告 (.json) │ │ +│ │ 📥 下载影响调查书 (.json) │ │ │ └────────────────────────────────────────┘ │ │ │ │ [修正后重新生成] [进行新生成] │ └─────────────────────────────────────────────┘ ``` +**交互说明 / 预览路径（修订 v1.1）：** +- 预览采用 **ContentBlock → chapter_html** 管线（`GET /api/sessions/{id}/chapters/{chapter_id}` 获取内容块；`GET /api/sessions/{id}/result/preview` 获取 HTML），最终下载由 `GET /api/sessions/{id}/result/download` 返回 docx +- QA 校验完成的事件为 `qa_completed {summary}`，未完成时预览区显示「校验中…」占位 +- 下载项：设计书 docx / QA 报告 json / 影响调查书 json + +**对齐原有：** `GET /api/sessions/{id}/result/preview`、`/result/download`、`/result/qa-report`、`/result/impact-report`、`POST /api/sessions/{id}/writer-fix`、`POST /api/sessions/{id}/rollback-to-impact` + +--- + +### 3.6 页面6: 设置 + +``` +┌─────────────────────────────────────────────┐ +│ 6. 设置 │ +├─────────────────────────────────────────────┤ +│ │ +│ ── 规则手册 ── │ +│ [上一个版本] [当前版本: v3] [重建手册] │ +│ 版本列表: │ +│ ▸ v3 (active) 2026-08-01 文档: 5件 │ +│ ▸ 记入规则.docx │ +│ ▸ 图表规则.xlsx │ +│ ▸ 做成说明书.docx │ +│ ▸ v2 2026-07-15 文档: 3件 [回滚] │ +│ ▸ v1 2026-07-01 文档: 2件 │ +│ │ +│ [更新规则]（将当前上传区规则文件重建手册） │ +│ │ +│ ── LLM 状态（只读摘要，脱敏） ── │ +│ 模型: deepseek-chat (主) / deepseek-chat (备用) │ +│ 向量库: Chroma (可用) │ +│ 约束: max_context=32000 / max_output=4096 │ +│ (敏感密钥不显示，见 /api/settings 脱敏) │ +│ │ +└─────────────────────────────────────────────┘ +``` + +**对齐原有：** `GET /api/rules/versions`、`POST /api/rules/update`、`POST /api/rules/rollback`、`GET /api/settings` + +--- + +### 3.7 页面7: 会话历史 + +``` +┌─────────────────────────────────────────────┐ +│ 7. 历史会话 │ +├─────────────────────────────────────────────┤ +│ │ +│ [＋ 新会话] │ +│ │ +│ ┌─ 会话列表 ────────────────────────────┐ │ +│ │ 会话ID 状态 更新于 操作 │ │ +│ │ s_1009 结果已生成 今天 14:03 [恢复] [删] │ │ +│ │ s_1008 影响调查确认 今天 13:40 [恢复] [删] │ │ +│ │ s_1007 解析确认 昨天 17:21 [恢复] [删] │ │ +│ │ ... │ │ +│ └──────────────────────────────────────────┘ │ +│ │ +│ [恢复并继续] 跳到该会话当前步骤 │ +│ (会话状态: uploading / parsing / impact / │ +│ awaiting_parse_confirm / awaiting_impact_confirm │ +│ / writing / qa / done) │ +└─────────────────────────────────────────────┘ +``` + +**交互说明：** +- 通过 `GET /api/sessions?user_id=` 拉取会话列表 +- 「恢复」进入该会话当前步骤（若处于 waiting 状态则自动拉取最新进度） +- 「删除」调用 `DELETE /api/sessions/{id}`（需二次确认，避免误删生成成果） + --- ## 4. 技术设计 -### 4.1 任务管理 +### 4.1 任务管理与队列抽象（修订 v1.1） ``` -Task Queue (Redis) - ├── task:generate-chapter-1 - │ status: completed - │ result: {chapter: "功能一览", html: "...", time_ms: 23000} - │ - ├── task:generate-chapter-2 - │ status: running - │ started_at: 2026-07-21T12:01:00Z - │ - └── task:generate-chapter-3 - status: pending +TaskQueue（抽象接口，默认实现 InMemoryQueue） + ├── InMemoryQueue # 开发/测试/演示默认（零依赖） + ├── RedisQueue # 生产可选（redis-py） + └── ValkeyQueue # 生产可选（Valkey，Redis 协议兼容） + +任务队列条目： + task:generate-chapter-1 + status: completed + result: {chapter: "章节", html: "...", time_ms: 23000} ``` +- 队列实现由配置 `task_queue.backend` 决定（memory / redis / valkey），详见 `docs/api-design.md` §1 架构决策与 `docs/config-design.md` +- Web UI 无需关心后端实现，仅消费统一任务状态 + ### 4.2 会话管理（SQLite） **会话表设计：** @@ -311,18 +419,18 @@ CREATE TABLE sessions ( user_id TEXT NOT NULL, created_at DATETIME DEFAULT CURRENT_TIMESTAMP, updated_at DATETIME, - status TEXT, -- "uploading" | "parsing" | "awaiting_parse_confirm" | "impact_running" | "awaiting_impact_confirm" | "writing" | "qa" | "done" - current_step TEXT, - metadata JSON -- 会话的摘要 + status TEXT, -- "uploading" | "parsing" | "awaiting_parse_confirm" | "impact_running" | "awaiting_impact_confirm" | "writing" | "qa" | "done" + metadata JSON, -- 会话的摘要 + CONSTRAINT fk_user FOREIGN KEY(user_id) REFERENCES users(id) ); -- 中间成果物的快照 CREATE TABLE session_snapshots ( id INTEGER PRIMARY KEY AUTOINCREMENT, session_id TEXT NOT NULL REFERENCES sessions(id), - step TEXT NOT NULL, -- "parse" | "impact" | "writer" | "qa" - data BLOB, -- 序列化的中间成果物 (JSON) - version INTEGER DEFAULT 1, -- 修正时的版本管理 + step TEXT NOT NULL CHECK (step IN ('parse','impact','writer','qa')), + data BLOB, + version INTEGER DEFAULT 1, created_at DATETIME DEFAULT CURRENT_TIMESTAMP ); @@ -330,77 +438,67 @@ CREATE TABLE session_snapshots ( CREATE TABLE session_files ( id INTEGER PRIMARY KEY AUTOINCREMENT, session_id TEXT NOT NULL REFERENCES sessions(id), - file_type TEXT NOT NULL, -- "requirements" | "template" | "rules" | "existing_system" + file_type TEXT NOT NULL, -- "requirements" | "template" | "write_instruction" | "rules" | "existing_system" file_name TEXT NOT NULL, - file_path TEXT NOT NULL, -- 文件系统上的路径 + file_path TEXT NOT NULL, file_size INTEGER, - mime_type TEXT, uploaded_at DATETIME DEFAULT CURRENT_TIMESTAMP ); ``` -**为什么用 SQLite：** -- 单一文件，无需额外安装 -- 通过 SQL 查询即可轻松搜索会话（如「用户X的未完成会话」） -- ACID 事务保证数据一致性 -- 进程重启后数据仍保留 -- 迁移到 PostgreSQL 也容易（表定义兼容性高） +> 修订说明：`session_files.file_type` 同步扩展 `write_instruction`（对照 api-design §2.2） ### 4.3 多用户 ``` 工作区: /data/users/{user_id}/ - ├── uploads/ # 用户上传的文件 - │ ├── session_001/ - │ │ ├── requirements.xlsx - │ │ └── template.docx - │ └── session_002/ + ├── uploads/ # 用户上传的文件（含要件/模板/做成说明/规则） ├── outputs/ # 生成的设计书 - │ ├── session_001.docx - │ └── session_002.docx └── config/ - └── .env # 用户个别设置（API Key 等共享） + └── .env # 用户个别设置 -共享数据（所有用户通用）: +共享数据（规则与模板全局共享）: /data/shared/ - ├── rules-handbook/ - │ ├── v1/ - │ └── v2/ # 规则更新版本 + ├── rules-handbook/ # 规则手册版本目录 + │ ├── v1/ v2/ ... └── templates/ ``` --- -## 5. 异常处理UX +## 5. 异常处理 UX ### 5.1 生成出错时 ``` -DB设计 生成过程中发生错误 -┌─────────────────────────────────────────┐ -│ ⚠ DB设计章生成时发生错误 │ -│ 错误详情: LLM API调用失败 │ -│ 错误码: LLM_TIMEOUT │ +数据库设计 生成过程处理中发生错误 +┌──────────────────────────────────────────┐ +│ ⚠ DB 设计章节生成时发生错误 │ +│ 详情: LLM 调用超时 │ +│ 错误码: LLM_TIMEOUT (502) │ │ │ -│ [重试] [跳过并继续] [中断] │ -└─────────────────────────────────────────┘ +│ [重试] [跳过并继续] [中断] │ +│ │ +│ 若 LLM 未配置: 显示「去设置页配置 Key」 │ +└──────────────────────────────────────────┘ ``` - **重试**: 重新生成同一章（重试 LLM 调用） - **跳过**: 跳过此章并进入下一章 -- **中断**: 全部中断，保存迄今为止的已完成章节 +- **中断**: 全部中断，保存已完成的章节 +- 用户选项与 `api-design.md` §7 错误码表的 `options` 列对应；LLM 相关错误（LLM_TIMEOUT / LLM_NETWORK_ERROR / LLM_NOT_CONFIGURED / LLM_PARSE_ERROR）由 engine `error_code` 提供机器可读值（见 `docs/superpowers/specs/2026-08-09-llm-errorcode-alignment-design.md`） ### 5.2 会话恢复 -浏览器关闭后再次打开时： +浏览器关闭后再次打开时（从历史页或直接访问）： ``` 「要恢复上次的会话吗？」 -上次的状态: Step 3 (影响调查确认) - ・解析结果: ✅ 完成 - ・影响调查: ✅ 完成（以上述v2确认） - ・Writer: 未开始 +上次的状态: step 3 (影响调查确认) + ・解析结果: ✅ 完成 + ・影响调查: ✅ 完成（以已确认版本） + ・生成: 未开始 [恢复并继续] [开始新会话] ``` @@ -413,11 +511,42 @@ DB设计 生成过程中发生错误 /upload → 聚焦到文件上传区域 /probe → 跳转到解析结果画面 /impact → 跳转到影响调查画面 -/generate → 跳转到生成执行画面 +/generate → 跳到生成执行 /result → 跳转到结果画面 +/history → 跳转到历史会话页 /settings → 跳转到设置画面 -/status → 显示当前生成任务的状态 +/status → 查看当前任务状态 /cancel → 取消当前生成 /help → 显示帮助 ``` +--- + +## 7. 无障碍与设计规范（v1.1 新增） + +- **键盘可达**：所有交互（上传、表格修正、确认、冲突决策）可独立用 Tab + Enter/Space 完成 +- **焦点可见**：键盘导航始终显示 focus ring；清除 `:focus-visible` 必须提供替代 +- **触控目标**：可点击目标 ≥ 44×44px +- **色盲安全**：状态不单用红/绿区分（附加图标/文字，如 ✅/⚠/❌ 应用于状态图标） +- **对比度**：正文 ≥ 4.5:1，大号文字 ≥ 3:1（WCAG AA） +- **加载不能为空**：生成/进度用骨架屏或指示器，避免空白闪屏 +- **错误提示语具体**：错误信息给出出错的章节/操作 + 建议操作（如「配置 Key」） +- **emoji 规范**：本文作为线稿使用 emoji 仅为示意；正式实现用图标库（如 lucide 等）统一 +- **移动与响应式**：不要求手机为主场景，但桌面缩窄到 1024px 时须保持 5 步导航可用 + +--- + +## 8. 与后端 API 的端点对应（汇总） + +| UI 步骤 | 主要端点（api-design）| +|---------|----------------------| +| 上传 | POST `/api/sessions/{id}/files`、POST `/api/sessions/{id}/start-parse` | +| 解析确认 | GET/confirm-parse/reparse | +| 影响调查 | start-impact / impact-result / impact-edits / confirm-impact / reject-impact | +| 生成 | generate / generation-status / regenerate-chapter | +| 规则冲突 | POST `/api/rules/conflicts/{id}/resolve`（WS conflict_pending 触发）| +| QA | run-qa / qa-result / writer-fix / rollback-to-impact | +| 结果下载 | result/preview / download / qa-report / impact-report | +| 历史 | GET `/api/sessions`、DELETE `/api/sessions/{id}` | +| 设置 | GET `/api/rules/versions`、POST `/api/rules/update`、POST `/api/rules/rollback`、GET `/api/settings` | +| 其他 | GET `/api/health`、POST `/api/sessions/{id}/cancel`、GET `/api/sessions/{id}/logs` | \ No newline at end of file