T1-SD0102-01/2026Technology-Competition

Files

T

lhl 1a3c829d4c docs: Web UI 设计评审修订（v1.0→v1.1，7 项发现全修 + api §2.2 write_instruction）

2026-08-09 13:28:38 +08:00

5.8 KiB

Raw Blame History

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 已标注）

5.8 KiB Raw Blame History Unescape Escape