From 64806167d3d3fdb11bbee3772522beb77c9ff253 Mon Sep 17 00:00:00 2001
From: xiaosi <2652281683@qq.com>
Date: Fri, 28 Aug 2026 16:39:19 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E5=A2=9E=E5=8A=A0=E4=B8=9A=E5=8A=A1?=
 =?UTF-8?q?=E8=A1=A8=E5=8D=95=E6=8E=A7=E4=BB=B6=E8=BF=81=E7=A7=BB=20TDesig?=
 =?UTF-8?q?n=20=E8=AE=BE=E8=AE=A1?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

第一轮覆盖设备/任务/固件页，约定 select/input/number/time
映射与 v-model 行为，其余页面后续轮次。
---
 ...-tdesign-form-controls-migration-design.md | 68 +++++++++++++++++++
 1 file changed, 68 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-08-28-tdesign-form-controls-migration-design.md

diff --git a/docs/superpowers/specs/2026-08-28-tdesign-form-controls-migration-design.md b/docs/superpowers/specs/2026-08-28-tdesign-form-controls-migration-design.md
new file mode 100644
index 0000000..c8cb3de
--- /dev/null
+++ b/docs/superpowers/specs/2026-08-28-tdesign-form-controls-migration-design.md
@@ -0,0 +1,68 @@
+# 业务表单控件迁移到 TDesign
+
+## 背景
+
+项目已接入 `tdesign-vue-next`（Vite `TDesignResolver` 按需引入）。登录页已用 `t-input` / `t-button` 等，但业务页筛选栏与弹窗表单仍大量使用原生 `<select>` / `<input>`。全站 `t-select` 用量为 0。
+
+目标方向：**能换的表单控件尽量全换**。本需求按页面分轮推进。
+
+## 目标
+
+1. 统一业务页表单控件为 TDesign，优先视觉与交互一致。
+2. 第一轮完成高频页：`DevicesView` / `TasksView` / `FirmwaresView`。
+3. 不改变业务逻辑与接口契约。
+
+## 非目标
+
+- 不改后台。
+- 不重做页面布局 / 表格体系。
+- 不在本轮替换地图内特殊控件、自定义外观开关（若强绑定原型 CSS，可暂留并标注）。
+- 不在本轮做完整 TDesign 主题定制（与 `prototype.css` 深度对齐另开）。
+- 第二轮页面（Users / OperationLogs / Account / DeviceDetail 等）不纳入本轮实现。
+
+## 第一轮范围
+
+| 页面 | 控件 |
+|------|------|
+| `DevicesView` | 搜索 input、状态/绑定 select、新增机巢表单 inputs、升级固件 select |
+| `TasksView` | 各 Tab 搜索 input、计划/设备/结果 select、任务/航线/航点表单 inputs、number、time、星期 select；原始视频录制自定义 checkbox → `t-switch` 或 `t-checkbox`（保持布尔语义） |
+| `FirmwaresView` | 搜索 input、状态 select、创建/编辑表单 inputs + number + select |
+
+## 控件映射
+
+| 原生 | TDesign | 约定 |
+|------|---------|------|
+| `<select>` | `t-select` | `:options="[{ label, value }]"`；少用 `<option>` 插槽 |
+| 文本 `<input>` | `t-input` | 搜索框可 `clearable`；短必填码按需 |
+| `type="number"` | `t-input-number` | 保留 `min/max/step`；`v-model` 数值语义不变 |
+| `type="time"` | `t-time-picker` | 绑定现有 `HH:mm` 字符串字段 |
+| 自定义录制 checkbox | `t-switch`（优先）或 `t-checkbox` | 仍绑定 `boolean` |
+| 纯展示/地图专用 input | 暂不换 | 标注原因 |
+
+尺寸：默认 `size="medium"`。筛选栏与工具栏用现有容器 class 限宽，尽量少覆盖 TDesign 主题变量。
+
+## 行为约定
+
+1. **v-model 类型不变**：空筛选项继续用 `''`；数值 select（如星期）继续 number。
+2. **事件**：原 `@change="reload"` 改为 `t-select` 的 `@change` 调同一 `reload`（或等价 watch，但优先显式事件以免双触发）。
+3. **选项数据**：在 `<script setup>` 提成常量/computed（如 `statusOptions`），模板只绑 `:options`。
+4. **无障碍**：原 `aria-label` 迁到 `t-select` 的 `placeholder` / 外层 label。
+5. **依赖**：不新增 npm 包；沿用自动按需引入。
+
+## 验收
+
+1. 上述三页无业务表单原生 `<select>`；可换的文本/数字/时间输入已换 TDesign。
+2. 筛选变更仍触发列表刷新；创建/编辑提交字段与改前一致。
+3. 登录页与其它未纳入页面行为不回归。
+4. 每页至少一次浏览器冒烟：打开筛选、改 select、打开一个表单弹窗填报。
+
+## 风险
+
+- TDesign 高度/边框与 `prototype.css` 工具栏不完全一致 → 用有限 class 调宽高，不全局改主题。
+- `t-input-number` / `t-time-picker` 空值与原生 string/number 混用 → 提交前保持与现有校验一致。
+- 任务页控件多 → 按页面拆 commit，避免巨石 diff。
+
+## 后续轮次（不在本轮）
+
+- Users / OperationLogs / Account / DeviceDetail 等剩余原生 select/input。
+- 可选：TDesign 主题 token 与原型色板对齐。