docs: 增加监控页指令进度浮窗实现计划

拆分 URL、轮询状态机、浮窗 UI 与浏览器冒烟四步，对齐 sent/acked/timeout/terminal 状态展示。
3 weeks ago · 31ad35780a
1 changed files with 425 additions and 0 deletions
--- a/docs/superpowers/plans/2026-08-28-command-progress-float.md
+++ b/docs/superpowers/plans/2026-08-28-command-progress-float.md
@ -0,0 +1,425 @@
+# Command Progress Float Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 监控页下发指令后弹出当前指令进度浮窗，轮询 `/v1/commands/:id` 逐步展示 `sent/acked/timeout/terminal`，并同步按钮旁状态文案。
+
+**Architecture:** 在 `MonitorView` 本地维护 `commandProgress` 状态；`runCommand` 使用 `sendCommand` 返回的 `cmd.id` 启动轮询；右下角非模态浮窗展示三步进度；同 title 按钮 `small` 文案跟随状态。不改后端协议。
+
+**Tech Stack:** Vue 3、现有 `request`/`urls`、`devicesStore.sendCommand`、`prototype.css`
+
+**Spec:** `docs/superpowers/specs/2026-08-28-command-progress-float-design.md`
+
+---
+
+### Task 1: 增加指令详情 URL
+
+**Files:**
+- Modify: `src/config/urls.js`
+
+- [ ] **Step 1: 增加 `COMMAND(id)`**
+
+在 `// Commands` 段：
+
+```js
+// Commands
+export const COMMANDS = '/v1/commands'
+export const COMMAND = (id) => `/v1/commands/${id}`
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add src/config/urls.js
+git commit -m "feat: 增加单条指令查询 URL"
+```
+
+---
+
+### Task 2: Monitor 指令进度状态机与轮询
+
+**Files:**
+- Modify: `src/views/MonitorView/MonitorView.vue`
+
+- [ ] **Step 1: 增加 import**
+
+确保已有：
+
+```js
+import request from '@/utils/http'
+import * as urls from '@/config/urls'
+```
+
+若当前是别的 http 路径，保持项目现有 import 风格（与文件顶部一致），只补 `urls.COMMAND`。
+
+- [ ] **Step 2: 增加状态常量与 progress 状态**
+
+放在 `script setup` 控制相关区域（`runCommand` 附近）：
+
+```js
+const COMMAND_STATUS = {
+  sent: { name: '已下发', step: 2, result: '等待应答', terminal: false },
+  acked: { name: '已确认', step: 3, result: '执行成功', terminal: true, ok: true },
+  timeout: { name: '已超时', step: 3, result: '已超时', terminal: true, ok: false },
+  terminal: { name: '执行失败', step: 3, result: '执行失败', terminal: true, ok: false },
+}
+
+const commandProgress = reactive({
+  open: false,
+  title: '',
+  deviceName: '',
+  commandId: '',
+  status: '', // sent/acked/timeout/terminal
+  result: '',
+  step: 1, // 1 确认下发 2 已下发 3 终态
+  error: '',
+  buttonTitle: '',
+})
+
+let commandPollTimer = null
+let commandAutoCloseTimer = null
+let commandPollFails = 0
+```
+
+- [ ] **Step 3: 增加 helper**
+
+```js
+function buttonStatusText(title) {
+  if (commandProgress.buttonTitle !== title || !commandProgress.status) return '状态：待执行'
+  const meta = COMMAND_STATUS[commandProgress.status]
+  return meta ? `状态：${meta.name}` : '状态：待执行'
+}
+
+function clearCommandTimers() {
+  if (commandPollTimer) {
+    clearInterval(commandPollTimer)
+    commandPollTimer = null
+  }
+  if (commandAutoCloseTimer) {
+    clearTimeout(commandAutoCloseTimer)
+    commandAutoCloseTimer = null
+  }
+}
+
+function closeCommandProgress() {
+  clearCommandTimers()
+  commandProgress.open = false
+}
+
+function applyCommandStatus(cmd) {
+  const status = cmd?.status || 'sent'
+  const meta = COMMAND_STATUS[status] || COMMAND_STATUS.sent
+  commandProgress.status = status
+  commandProgress.step = meta.step
+  commandProgress.result = cmd?.ackResultCode || meta.result
+  commandProgress.error = ''
+  return meta
+}
+
+function scheduleAutoClose() {
+  if (commandAutoCloseTimer) clearTimeout(commandAutoCloseTimer)
+  commandAutoCloseTimer = setTimeout(() => {
+    closeCommandProgress()
+  }, 5000)
+}
+
+async function pollCommandOnce() {
+  if (!commandProgress.commandId) return
+  try {
+    const cmd = await request.get(urls.COMMAND(commandProgress.commandId))
+    commandPollFails = 0
+    const meta = applyCommandStatus(cmd)
+    if (meta.terminal) {
+      clearInterval(commandPollTimer)
+      commandPollTimer = null
+      scheduleAutoClose()
+    }
+  } catch (e) {
+    commandPollFails += 1
+    const status = e?.response?.status
+    if (status === 403 || status === 404 || commandPollFails >= 3) {
+      clearInterval(commandPollTimer)
+      commandPollTimer = null
+      commandProgress.error =
+        status === 403
+          ? '无权限查看进度，请稍后在操作记录确认'
+          : status === 404
+            ? '未找到指令记录'
+            : (e.message || '进度查询失败')
+      scheduleAutoClose()
+    }
+  }
+}
+
+function startCommandProgress(cmd, title, deviceName) {
+  clearCommandTimers()
+  commandPollFails = 0
+  commandProgress.open = true
+  commandProgress.title = title
+  commandProgress.deviceName = deviceName || '--'
+  commandProgress.commandId = String(cmd?.id || '')
+  commandProgress.buttonTitle = title
+  commandProgress.step = 1
+  commandProgress.error = ''
+  applyCommandStatus(cmd || { status: 'sent' })
+
+  if (!commandProgress.commandId) {
+    commandProgress.error = '未返回指令 ID，无法跟踪进度'
+    scheduleAutoClose()
+    return
+  }
+
+  const ttl = Number(cmd?.ttlMs) > 0 ? Number(cmd.ttlMs) : 30000
+  const deadline = Date.now() + ttl + 5000
+
+  commandPollTimer = setInterval(async () => {
+    if (Date.now() > deadline) {
+      clearInterval(commandPollTimer)
+      commandPollTimer = null
+      if (!COMMAND_STATUS[commandProgress.status]?.terminal) {
+        commandProgress.error = '等待超时，请稍后在操作记录查看'
+        commandProgress.step = 3
+      }
+      scheduleAutoClose()
+      return
+    }
+    await pollCommandOnce()
+  }, 1500)
+
+  // 立即查一次，避免干等 1.5s
+  pollCommandOnce()
+}
+```
+
+- [ ] **Step 4: 改写 `runCommand`**
+
+```js
+async function runCommand(title, desc) {
+  const rec = record.value
+  if (!rec) return
+  if (!rec.online) {
+    ui.toast('设备当前离线，无法下发指令')
+    return
+  }
+  if (rec.kind === 'drone' && rec.bindingState !== 'bound') {
+    ui.toast('无人机未绑定机巢，无法下发指令')
+    return
+  }
+  const ok = await ui.confirm(title, desc)
+  if (!ok) return
+  try {
+    const cmd = await devices.sendCommand(rec, title)
+    ui.toast(`${title}指令已下发`)
+    startCommandProgress(cmd, title, rec.name)
+    await reload()
+  } catch (e) {
+    ui.toast(e.message || '指令下发失败')
+  }
+}
+```
+
+- [ ] **Step 5: 卸载清理**
+
+在现有 `onUnmounted` 中追加：
+
+```js
+closeCommandProgress()
+```
+
+并在 `onGlobalKeydown` 增加：
+
+```js
+if (event.key === 'Escape' && commandProgress.open) {
+  closeCommandProgress()
+  return
+}
+```
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/views/MonitorView/MonitorView.vue
+git commit -m "feat: 监控指令下发后轮询命令状态"
+```
+
+---
+
+### Task 3: 浮窗 UI + 按钮状态文案
+
+**Files:**
+- Modify: `src/views/MonitorView/MonitorView.vue`
+- Modify: `src/styles/prototype.css`
+
+- [ ] **Step 1: 按钮 `small` 改为动态**
+
+机巢主按钮（有「状态：待执行」的）：
+
+```vue
+<small>{{ buttonStatusText('一键起飞') }}</small>
+<small>{{ buttonStatusText('一键降落') }}</small>
+<!-- stage / reset 同理，title 与 runCommand 第一个参数一致 -->
+```
+
+更多控制里 `dockExtraCommands`：
+
+```vue
+<small>{{ commandProgress.buttonTitle === cmd.title && commandProgress.status ? buttonStatusText(cmd.title) : cmd.hint }}</small>
+```
+
+无人机侧：对已有 `<small>` 的主按钮（一键返航/起飞/紧急停止）同样用 `buttonStatusText(title)`；纯文字 secondary 按钮可不加。
+
+- [ ] **Step 2: 增加浮窗模板**
+
+放在 `MonitorView` 根模板末尾（与 dock status modal 同级）：
+
+```vue
+<div
+  v-if="commandProgress.open"
+  class="command-progress-float"
+  role="status"
+  aria-live="polite"
+>
+  <header>
+    <div>
+      <strong>{{ commandProgress.title }}</strong>
+      <small>{{ commandProgress.deviceName }}</small>
+    </div>
+    <button type="button" class="icon-command" title="关闭" @click="closeCommandProgress">
+      <svg><use href="#i-x" /></svg>
+    </button>
+  </header>
+  <ol>
+    <li :class="{ done: commandProgress.step > 1, active: commandProgress.step === 1 }">
+      <i></i><span>确认下发</span><em>已确认</em>
+    </li>
+    <li :class="{ done: commandProgress.step > 2, active: commandProgress.step === 2 }">
+      <i></i><span>已下发</span><em>{{ commandProgress.step >= 2 ? '等待应答' : '…' }}</em>
+    </li>
+    <li
+      :class="{
+        done: commandProgress.step >= 3 && !commandProgress.error && commandProgress.status === 'acked',
+        active: commandProgress.step === 3,
+        fail: commandProgress.step >= 3 && (commandProgress.status === 'timeout' || commandProgress.status === 'terminal' || !!commandProgress.error),
+      }"
+    >
+      <i></i>
+      <span>{{ commandProgress.status === 'acked' ? '已确认' : (COMMAND_STATUS[commandProgress.status]?.name || '执行结果') }}</span>
+      <em>{{ commandProgress.error || commandProgress.result || '…' }}</em>
+    </li>
+  </ol>
+</div>
+```
+
+注意：模板里若不能直接用 `COMMAND_STATUS`，改成 computed `commandProgressTerminalLabel`。
+
+- [ ] **Step 3: 增加样式**
+
+`prototype.css` 追加：
+
+```css
+.command-progress-float {
+  position: absolute;
+  right: 18px;
+  bottom: 56px;
+  z-index: 36;
+  width: 280px;
+  padding: 12px 12px 10px;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  background: rgba(255,255,255,.96);
+  box-shadow: 0 10px 28px rgba(20, 34, 48, .18);
+  color: #334553;
+}
+.command-progress-float > header {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 8px;
+  margin-bottom: 10px;
+}
+.command-progress-float > header strong { display: block; font-size: 13px; }
+.command-progress-float > header small { color: var(--muted); font-size: 11px; }
+.command-progress-float ol { margin: 0; padding: 0; list-style: none; display: grid; gap: 8px; }
+.command-progress-float li {
+  display: grid;
+  grid-template-columns: 14px 1fr auto;
+  align-items: center;
+  gap: 8px;
+  min-height: 28px;
+  color: #7b8792;
+  font-size: 12px;
+}
+.command-progress-float li i {
+  width: 10px; height: 10px; border-radius: 50%;
+  border: 1.5px solid #c0CAD3; background: #fff;
+}
+.command-progress-float li.active { color: #1f5f9f; font-weight: 600; }
+.command-progress-float li.active i { border-color: #2d82da; background: #2d82da; }
+.command-progress-float li.done { color: #2f6b4f; }
+.command-progress-float li.done i { border-color: #2f9d6a; background: #2f9d6a; }
+.command-progress-float li.fail { color: #a53e45; }
+.command-progress-float li.fail i { border-color: #c8454b; background: #c8454b; }
+.command-progress-float li em { font-style: normal; color: var(--muted); font-size: 11px; }
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/views/MonitorView/MonitorView.vue src/styles/prototype.css
+git commit -m "feat: 增加指令进度浮窗与按钮状态文案"
+```
+
+---
+
+### Task 4: 浏览器冒烟
+
+**Steps:**
+
+- [ ] **Step 1: 启动前端，mock 指令接口**
+
+对监控页：
+
+1. 登录进 `/monitor`，选中在线机巢。
+2. 拦截：
+   - `POST /api/v1/docks/:id/command` → `{ code:200, data:{ id: 1001, status:'sent', ttlMs:30000, commandType:'dock.open' } }`
+   - 前 2 次 `GET /api/v1/commands/1001` → `status:'sent'`
+   - 之后 → `status:'acked', ackResultCode:'OK'`
+3. 点击「打开舱门」或「一键起飞」并确认。
+
+- [ ] **Step 2: 验收清单**
+
+1. 浮窗出现，步骤 1 完成 → 步骤 2「已下发/等待应答」→ 步骤 3「已确认/执行成功」。
+2. 对应按钮 `small` 变为「状态：已下发」再变「状态：已确认」。
+3. 终态约 5s 后浮窗自动关闭；期间可手动关。
+4. Escape 可关闭浮窗。
+5. 连续点另一条指令：浮窗切换到新指令。
+6. 离线设备：仅 toast，不出现成功浮窗。
+
+- [ ] **Step 3: Commit 验收说明（若有小修）**
+
+若冒烟中修了样式/边界，单独 commit：
+
+```bash
+git add -A
+git commit -m "fix: 指令进度浮窗冒烟问题"
+```
+
+---
+
+## 覆盖对照（spec）
+
+| Spec 要求 | Task |
+|-----------|------|
+| 下发后浮窗 + 三步状态 | Task 2/3 |
+| 轮询 `/v1/commands/:id` 1.5s，TTL+5s | Task 2 |
+| 按钮 small 同步 | Task 3 |
+| 终态 5s 自动关 / 手动关 / Escape | Task 2/3 |
+| 同设备新指令替换跟踪 | Task 2 `startCommandProgress` |
+| 403/404/连续失败 | Task 2 `pollCommandOnce` |
+| 不改后端协议 | 全程 |
+
+## 执行注意
+
+- 不要改 `devicesStore.sendCommand` 的返回值语义（已返回 cmd）。
+- 不要引入 WebSocket。
+- 工作流子步骤（开门/归中）不在本计划范围。