121 lines
5.8 KiB
Markdown
121 lines
5.8 KiB
Markdown
# 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 已标注） |