@ -2,424 +2,41 @@
> **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` ，并同步按钮旁状态文案 。
**Goal:** 抽出地图指令进度浮层为展示组件；轮询/状态机留页面 。
**Architecture:** 在 `MonitorView` 本地维护 `commandProgress` 状态；`runCommand` 使用 `sendCommand` 返回的 `cmd.id` 启动轮询；右下角非模态浮窗展示三步进度；同 title 按钮 `small` 文案跟随状态。不改后端协议。
**Tech Stack:** Vue 3、现有 `request` /`urls`、`devicesStore.sendCommand`、`prototype.css`
**Architecture:** `CommandProgressFloat.vue` 接收 open/title/deviceName/step/status/result/error/terminalLabel，emit `close` 。
**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`
### Task 1
- [ ] **Step 1: 按钮 `small` 改为动态**
- Create `src/components/CommandProgressFloat.vue`
- Modify `src/views/MonitorView/MonitorView.vue`
机巢主按钮（有「状态：待执行」的） ：
替换 map-panel 内 float 为：
```vue
< small > {{ buttonStatusText('一键起飞') }}< / small >
< small > {{ buttonStatusText('一键降落') }}< / small >
<!-- stage / reset 同理，title 与 runCommand 第一个参数一致 -->
< CommandProgressFloat
:open="commandProgress.open"
:title="commandProgress.title"
:device-name="commandProgress.deviceName"
:step="commandProgress.step"
:status="commandProgress.status"
:result="commandProgress.result"
:error="commandProgress.error"
:terminal-label="commandProgressTerminalLabel"
@close ="closeCommandProgress"
/>
```
更多控制里 `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: 指令进度浮窗冒烟问题"
```
---
Commit: `refactor: 抽取 CommandProgressFloat 指令进度浮层`
## 覆盖对照（spec）
### Task 2 冒烟
| 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` |
| 不改后端协议 | 全程 |
浮层 DOM/class 在 open=true 时出现；点关闭触发 close；无 console error。
## 执行注意
## 约束
- 不要改 `devicesStore.sendCommand` 的返回值语义（已返回 cmd）。
- 不要引入 WebSocket。
- 工作流子步骤（开门/归中）不在本计划范围。
不改后台；精确 git add；中文 commit
xiaosi
3 weeks ago