sanguo/sanguo_moziplus_v2
8
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
main
sanguo_moziplus_v2/docs/review/frontend-audit.md
T
cfdaily f9c03b349e auto-sync: 2026-05-19 22:24:38
2026-05-19 22:24:38 +08:00

21 KiB
Raw Permalink Blame History

前端组件审查报告

审查人: 庞统（副军师）🐦 日期: 2026-05-19 审查范围: src/frontend/src/ 全部 TSX/TS 文件 vs 设计文档

一、Tab/页面对照

App.tsx TAB_DEFS（实际代码，store.ts L129-L142）

# key label icon 对应组件 设计文档规划 状态
1 tasks 任务看板 📜 EdictBoard ✅ frontend-redesign-v2.6 §P1, topic9 §D9-3 ✅ 一致
2 mail 飞鸽传书 ✉️ MailPanel ❌ 设计文档无独立 Mail Tab（v2.7 新增，设计文档未更新） ✅ 超前实现（合理）
3 court 军议大厅 🏛️ CourtDiscussion ✅ topic9 §D9-3 "军议大厅→合并到评论线程" → 保留为独立 Tab ⚠️ 设计建议合并但代码保留
4 monitor 编排调度 🔌 MonitorPanel ✅ topic9 §D9-3 "编排调度→合并到任务看板" → 保留独立 Tab ⚠️ 设计建议合并但代码保留
5 agents 将军总览 🤺 OfficialPanel ✅ topic9 §D9-3 "将军总览→合并到全局监控" → 保留独立 Tab ⚠️ 设计建议合并但代码保留
6 models 模型配置 🤖 ModelConfig ✅ topic9 §D9-3 合并到系统配置 → 保留独立 Tab ⚠️ 设计建议合并但代码保留
7 skills 技能配置 🎯 SkillsConfig ✅ topic9 §D9-3 合并到系统配置 → 保留独立 Tab ⚠️ 设计建议合并但代码保留
8 sessions 传令巡哨 🔭 SessionsPanel ✅ topic9 §D9-3 "会话监控→合并到全局监控" → 保留独立 Tab ⚠️ 设计建议合并但代码保留
9 usage 花费总览 💰 UsagePanel ❌ 设计文档未规划此 Tab ✅ 超前实现
10 archives 奏折阁 📜 MemorialPanel ✅ topic9 §D9-3 "奏折阁→合并到产出档案" → 保留独立 Tab ⚠️ 设计建议合并但代码保留
11 templates 任务模板 📋 TemplatePanel ❌ 设计文档未规划此 Tab ✅ 超前实现
12 settings 系统设置 ⚙️ SettingsPanel ✅ frontend-redesign-v2.6 §P4, topic9 §D9-3 ✅ 一致

设计文档规划但代码未实现

设计文档页面 位置 状态
AI Briefing / AI 晨报 topic7 §D7-5, topic9 §D9-6, frontend-redesign-v2.6 §P5 ❌ 未实现（MorningPanel.tsx 存在但 Tab 中未注册，TabKey 类型中也未包含 morning）
Command Palette (⌘K) topic7 §D9-7 ⚠️ GlobalSearch.tsx 存在但未在 App.tsx 中使用/注册
产出档案 topic9 §D9-3 ❌ 未实现为独立 Tab（archives/MemorialPanel 是旧版归档视图）

总结

  • 设计建议 5 页精简（topic9 D9-3）→ 代码实际 12 Tab
  • 代码保留了 v1.0 的完整 Tab 结构，未按设计文档精简合并
  • 新增了 mail、usage、templates 三个设计文档未规划的 Tab
  • morning Tab 有组件（MorningPanel.tsx 418行）但未注册到 TAB_DEFS

二、组件功能审查

EdictBoard (文件: components/EdictBoard.tsx, 482行)

功能点 设计文档位置 代码实现状态 证据
顶部统计 4 格（活跃/完成/失败/审查） topic9 §3.2 "顶部统计（4格）" ✅ 已实现 L398-L415, 4个统计卡片
5 步线性状态管线（pending→claimed→working→review→done） topic9 §2.2, §3.2 ✅ 已实现 L10-L15 PIPELINE_STEPS
8 状态全覆盖（含 failed/blocked/cancelled 旁路） topic9 §2.2 司马懿 P1 评审 ✅ 已实现 L17-L20 PIPELINE_ORDER 含全部11状态
任务卡片（ID+标题+状态标签+Agent+优先级+管线） topic9 §3.2 "任务卡片" ✅ 已实现 L135-L220 TaskCard
筛选栏两行布局（第1行归档控制+第2行状态筛选+搜索） v2.8 §3.1 ✅ 已实现 L420-L458 两行筛选
卡片快捷按钮（最多3个，按状态动态显示） v2.8 §3.2 "卡片按钮（最多3个）" ✅ 已实现 L226-L241 CARD_ACTIONS
子 Task 进度指示器（■■□□□ 2/5 + 当前 Stage） v2.7 §1.6, §2.1 ✅ 已实现 L203-L213 subtaskIndex + 进度条
一键归档 v2.8 §2.2 ✅ 已实现 L440-L452
项目下拉在筛选栏 v2.8 §3.1 "项目下拉移入筛选栏" ❌ 未实现（项目下拉仍在 Header） App.tsx L87-L99 项目下拉在 hdr-r 中
DAG 拓扑视图 topic7 §D7-6 "全局层", topic9 §D9-5 ❌ 未实现 无 React Flow 依赖
评论线程（卡片级别） topic9 §D9-8 ❌ 未实现（评论仅在 TaskModal 中） EdictBoard 无评论入口

TaskModal (文件: components/TaskModal.tsx, 521行)

功能点 设计文档位置 代码实现状态 证据
4 Tab 布局（总览/产出/审查/经验） topic9 §3.3 "4 Tab 布局" ✅ 已实现 L287-L293 tabs 定义
基本信息展示 topic9 §3.3 Tab1 ✅ 已实现 L315-L321 描述展示
状态操作按钮（基于 VALID_TRANSITIONS 守卫） topic9 §2.3, v2.8 §3.2 "Modal 完整按钮" ⚠️ 部分实现 L141-L168 StatusButtons 渲染按钮但未绑定实际点击处理函数（按钮无 onClick）
11 状态转换表（含 paused/escalated/waiting_human） v2.8 §1.2 "完整状态转换表" ✅ 已实现 L23-L35 VALID_TRANSITIONS 含11个状态
事件时间线 topic9 §3.3 "事件时间线" ✅ 已实现 L170-L195 EventTimeline
评论/交接（6种类型：handoff/progress/review/rebuttal/debate/observation） topic9 §3.3 "评论/交接" ✅ 已实现 L37-L44 COMMENT_TYPE_LABEL, L374-L402 评论展示
决策记录 topic9 §3.3 "决策记录" ✅ 已实现 L404-L421
产出物列表 topic9 §3.3 Tab2 ✅ 已实现 L423-L442
审查记录（APPROVE/REJECT + 置信度 + 轮次） topic9 §3.3 Tab3 ✅ 已实现 L444-L474
经验沉淀（best_practice/pitfall/environment 彩色边框） topic9 §3.3 Tab4 ✅ 已实现 L476-L499
Checkpoint 面板（waiting_human 状态触发） v2.8 §四 "Checkpoint 机制" ✅ 已实现 L363-L371 CheckpointPanel 条件渲染
v2.7 子 Task 面板（Stage 进度条 + 子 Task 列表） v2.7 §2.2 父子关系 ✅ 已实现 L152-L196 SubtaskPanel
用户评论输入 topic9 §D9-8 "用户可以直接在评论线程中发言" ❌ 未实现 评论区域仅展示，无输入框
乐观锁（expected_version） topic9 §D9-10 "乐观锁" ❌ 未实现 无 version 字段处理
来源标识（source: 'dashboard'） topic9 §D9-10 "来源标识" ❌ 未实现 操作请求无 source 字段

CheckpointPanel (文件: components/CheckpointPanel.tsx, 357行)

功能点 设计文档位置 代码实现状态 证据
三种 Checkpoint 类型（验证/决策/执行） v2.8 §4.2 ✅ 已实现 三种渲染分支
verify 类型：自动核验 + 人工核验 + 双按钮审批 v2.8 §4.2 "验证" ✅ 已实现 approve/reject API 调用
decision 类型：多方案并排 + 利弊 + 推荐 v2.8 §4.2 "决策" ✅ 已实现 options 渲染
action 类型：分步打勾 + 命令行 v2.8 §4.2 "执行" ✅ 已实现 steps + command
API 对接（checkpoints CRUD） v2.8 §4.5 ✅ 已实现 fetch 调用 checkpoints API

ArtifactPanel (文件: components/ArtifactPanel.tsx, 185行)

功能点 设计文档位置 代码实现状态 证据
产出物列表展示 topic9 §3.3 Tab2 ✅ 已实现
产出物预览/下载 v2.8 §M3 "Artifact" ⚠️ UI 存在但 API 返回空 api.ts artifactPreview/artifactDownloadUrl 返回空/false

MailPanel (文件: components/MailPanel.tsx, 215行)

功能点 设计文档位置 代码实现状态 证据
邮件列表展示 v2.7 新增功能 ✅ 已实现 fetch /api/mail
邮件详情查看 v2.7 新增功能 ✅ 已实现 fetch /api/mail/{id}
标记已读/未读 v2.7 新增功能 ✅ 已实现 PATCH is_read
发送邮件 — ❌ 未实现 无发送 UI

MonitorPanel (文件: components/MonitorPanel.tsx, 503行)

功能点 设计文档位置 代码实现状态 证据
Agent 状态展示 topic9 §D9-5 "Agent 状态面板" ✅ 已实现
DAG 拓扑可视化 topic7 §D7-6, topic9 §D9-5 ❌ 未实现 无 React Flow
Gateway 健康检查 topic9 §D9-5 ✅ 已实现 api.agentsStatus()
Agent 唤醒按钮 — ✅ 已实现 api.agentWake()

GlobalSearch (文件: components/GlobalSearch.tsx, 104行)

功能点 设计文档位置 代码实现状态 证据
⌘K 快捷键触发 topic7 §D9-7 "Command Palette" ⚠️ 组件存在但未注册 App.tsx 未引用 GlobalSearch
模糊搜索任务+Agent topic7 §D9-7 ✅ 已实现 搜索逻辑完整

CourtDiscussion (文件: components/CourtDiscussion.tsx, 774行)

功能点 设计文档位置 代码实现状态 证据
议题创建 v1.0 功能迁移 ✅ 已实现 api.courtDiscussStart()
多轮讨论 v1.0 功能迁移 ✅ 已实现 api.courtDiscussAdvance()
讨论结论 v1.0 功能迁移 ✅ 已实现 api.courtDiscussConclude()

MorningPanel (文件: components/MorningPanel.tsx, 418行)

功能点 设计文档位置 代码实现状态 证据
新闻采集展示 topic7 §D7-5 "定时摘要" ✅ 已实现（组件存在）
订阅配置 — ✅ 已实现 SubConfigPanel
AI Briefing 自动生成 topic9 §D9-6, frontend-redesign-v2.6 §P5 ⚠️ 仅新闻展示，无 AI 摘要生成 无 AI 生成逻辑

UsagePanel (文件: components/UsagePanel.tsx, 172行)

功能点 设计文档位置 代码实现状态 证据
Token 消耗归因（按 Agent） 无设计文档 ✅ 超前实现 基于 officialsData 聚合
总消耗统计 无设计文档 ✅ 超前实现

NotificationCenter (文件: components/NotificationCenter.tsx, 73行)

功能点 设计文档位置 代码实现状态 证据
铃铛 UI frontend-redesign-v2.6 §P6 ⚠️ 占位（App.tsx 中仅一个 button，未引入 NotificationCenter 组件） App.tsx L83 按钮 + title="通知中心（v2.7）"
4 级分组通知 topic7 §D7-2 ❌ 未实现
SSE 实时推送 topic9 §4.3 "SSE 事件推送" ❌ 未实现 仍用 HTTP 5s 轮询

SettingsPanel (文件: components/SettingsPanel.tsx, 293行)

功能点 设计文档位置 代码实现状态 证据
项目管理（创建/删除） frontend-redesign-v2.6 §P4 ✅ 已实现
系统配置 topic9 §D9-3 ✅ 已实现

三、状态管理对照

store.ts V2Task 类型 vs 设计文档

字段 store.ts (L11-L42) 设计文档位置 一致性
status 11 个枚举值 'pending'|'claimed'|'working'|'review'|'paused'|'escalated'|'waiting_human'|'done'|'failed'|'blocked'|'cancelled' v2.8 §1.2 (11个状态) ✅ 完全一致
priority: number number 类型 topic9 §2.4 (P0修复: string→number) ✅ 一致
parent_task string | null v2.7 §2.1 ✅ 一致
depends_on string | null v2.7 §2.1 ✅ 一致
stages_json string v2.7 §2.1 ✅ 一致
stage string | null v2.7 §2.1 ✅ 一致
archived number v2.8 §2.1 ✅ 一致
escalated number v2.8 §1.3 (废弃字段,保留兼容) ✅ 一致
risk_level string | null topic9 §2.1 ⚠️ 设计文档为枚举 'low'|'standard'|'high'|'critical'，代码为 string | null
must_haves string | null ❌ 设计文档无此字段 ⚠️ 超前（代码有，设计未记录）
estimated_duration_minutes number | null ❌ 设计文档无此字段 ⚠️ 超前

PIPE 定义（store.ts L50-L57）

代码 PIPE（7步） 设计文档管线（topic9 §2.2 5步线性） 一致性
created → planning → challenge → assigned → executing → reviewing → done pending → claimed → working → review → done ❌ 不一致
代码 PIPE 保留旧版 Edict 7步管线 新设计是 5步线性管线

说明: store.ts 的 PIPE 用于旧版 Task 适配（Edict 模式），EdictBoard.tsx 使用自己的 PIPELINE_STEPS（5步），TaskModal.tsx 使用 VALID_TRANSITIONS（11状态）。三套管线并存，需注意一致性。

状态筛选按钮

代码（EdictBoard L361-L374） 设计文档（v2.8 §3.1 第2行） 一致性
all/pending/claimed/working/review/paused/escalated/waiting_human/done/failed/blocked/cancelled (12个) all/pending/claimed/working/review/paused/escalated/waiting_human/done/failed/blocked/cancelled (12个) ✅ 完全一致

四、API 调用对照

前端 api.ts 调用 vs 后端实际路由

前端方法 调用端点 后端路由（topic9 §4.4） 状态
api.liveStatus() /api/projects + /api/daemon/status + /api/projects/{pid}/tasks ✅ 已有 ✅ 对接
api.createTask() POST /api/projects/{pid}/tasks ✅ 已有 ✅ 对接
api.taskAction() POST /api/projects/{pid}/tasks/{tid}/status ✅ 已有 ✅ 对接
api.reviewAction() POST /api/projects/{pid}/tasks/{tid}/reviews ✅ 已有 ✅ 对接
api.taskProgress() GET /api/projects/{pid}/tasks/{tid}/progress ❌ 设计有但后端未实现 ⚠️ 前端调用，后端可能404
api.listSubtasks() GET /api/projects/{pid}/tasks?parent_task={pid} ⚠️ 后端是否有此查询参数？ ⚠️ 需确认
CheckpointPanel GET/POST /api/projects/{pid}/tasks/{tid}/checkpoints v2.8 §4.5 ✅ 对接
MailPanel GET /api/mail, GET/PATCH /api/mail/{id} v2.7 新增 ✅ 对接
api.courtDiscussStart/Advance/Conclude 前端调用但 api.ts 返回 { ok: false, error: 'Not implemented' } ❌ 后端未实现 ⚠️ UI存在但无功能
api.artifacts() 返回空 { ok: true, deliverable: null, nodes: [] } ❌ 后端未实现 ⚠️ 占位
api.humanInput() 返回空 { ok: true, active: false } ❌ 后端未实现 ⚠️ 占位
api.agentConfig() 返回空 { agents: [], knownModels: [] } ❌ v2.6 暂无 ⚠️ 占位
api.setModel/setDispatchChannel/agentWake 返回 { ok: false, error: 'Not implemented' } ❌ 未实现 ⚠️ 占位
api.morningBrief/morningConfig 返回空数据 ⚠️ Mock ⚠️ 占位

五、超前实现清单

代码已实现但设计文档中未记录的功能

# 功能 文件 说明
1 飞鸽传书 Tab（MailPanel） MailPanel.tsx (215行) v2.7 新增但设计文档 topic9 未更新 Tab 列表
2 花费总览 Tab（UsagePanel） UsagePanel.tsx (172行) 设计文档未规划此 Tab
3 任务模板 Tab（TemplatePanel） TemplatePanel.tsx (232行) + store.ts TEMPLATES 设计文档未规划此 Tab
4 新建军令 Modal（CreateTaskModal） App.tsx L135-L198 设计文档有提及（v2.8 §3.3 title可选）但未详细设计 UI
5 V2Task.must_haves 字段 store.ts L31 设计文档无此字段
6 V2Task.estimated_duration_minutes 字段 store.ts L33 设计文档无此字段
7 旧版 Edict 7步 PIPE 兼容 store.ts L50-L57 保留了旧版管线兼容逻辑
8 项目自动选择逻辑 store.ts loadLive 自动选择第一个项目
9 全局搜索 GlobalSearch GlobalSearch.tsx (104行) 设计为 D9-7 Command Palette，代码已实现但未注册
10 MorningPanel（AI晨报） MorningPanel.tsx (418行) 组件已实现但未注册到 TAB_DEFS
11 ArtifactList ArtifactList.tsx (71行) 独立产出物列表组件
12 ConfirmDialog ConfirmDialog.tsx (36行) 通用确认对话框
13 Toaster Toaster.tsx (16行) Toast 通知组件

六、缺口清单

设计文档已设计但代码未实现的功能

# 功能 设计文档位置 优先级 说明
1 页面精简为 5 Tab topic9 §D9-3, frontend-principles §页面对照 P1 设计要求10→5页，代码仍保留12 Tab
2 DAG 拓扑视图 topic7 §D7-6, topic9 §D9-5 P1 需要 React Flow，未实现
3 Command Palette (⌘K) topic7 §D9-7 P2 GlobalSearch 存在但未集成
4 SSE 实时推送 topic9 §4.3, frontend-principles "Phase 3" P2 仍用 HTTP 5s 轮询
5 通知中心完整实现 frontend-redesign-v2.6 §P6, topic7 §D7-2 P1 仅有铃铛占位按钮，无面板
6 AI Briefing 自动生成 topic9 §D9-6, frontend-redesign-v2.6 §P5 P3 MorningPanel 存在但未注册；AI 摘要生成未实现
7 用户评论输入 topic9 §D9-8 "用户可以直接在评论线程中发言" P1 TaskModal 评论区仅展示，无输入框
8 乐观锁 (expected_version) topic9 §D9-10 P2 操作请求无 version 字段
9 来源标识 (source: 'dashboard') topic9 §D9-10 P2 操作请求无 source 字段
10 TaskModal 状态按钮未绑定点击 topic9 §3.3 "状态操作" P0 StatusButtons 组件渲染了按钮但没有 onClick 处理
11 项目下拉移入筛选栏 v2.8 §3.1 P1 项目下拉仍在 Header
12 Artifact 文件预览/下载 v2.8 §M3 P2 API 返回空，前端仅占位
13 产出档案 Tab topic9 §D9-3 P2 设计有但未实现（archives 是旧版归档）
14 推送级别 4 级分组 topic7 §D7-2 P3 未实现
15 Agent 主动汇报（WebChat 推送） topic7 §D7-5 P3 前端无此逻辑（依赖后端+OpenClaw）
16 GET /tasks/{tid}/progress 后端 API v2.7 §2.2 P1 前端调用但后端可能未实现
17 GET /tasks/{tid}/experiences 后端 API topic9 §4.2 API-3 P1 后端未实现

七、关键发现

🔴 P0 关键问题

  1. TaskModal StatusButtons 无 onClick 绑定（TaskModal.tsx L141-L168）

    • 渲染了状态操作按钮但未绑定实际处理函数，用户点击无响应
    • 设计文档 topic9 §3.3 明确要求"按钮（基于守卫）"

  2. 三套管线并存

    • store.ts PIPE: 旧版 Edict 7步（created→planning→...→done）
    • EdictBoard.tsx PIPELINE_STEPS: 新版 5步（pending→claimed→working→review→done）
    • TaskModal.tsx VALID_TRANSITIONS: 新版 11状态转换表
    • 建议统一，清理旧版 PIPE

🟡 P1 重要问题

  1. Tab 数量未按设计精简：设计要求 5 页，代码实际 12 Tab。合并方案未执行。
  2. DAG 拓扑未实现：这是设计文档的核心差异化功能。
  3. 通知中心仅占位：SSE + 通知面板未对接。
  4. 用户评论输入缺失：TaskModal 中无法输入评论。
  5. taskProgress API 前端调用但后端可能未实现：会导致 404。

🟢 P2 改进建议

  1. GlobalSearch 组件已实现，建议集成 ⌘K 快捷键注册。
  2. MorningPanel 组件已实现，建议注册到 TAB_DEFS 或替代 AI Briefing。
  3. 项目下拉建议从 Header 移到 EdictBoard 筛选栏（v2.8 §3.1）。
  4. 乐观锁和来源标识建议在对接后端操作 API 时一并实现。

八、文件清单

文件 行数 主要功能
App.tsx ~200 主布局 + Header + Tab 路由 + CreateTaskModal
store.ts ~420 Zustand 全局状态 + PIPE + 模板 + 轮询
api.ts ~350 API 层（v2.6 适配 + 类型定义）
EdictBoard.tsx 482 任务看板（卡片 + 筛选 + 管线）
TaskModal.tsx 521 任务详情（4 Tab）
CheckpointPanel.tsx 357 Checkpoint 三类型面板
CourtDiscussion.tsx 774 朝堂议政
SkillsConfig.tsx 649 技能配置
MonitorPanel.tsx 503 编排调度
SessionsPanel.tsx 358 传令巡哨
MorningPanel.tsx 418 AI 晨报（未注册 Tab）
MailPanel.tsx 215 飞鸽传书
MemorialPanel.tsx 284 奏折阁
OfficialPanel.tsx 258 将军总览
SettingsPanel.tsx 293 系统设置
ArtifactPanel.tsx 185 成果物面板
ModelConfig.tsx 196 模型配置
TemplatePanel.tsx 232 任务模板
UsagePanel.tsx 172 花费总览
GlobalSearch.tsx 104 全局搜索（未注册）
NotificationCenter.tsx 73 通知中心（未集成）
ArtifactList.tsx 71 产出物列表
ConfirmDialog.tsx 36 确认对话框
Toaster.tsx 16 Toast 组件
CourtCeremony.tsx 51 朝堂仪式动画
time.ts — 时间工具
总计 ~6248
Reference in New Issue View Git Blame Copy Permalink