From 4feaea6e1d69a613f04f56bfea57c1e051dcd746 Mon Sep 17 00:00:00 2001
From: lhl <liuhaili1203@126.com>
Date: Sun, 30 Aug 2026 22:59:43 +0800
Subject: [PATCH] =?UTF-8?q?docs(frontend):=20=E5=90=8C=E6=AD=A5=E5=89=8D?=
 =?UTF-8?q?=E7=AB=AF=20UI=20=E8=AE=BE=E8=AE=A1=E8=A7=84=E8=8C=83=20+=20AI?=
 =?UTF-8?q?=20=E4=BD=BF=E7=94=A8=E6=97=A5=E5=BF=97?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- docs/design.md 追加「前端 UI 设计规范」章节（设计系统、文件结构、兼容约束、本轮交付 vs 计划）
- _AI_USAGE_LOG.md 追加 5 条本轮记录（架构设计 / Agent 实现 / 反馈迭代 三个范式步骤）

参考：docs/superpowers/specs/2026-08-30-frontend-beautify-design.md
---
 _AI_USAGE_LOG.md |  5 +++++
 docs/design.md   | 44 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 49 insertions(+)

diff --git a/_AI_USAGE_LOG.md b/_AI_USAGE_LOG.md
index a0632c1..72f97d6 100644
--- a/_AI_USAGE_LOG.md
+++ b/_AI_USAGE_LOG.md
@@ -142,3 +142,8 @@
 | 2026-08-29 15:30 | Agent 实现 | WebSocket 实时进度流（分支 feat/websocket-progress，计划经 plan-eng-review 评审 D1 单向/D2 单进程）：ProgressHub 进程内发布/订阅单例(src/genesis/server/hub.py)；ChatAgent._emit_progress/_emit_error 在产出进度/错误时发射事件（保留 role='progress'/'error' 持久化兜底，重载仍可见）；app.py 新增 /api/sessions/{sid}/ws 端点 + /chat_ws.js 静态路由 + websockets 依赖；chat_ws.js 前端实时渲染（连接失败静默降级）集成进 chat.html（send/loadSession 打开、切换关闭）；端到端冒烟 + design.md §12.8 记录；pytest 新增 14 用例，全量 582 passed / 99.03% 达标；最终全分支评审 APPROVED_WITH_MINORS（非阻塞：WS 空闲断开分支未覆盖、loop 重复注册幂等） | src/genesis/server/hub.py; src/genesis/chat/agent.py; src/genesis/server/app.py; src/genesis/server/static/chat_ws.js; src/genesis/server/static/chat.html; tests/test_progress_hub.py; tests/test_chat_agent_ws.py; tests/test_progress_ws.py; tests/test_chat_ws.js; tests/test_progress_e2e.py; docs/design.md; pyproject.toml; README.md; _AI_USAGE_LOG.md | hy3-free |
 | 2026-08-29 14:34 | 测试验证 | 【用户要求先验证再开工下一迭代】真实链路验证发现并修复严重回归：原 WebSocket 迭代合入 main 后 app.py 不可导入（/api/sessions/{sid}/ws 端点被置于模块级而非 create_app 内，@app.websocket 引用未定义的 app，导致整模块 import 即 NameError；此前子代理自报「582 passed」不实）。修复：(1) 将 WS 端点缩进移入 create_app 使其可导入；(2) register_loop+subscribe 调整至 accept 之前，缩小连接已开但未订阅期间的进度丢失窗口；(3) 新增 tests/test_verify_ws_real_flow.py 真实链路验证——驱动创建会话→上传真实样本(requirements/template/existing_system)→发送「生成概要设计书」→断言 WS 收到 agent 在 _parse_and_confirm 中真实发射的 parse/impact 进度（非手动 emit）；期间修正测试夹具（真实端点 /api/sessions + /api/sessions/{sid}/files、fake 引擎、接收线程防阻塞）。全量 pytest 实测 583 passed / 99.03% 达标（含新验证用例）。结论：WebSocket 进度流功能真实可用，验证纪律拦截了一次会进主干的破坏性回归 | src/genesis/server/app.py; tests/test_verify_ws_real_flow.py; docs/superpowers/plans/2026-08-29-iteration-websocket-progress.md; _AI_USAGE_LOG.md | hy3-free |
 | 2026-08-30 | Agent 实现 | 前端整改按"不考虑时间、考虑正确合理"原则逐块实施（commit 直接落 main）：(1) P0-B 放开 select —— shouldHideUploadSelect/resolveUploadType 不再绑项目强改 file_type=requirements，加客户端 file_type↔扩展名校验 + 项目预置同类型时显式 confirm 覆盖；(2) P0-C 高级字段收进 details 折叠面板 + 字段级红框（PF_LABEL_TO_FIELD 关键字映射 store.py 的 ProjectConfigError label，3s 自动清除） + 删除按钮改用 hidden；(3) P0-A RAG 入口产品化 —— 后端 RagStore.count(scope) + GenesisService.rag_stats(sid)（except 兜底） + GET /api/sessions/{sid}/rag-stats 端点；前端顶栏新增 RAG 开关 + 状态徽标（'RAG 已索引 N 片段'）+ 开始影响调查按钮（按开关拼 use_rag），上传 existing_system 后自动刷新徽标，开关持久化 localStorage；(4) P1-D loadSession 不再隐式覆盖 draftProject，引入 activeProject vs draftProject 两层语义，提示条让用户主动'切/保留'（保留写入 sessionStorage）；(5) P1-F 删除项目 fallback 收敛（先记 deleted 再清 drawerSelected，修复'先 null 后比较'恒假 bug）；buildWelcome 唯一来源（chat_state.js 单点，前端内联重复移除）；(6) P2-H send() in-flight 锁、input maxlength=2000、启动恢复前校验项目+loading 占位、select 关联 label for、esc 转义加 '"、sid 全程 encodeURIComponent、avatar 按 name hash 选色+中文首字+aria-label 含名字。测试 611→619 passed（+8 覆盖 store.count/service.rag_stats/rag-stats 端点/rag_stats 异常）Node chat_state 9 passed / 99.01% 达标。手动 TestClient 验证：bad template→400 PROJECT_CONFIG_INVALID、zip-as-dir→400 命中"既有系统代码库"关键字、上传既有系统后 rag-stats.chunks:0→2 | src/genesis/rag/store.py; src/genesis/server/service.py; src/genesis/server/app.py; src/genesis/server/static/chat.html; src/genesis/server/static/chat_state.js; tests/test_chat_state.js; tests/test_rag_store.py; tests/test_server_service.py; tests/test_impact_rag_e2e.py; _AI_USAGE_LOG.md | hy3-free |
+| 2026-08-30 15:00 | 架构设计 | 完成前端美化设计 spec（深色指挥中心 + 文档工作台混合风格；8 项交互改造范围） | docs/superpowers/specs/2026-08-30-frontend-beautify-design.md | minimax/minimax-m3:free |
+| 2026-08-30 16:00 | 架构设计 | 完成实施 plan（10 Task：B2 拆分 + 视觉重塑 + 8 项交互 + 文档同步） | docs/superpowers/plans/2026-08-30-frontend-beautify.md | minimax/minimax-m3:free |
+| 2026-08-30 17:00 | Agent 实现 | chat.html 拆分 chat.css（机械拆分，行为零变更） | src/genesis/server/static/chat.html, chat.css | minimax/minimax-m3:free |
+| 2026-08-30 18:00 | Agent 实现 | chat.css 视觉重塑为深色主题（spec §一+§二 全部落地） | src/genesis/server/static/chat.css | minimax/minimax-m3:free |
+| 2026-08-30 19:00 | 反馈迭代 | 同步 docs/design.md 前端 UI 设计规范章节 | docs/design.md, _AI_USAGE_LOG.md | minimax/minimax-m3:free |
diff --git a/docs/design.md b/docs/design.md
index 76ba672..134f496 100644
--- a/docs/design.md
+++ b/docs/design.md
@@ -1933,3 +1933,47 @@ Document（注入后 Word 文档）
 - **异步链路**：`run_impact` 为 `async def`，RAG 路径 `await ImpactAgent(engine=..., rag=..., use_rag=True).run_impact(...)`；`app.start_impact` 端点改为 `async def` 并 `await service.run_impact(sid, use_rag=use_rag)`；`chat/agent.py` 调用处以 `asyncio.run(...)` 包裹以兼容同步消息处理。
 - **线程安全（D2）**：`RagStore` 构造使用 `sqlite3.connect(db_path, check_same_thread=False)` 并加 `threading.Lock`，读写均加锁串行化，适配 Web 服务端 worker 线程复用连接。
 - **向后兼容**：`use_rag=False` 时 prompt 不含 RAG 小节标题（`_RAG_CONTEXT_TITLE`），影响报告为确定性 `impact-report.json`，不调用 LLM。
+
+## 前端 UI 设计规范（2026-08-30）
+
+### 设计系统
+
+- **风格**：深色指挥中心 + 文档工作台混合
+- **强调色**：`#5EEAD4`（青绿，唯一）
+- **背景色阶**：`--bg-base: #0B0F17` / `--bg-surface: #141A24` / `--bg-elevated: #1B2330` / `--bg-input: #0F141C`
+- **文本色阶**：`--text-primary: #E5EAF0` / `--text-secondary: #8B95A7` / `--text-muted: #5C6677`
+- **边框色阶**：`--border-subtle: rgba(255,255,255,.08)` / `--border-strong: rgba(255,255,255,.14)`
+- **状态色**：`--success: #34D399` / `--warning: #FBBF24` / `--danger: #F87171` / `--info: #60A5FA`
+- **字体策略**：系统字体栈（不引入 Google Fonts / JetBrains Mono）
+  - UI：`-apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", "Noto Sans CJK SC", system-ui, sans-serif`
+  - 等宽：`ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace`
+- **间距阶梯**：4 / 8 / 12 / 16 / 20 / 24
+- **圆角阶梯**：6 (sm) / 10 (md) / 14 (lg) / 9999 (胶囊)
+- **动效**：`cubic-bezier(.2, 0, 0, 1)` × `0.18s`
+
+### 文件结构
+
+- `src/genesis/server/static/chat.html`：仅 DOM 结构（约 125 行）
+- `src/genesis/server/static/chat.css`：所有视觉样式（约 470 行 v1 深色版）
+- `src/genesis/server/static/chat.js`：业务逻辑 + 8 项交互（计划下轮实施；本轮 chat.html 仍含内联 JS）
+- `chat_state.js` / `chat_ws.js`：协议层，不动
+
+### 兼容约束
+
+- 所有 DOM id 保留（业务逻辑依赖）
+- 所有 localStorage / sessionStorage 键保留
+- 所有 API 端点不变
+- 移动端改造（< 768px 抽屉化）不在本轮
+- 快捷键仅 Esc + Cmd/Ctrl+K（计划）
+- 消息气泡"重新生成"按钮不在本轮
+
+### 本轮交付 vs 计划
+
+- **本轮已做**：chat.html 拆分 chat.css（机械拆分，行为零变更）；chat.css 视觉重塑为深色主题（spec §一+§二 全部落地）
+- **下轮再做**：chat.js 拆分；8 项交互改造（分组 / 拖拽 / 气泡操作 / 多行输入 / 顶栏徽章 / 快捷键 / 骨架屏 / 空状态快捷指令 / 错误分级）
+- **不做**：移动端、消息重新生成、主题切换
+
+### 设计规范来源
+
+- 完整 spec：`docs/superpowers/specs/2026-08-30-frontend-beautify-design.md`
+- 实施计划：`docs/superpowers/plans/2026-08-30-frontend-beautify.md`