From 2a4c774aca2ab7d52434014ef2892f36c1d40fc1 Mon Sep 17 00:00:00 2001
From: YunaiV <zhijiantianya@gmail.com>
Date: Sun, 7 Dec 2025 16:36:55 +0800
Subject: [PATCH] =?UTF-8?q?review=EF=BC=9A=E3=80=90antd/ele=E3=80=91?=
 =?UTF-8?q?=E3=80=90iot=E3=80=91=E4=BB=A3=E7=A0=81=E8=BF=81=E7=A7=BB?=
 =?UTF-8?q?=E7=9A=84=20review?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../src/views/iot/device/device/index.vue     | 47 ++++++++++---------
 .../iot/device/device/modules/card-view.vue   | 15 +++---
 .../device/device/modules/detail/index.vue    |  5 +-
 .../device/modules/detail/modules/config.vue  | 23 ++++-----
 .../device/modules/detail/modules/message.vue |  2 +
 .../modules/detail/modules/simulator.vue      |  1 +
 .../modules/detail/modules/sub-device.vue     |  2 +
 .../detail/modules/thing-model-event.vue      |  1 +
 .../modules/thing-model-property-history.vue  | 28 +++++------
 .../detail/modules/thing-model-property.vue   |  1 +
 .../detail/modules/thing-model-service.vue    |  1 +
 .../views/iot/device/device/modules/form.vue  | 10 ++--
 .../iot/device/device/modules/group-form.vue  |  3 +-
 .../iot/product/category/modules/form.vue     |  1 +
 .../src/views/iot/product/product/data.ts     |  1 +
 .../src/views/iot/product/product/index.vue   | 27 +++++------
 .../iot/product/product/modules/card-view.vue |  4 +-
 .../product/product/modules/detail/index.vue  |  1 +
 .../product/modules/detail/modules/header.vue |  3 +-
 .../iot/product/product/modules/form.vue      | 12 +++--
 20 files changed, 96 insertions(+), 92 deletions(-)

diff --git a/apps/web-antd/src/views/iot/device/device/index.vue b/apps/web-antd/src/views/iot/device/device/index.vue
index 153099e79..59ee900d3 100644
--- a/apps/web-antd/src/views/iot/device/device/index.vue
+++ b/apps/web-antd/src/views/iot/device/device/index.vue
@@ -63,17 +63,17 @@ const [DeviceImportFormModal, deviceImportFormModalApi] = useVbenModal({
   destroyOnClose: true,
 });
 
-// 搜索参数
-const searchParams = ref({
+const queryParams = ref({
   deviceName: '',
   nickname: '',
   productId: undefined as number | undefined,
   deviceType: undefined as number | undefined,
   status: undefined as number | undefined,
   groupId: undefined as number | undefined,
-});
+}); // 搜索参数
 
 // 获取字典选项
+// TODO @haohao：直接使用 getDictOptions 哈，不用包装方法；
 const getIntDictOptions = (dictType: string) => {
   return getDictOptions(dictType, 'number');
 };
@@ -81,21 +81,22 @@ const getIntDictOptions = (dictType: string) => {
 /** 搜索 */
 function handleSearch() {
   if (viewMode.value === 'list') {
-    gridApi.formApi.setValues(searchParams.value);
+    gridApi.formApi.setValues(queryParams.value);
     gridApi.query();
   } else {
-    cardViewRef.value?.search(searchParams.value);
+    // todo @haohao：改成 query 方法，更统一；
+    cardViewRef.value?.search(queryParams.value);
   }
 }
 
 /** 重置 */
 function handleReset() {
-  searchParams.value.deviceName = '';
-  searchParams.value.nickname = '';
-  searchParams.value.productId = undefined;
-  searchParams.value.deviceType = undefined;
-  searchParams.value.status = undefined;
-  searchParams.value.groupId = undefined;
+  queryParams.value.deviceName = '';
+  queryParams.value.nickname = '';
+  queryParams.value.productId = undefined;
+  queryParams.value.deviceType = undefined;
+  queryParams.value.status = undefined;
+  queryParams.value.groupId = undefined;
   handleSearch();
 }
 
@@ -110,7 +111,7 @@ function handleRefresh() {
 
 /** 导出表格 */
 async function handleExport() {
-  const data = await exportDeviceExcel(searchParams.value);
+  const data = await exportDeviceExcel(queryParams.value);
   downloadFileFromBlobPart({ fileName: '物联网设备.xls', source: data });
 }
 
@@ -212,7 +213,7 @@ const [Grid, gridApi] = useVbenVxeGrid({
           return await getDevicePage({
             pageNo: page.currentPage,
             pageSize: page.pageSize,
-            ...searchParams.value,
+            ...queryParams.value,
           });
         },
       },
@@ -238,7 +239,7 @@ onMounted(async () => {
   // 处理 productId 参数
   const { productId } = route.query;
   if (productId) {
-    searchParams.value.productId = Number(productId);
+    queryParams.value.productId = Number(productId);
     // 自动触发搜索
     handleSearch();
   }
@@ -256,7 +257,7 @@ onMounted(async () => {
       <!-- 搜索表单 -->
       <div class="mb-3 flex flex-wrap items-center gap-3">
         <Select
-          v-model:value="searchParams.productId"
+          v-model:value="queryParams.productId"
           placeholder="请选择产品"
           allow-clear
           style="width: 200px"
@@ -270,21 +271,21 @@ onMounted(async () => {
           </Select.Option>
         </Select>
         <Input
-          v-model:value="searchParams.deviceName"
+          v-model:value="queryParams.deviceName"
           placeholder="请输入 DeviceName"
           allow-clear
           style="width: 200px"
           @press-enter="handleSearch"
         />
         <Input
-          v-model:value="searchParams.nickname"
+          v-model:value="queryParams.nickname"
           placeholder="请输入备注名称"
           allow-clear
           style="width: 200px"
           @press-enter="handleSearch"
         />
         <Select
-          v-model:value="searchParams.deviceType"
+          v-model:value="queryParams.deviceType"
           placeholder="请选择设备类型"
           allow-clear
           style="width: 200px"
@@ -298,7 +299,7 @@ onMounted(async () => {
           </Select.Option>
         </Select>
         <Select
-          v-model:value="searchParams.status"
+          v-model:value="queryParams.status"
           placeholder="请选择设备状态"
           allow-clear
           style="width: 200px"
@@ -312,7 +313,7 @@ onMounted(async () => {
           </Select.Option>
         </Select>
         <Select
-          v-model:value="searchParams.groupId"
+          v-model:value="queryParams.groupId"
           placeholder="请选择设备分组"
           allow-clear
           style="width: 200px"
@@ -360,6 +361,7 @@ onMounted(async () => {
               auth: ['iot:device:import'],
               onClick: handleImport,
             },
+            // TODO @haohao：应该是选中后，才可用
             {
               label: '添加到分组',
               type: 'primary',
@@ -368,6 +370,7 @@ onMounted(async () => {
               ifShow: () => viewMode === 'list',
               onClick: handleAddToGroup,
             },
+            // TODO @haohao：应该是选中后，才可用；然后，然后 danger 颜色；
             {
               label: '批量删除',
               type: 'primary',
@@ -398,7 +401,7 @@ onMounted(async () => {
       </div>
     </Card>
 
-    <Grid v-show="viewMode === 'list'">
+    <Grid table-title="设备列表" v-show="viewMode === 'list'">
       <template #toolbar-tools>
         <div></div>
       </template>
@@ -469,7 +472,7 @@ onMounted(async () => {
       ref="cardViewRef"
       :products="products"
       :device-groups="deviceGroups"
-      :search-params="searchParams"
+      :search-params="queryParams"
       @create="handleCreate"
       @edit="handleEdit"
       @delete="handleDelete"
diff --git a/apps/web-antd/src/views/iot/device/device/modules/card-view.vue b/apps/web-antd/src/views/iot/device/device/modules/card-view.vue
index 286e1f757..eb831ea8b 100644
--- a/apps/web-antd/src/views/iot/device/device/modules/card-view.vue
+++ b/apps/web-antd/src/views/iot/device/device/modules/card-view.vue
@@ -1,7 +1,8 @@
 <script lang="ts" setup>
+// TODO @haohao：product 的 card-view 的意见，这里看看要不要也改改下。
 import { onMounted, ref } from 'vue';
 
-import { DICT_TYPE } from '@vben/constants';
+import { DeviceStateEnum, DICT_TYPE } from '@vben/constants';
 import { getDictLabel, getDictObj } from '@vben/hooks';
 import { IconifyIcon } from '@vben/icons';
 import { isValidColor, TinyColor } from '@vben/utils';
@@ -18,8 +19,6 @@ import {
   Tooltip,
 } from 'ant-design-vue';
 
-import { DeviceStateEnum } from '@vben/constants';
-
 import { getDevicePage } from '#/api/iot/device/device';
 
 interface Props {
@@ -180,6 +179,7 @@ function getDeviceTypeColor(deviceType: number) {
 }
 
 /** 获取设备状态信息 */
+// TODO @haohao：这里可以简化下么？体感看着有点复杂哈；
 function getStatusInfo(state: null | number | string | undefined) {
   const parsedState = Number(state);
   const hasNumericState = Number.isFinite(parsedState);
@@ -274,7 +274,7 @@ onMounted(() => {
                 <div class="info-item">
                   <span class="info-label">所属产品</span>
                   <a
-                    class="info-value text-primary cursor-pointer"
+                    class="info-value cursor-pointer text-primary"
                     @click="
                       (e) => {
                         e.stopPropagation();
@@ -301,10 +301,7 @@ onMounted(() => {
                 </div>
                 <div class="info-item">
                   <span class="info-label">Deviceid</span>
-                  <Tooltip
-                    :title="item.Deviceid || item.id"
-                    placement="top"
-                  >
+                  <Tooltip :title="item.Deviceid || item.id" placement="top">
                     <span class="info-value device-id cursor-pointer">
                       {{ item.Deviceid || item.id }}
                     </span>
@@ -359,7 +356,7 @@ onMounted(() => {
     </div>
 
     <!-- 分页 -->
-    <div v-if="list.length > 0" class="flex justify-end">
+    <div v-if="list.length > 0" class="mt-3 flex justify-end">
       <Pagination
         v-model:current="queryParams.pageNo"
         v-model:page-size="queryParams.pageSize"
diff --git a/apps/web-antd/src/views/iot/device/device/modules/detail/index.vue b/apps/web-antd/src/views/iot/device/device/modules/detail/index.vue
index 0f7929684..ac1ede8cd 100644
--- a/apps/web-antd/src/views/iot/device/device/modules/detail/index.vue
+++ b/apps/web-antd/src/views/iot/device/device/modules/detail/index.vue
@@ -7,11 +7,10 @@ import { onMounted, ref } from 'vue';
 import { useRoute, useRouter } from 'vue-router';
 
 import { Page } from '@vben/common-ui';
+import { DeviceTypeEnum } from '@vben/constants';
 
 import { message, Tabs } from 'ant-design-vue';
 
-import { DeviceTypeEnum } from '@vben/constants';
-
 import { getDevice } from '#/api/iot/device/device';
 import { getProduct } from '#/api/iot/product/product';
 import { getThingModelListByProductId } from '#/api/iot/thingmodel';
@@ -36,6 +35,8 @@ const device = ref<IotDeviceApi.Device>({} as IotDeviceApi.Device);
 const activeTab = ref('info');
 const thingModelList = ref<ThingModelData[]>([]);
 
+// TODO @haohao：类似 device/detail/index.vue 挪出去哈。
+
 /** 获取设备详情 */
 async function getDeviceData(deviceId: number) {
   loading.value = true;
diff --git a/apps/web-antd/src/views/iot/device/device/modules/detail/modules/config.vue b/apps/web-antd/src/views/iot/device/device/modules/detail/modules/config.vue
index 6fa449022..f24fc0627 100644
--- a/apps/web-antd/src/views/iot/device/device/modules/detail/modules/config.vue
+++ b/apps/web-antd/src/views/iot/device/device/modules/detail/modules/config.vue
@@ -56,14 +56,14 @@ const hasConfigData = computed(() => {
 });
 
 /** 启用编辑模式的函数 */
-function enableEdit() {
+function handleEdit() {
   isEditing.value = true;
   // 重新同步编辑器内容
   configString.value = JSON.stringify(config.value, null, 2);
 }
 
 /** 取消编辑的函数 */
-function cancelEdit() {
+function handleCancelEdit() {
   try {
     config.value = props.device.config ? JSON.parse(props.device.config) : {};
     configString.value = JSON.stringify(config.value, null, 2);
@@ -84,29 +84,23 @@ async function saveConfig() {
     message.error({ content: 'JSON格式错误，请修正后再提交！' });
     return;
   }
-
+  // TODO @haohao：这里要不要做个类似下面的 pushLoading 避免重复提交；
   await updateDeviceConfig();
   isEditing.value = false;
 }
 
 /** 配置推送处理函数 */
 async function handleConfigPush() {
+  pushLoading.value = true;
   try {
-    pushLoading.value = true;
-
     // 调用配置推送接口
     await sendDeviceMessage({
       deviceId: props.device.id!,
       method: IotDeviceMessageMethodEnum.CONFIG_PUSH.method,
       params: config.value,
     });
-
+    // 提示成功
     message.success({ content: '配置推送成功！' });
-  } catch (error) {
-    if (error !== 'cancel') {
-      message.error({ content: '配置推送失败！' });
-      console.error('配置推送错误:', error);
-    }
   } finally {
     pushLoading.value = false;
   }
@@ -124,8 +118,6 @@ async function updateDeviceConfig() {
     message.success({ content: '更新成功！' });
     // 触发 success 事件
     emit('success');
-  } catch (error) {
-    console.error(error);
   } finally {
     loading.value = false;
   }
@@ -143,8 +135,9 @@ async function updateDeviceConfig() {
       class="my-4"
       description="如需编辑文件，请点击下方编辑按钮"
     />
+    <!-- TODO @haohao：应该按钮，是在下方，可以参考 element-plus 的版本 -->
     <div class="mt-5 text-center">
-      <Button v-if="isEditing" @click="cancelEdit">取消</Button>
+      <Button v-if="isEditing" @click="handleCancelEdit">取消</Button>
       <Button
         v-if="isEditing"
         type="primary"
@@ -153,7 +146,7 @@ async function updateDeviceConfig() {
       >
         保存
       </Button>
-      <Button v-else @click="enableEdit">编辑</Button>
+      <Button v-else @click="handleEdit">编辑</Button>
       <Button
         v-if="!isEditing"
         type="primary"
diff --git a/apps/web-antd/src/views/iot/device/device/modules/detail/modules/message.vue b/apps/web-antd/src/views/iot/device/device/modules/detail/modules/message.vue
index 595ee23c0..49168834a 100644
--- a/apps/web-antd/src/views/iot/device/device/modules/detail/modules/message.vue
+++ b/apps/web-antd/src/views/iot/device/device/modules/detail/modules/message.vue
@@ -27,6 +27,8 @@ import { getDeviceMessagePage } from '#/api/iot/device/device';
 import { DictTag } from '#/components/dict-tag';
 import { IotDeviceMessageMethodEnum } from '#/views/iot/utils/constants';
 
+// TODO @haohao：看看能不能调整成 Grid 风格~方便 element-plus 的迁移
+
 const props = defineProps<{
   deviceId: number;
 }>();
diff --git a/apps/web-antd/src/views/iot/device/device/modules/detail/modules/simulator.vue b/apps/web-antd/src/views/iot/device/device/modules/detail/modules/simulator.vue
index 0679da758..2b65f9bdf 100644
--- a/apps/web-antd/src/views/iot/device/device/modules/detail/modules/simulator.vue
+++ b/apps/web-antd/src/views/iot/device/device/modules/detail/modules/simulator.vue
@@ -341,6 +341,7 @@ async function handleServiceInvoke(row: ThingModelData) {
 <template>
   <ContentWrap>
     <!-- 上方：指令调试区域 -->
+    <!-- TODO @haohao：要不要改成左右； -->
     <Card class="simulator-tabs mb-4">
       <template #title>
         <div class="flex items-center justify-between">
diff --git a/apps/web-antd/src/views/iot/device/device/modules/detail/modules/sub-device.vue b/apps/web-antd/src/views/iot/device/device/modules/detail/modules/sub-device.vue
index 5345b4f37..a2551782b 100644
--- a/apps/web-antd/src/views/iot/device/device/modules/detail/modules/sub-device.vue
+++ b/apps/web-antd/src/views/iot/device/device/modules/detail/modules/sub-device.vue
@@ -3,6 +3,8 @@ import { onMounted, ref } from 'vue';
 
 import { Card, Empty } from 'ant-design-vue';
 
+// TODO @haohao：这里要实现一把么？
+
 interface Props {
   deviceId: number;
 }
diff --git a/apps/web-antd/src/views/iot/device/device/modules/detail/modules/thing-model-event.vue b/apps/web-antd/src/views/iot/device/device/modules/detail/modules/thing-model-event.vue
index 979d73bcb..3c94c2a7f 100644
--- a/apps/web-antd/src/views/iot/device/device/modules/detail/modules/thing-model-event.vue
+++ b/apps/web-antd/src/views/iot/device/device/modules/detail/modules/thing-model-event.vue
@@ -1,5 +1,6 @@
 <!-- 设备事件管理 -->
 <script lang="ts" setup>
+// TODO @haohao：看看能不能用 Grid 实现下，方便 element-plus 迁移
 import type { ThingModelData } from '#/api/iot/thingmodel';
 
 import { computed, onMounted, reactive, ref } from 'vue';
diff --git a/apps/web-antd/src/views/iot/device/device/modules/detail/modules/thing-model-property-history.vue b/apps/web-antd/src/views/iot/device/device/modules/detail/modules/thing-model-property-history.vue
index 930fcaabe..9c4bdd184 100644
--- a/apps/web-antd/src/views/iot/device/device/modules/detail/modules/thing-model-property-history.vue
+++ b/apps/web-antd/src/views/iot/device/device/modules/detail/modules/thing-model-property-history.vue
@@ -24,9 +24,8 @@ import {
 } from 'ant-design-vue';
 import dayjs from 'dayjs';
 
-import ShortcutDateRangePicker from '#/components/shortcut-date-range-picker/shortcut-date-range-picker.vue';
-
 import { getHistoryDevicePropertyList } from '#/api/iot/device/device';
+import ShortcutDateRangePicker from '#/components/shortcut-date-range-picker/shortcut-date-range-picker.vue';
 import { IoTDataSpecsDataTypeEnum } from '#/views/iot/utils/constants';
 
 /** IoT 设备属性历史数据详情 */
@@ -43,16 +42,10 @@ const total = ref(0); // 总数据量
 const thingModelDataType = ref<string>(''); // 物模型数据类型
 const propertyIdentifier = ref<string>(''); // 属性标识符
 
-/** 时间范围（仅日期，不包含时分秒） */
 const dateRange = ref<[string, string]>([
   dayjs().subtract(6, 'day').format('YYYY-MM-DD'),
   dayjs().format('YYYY-MM-DD'),
-]);
-
-/** 将日期范围转换为带时分秒的格式 */
-function formatDateRangeWithTime(dates: [string, string]): [string, string] {
-  return [`${dates[0]} 00:00:00`, `${dates[1]} 23:59:59`];
-}
+]); // 时间范围（仅日期，不包含时分秒）
 
 const queryParams = reactive({
   deviceId: -1,
@@ -64,23 +57,21 @@ const queryParams = reactive({
 const chartRef = ref<EchartsUIType>();
 const { renderEcharts } = useEcharts(chartRef);
 
-// 判断是否为复杂数据类型（struct 或 array）
 const isComplexDataType = computed(() => {
   if (!thingModelDataType.value) return false;
   return [
     IoTDataSpecsDataTypeEnum.ARRAY,
     IoTDataSpecsDataTypeEnum.STRUCT,
   ].includes(thingModelDataType.value as any);
-});
+}); // 判断是否为复杂数据类型（struct 或 array）
 
-// 统计数据
 const maxValue = computed(() => {
   if (isComplexDataType.value || list.value.length === 0) return '-';
   const values = list.value
     .map((item) => Number(item.value))
     .filter((v) => !Number.isNaN(v));
   return values.length > 0 ? Math.max(...values).toFixed(2) : '-';
-});
+}); // 统计数据
 
 const minValue = computed(() => {
   if (isComplexDataType.value || list.value.length === 0) return '-';
@@ -100,6 +91,11 @@ const avgValue = computed(() => {
   return (sum / values.length).toFixed(2);
 });
 
+/** 将日期范围转换为带时分秒的格式 */
+function formatDateRangeWithTime(dates: [string, string]): [string, string] {
+  return [`${dates[0]} 00:00:00`, `${dates[1]} 23:59:59`];
+}
+
 // 表格列配置
 const tableColumns = computed(() => [
   {
@@ -409,7 +405,9 @@ defineExpose({ open }); // 提供 open 方法，用于打开弹窗
         <Space :size="12" class="w-full" wrap>
           <!-- 时间选择 -->
           <div class="flex items-center gap-3">
-            <span class="whitespace-nowrap text-sm text-gray-500">时间范围</span>
+            <span class="whitespace-nowrap text-sm text-gray-500">
+              时间范围
+            </span>
             <ShortcutDateRangePicker @change="handleDateRangeChange" />
           </div>
 
@@ -531,7 +529,7 @@ defineExpose({ open }); // 提供 open 方法，用于打开弹窗
   .chart-container,
   .table-container {
     padding: 16px;
-    background-color: hsl(var(--card));
+    background-color: hsl(var(--card)); // TODO @haohao：看看这个能不能 fix 下~ idea 爆红了；
     border: 1px solid hsl(var(--border) / 60%);
     border-radius: 8px;
   }
diff --git a/apps/web-antd/src/views/iot/device/device/modules/detail/modules/thing-model-property.vue b/apps/web-antd/src/views/iot/device/device/modules/detail/modules/thing-model-property.vue
index 498bb070b..0849fd05a 100644
--- a/apps/web-antd/src/views/iot/device/device/modules/detail/modules/thing-model-property.vue
+++ b/apps/web-antd/src/views/iot/device/device/modules/detail/modules/thing-model-property.vue
@@ -1,5 +1,6 @@
 <!-- 设备属性管理 -->
 <script lang="ts" setup>
+// TODO @haohao：看看能不能用 Grid 实现下，方便 element-plus 迁移
 import type { IotDeviceApi } from '#/api/iot/device/device';
 
 import { onBeforeUnmount, onMounted, reactive, ref, watch } from 'vue';
diff --git a/apps/web-antd/src/views/iot/device/device/modules/detail/modules/thing-model-service.vue b/apps/web-antd/src/views/iot/device/device/modules/detail/modules/thing-model-service.vue
index bbda06a90..492af4495 100644
--- a/apps/web-antd/src/views/iot/device/device/modules/detail/modules/thing-model-service.vue
+++ b/apps/web-antd/src/views/iot/device/device/modules/detail/modules/thing-model-service.vue
@@ -1,5 +1,6 @@
 <!-- 设备服务调用 -->
 <script lang="ts" setup>
+// TODO @haohao：看看能不能调整成 Grid 风格~方便 element-plus 的迁移
 import type { ThingModelData } from '#/api/iot/thingmodel';
 
 import { computed, onMounted, reactive, ref } from 'vue';
diff --git a/apps/web-antd/src/views/iot/device/device/modules/form.vue b/apps/web-antd/src/views/iot/device/device/modules/form.vue
index 2994e8d00..3cc059283 100644
--- a/apps/web-antd/src/views/iot/device/device/modules/form.vue
+++ b/apps/web-antd/src/views/iot/device/device/modules/form.vue
@@ -8,11 +8,7 @@ import { useVbenModal } from '@vben/common-ui';
 import { message } from 'ant-design-vue';
 
 import { useVbenForm } from '#/adapter/form';
-import {
-  createDevice,
-  getDevice,
-  updateDevice,
-} from '#/api/iot/device/device';
+import { createDevice, getDevice, updateDevice } from '#/api/iot/device/device';
 import { $t } from '#/locales';
 
 import { useFormSchema } from '../data';
@@ -40,7 +36,6 @@ const [Form, formApi] = useVbenForm({
 });
 
 const [Modal, modalApi] = useVbenModal({
-  /** 提交表单 */
   async onConfirm() {
     const { valid } = await formApi.validate();
     if (!valid) {
@@ -51,6 +46,7 @@ const [Modal, modalApi] = useVbenModal({
     const data = (await formApi.getValues()) as IotDeviceApi.Device;
     try {
       await (formData.value?.id ? updateDevice(data) : createDevice(data));
+      // 关闭并提示
       await modalApi.close();
       emit('success');
       message.success($t('ui.actionMessage.operationSuccess'));
@@ -58,7 +54,6 @@ const [Modal, modalApi] = useVbenModal({
       modalApi.unlock();
     }
   },
-  /** 弹窗打开/关闭 */
   async onOpenChange(isOpen: boolean) {
     if (!isOpen) {
       formData.value = undefined;
@@ -68,6 +63,7 @@ const [Modal, modalApi] = useVbenModal({
     const data = modalApi.getData<IotDeviceApi.Device>();
     if (!data || !data.id) {
       // 新增模式：设置默认值（如果需要）
+      // TODO @haohao：是不是 return 就好啦；不用这里 undefined 啦；
       formData.value = undefined;
       return;
     }
diff --git a/apps/web-antd/src/views/iot/device/device/modules/group-form.vue b/apps/web-antd/src/views/iot/device/device/modules/group-form.vue
index 86b37032a..38c3057e1 100644
--- a/apps/web-antd/src/views/iot/device/device/modules/group-form.vue
+++ b/apps/web-antd/src/views/iot/device/device/modules/group-form.vue
@@ -29,7 +29,6 @@ const [Form, formApi] = useVbenForm({
 });
 
 const [Modal, modalApi] = useVbenModal({
-  /** 提交表单 */
   async onConfirm() {
     const { valid } = await formApi.validate();
     if (!valid) {
@@ -43,6 +42,7 @@ const [Modal, modalApi] = useVbenModal({
         ids: deviceIds.value,
         groupIds: data.groupIds as number[],
       });
+      // 关闭并提示
       await modalApi.close();
       emit('success');
       message.success($t('ui.actionMessage.operationSuccess'));
@@ -50,7 +50,6 @@ const [Modal, modalApi] = useVbenModal({
       modalApi.unlock();
     }
   },
-  /** 弹窗打开/关闭 */
   async onOpenChange(isOpen: boolean) {
     if (!isOpen) {
       deviceIds.value = [];
diff --git a/apps/web-antd/src/views/iot/product/category/modules/form.vue b/apps/web-antd/src/views/iot/product/category/modules/form.vue
index df2290639..1076767b0 100644
--- a/apps/web-antd/src/views/iot/product/category/modules/form.vue
+++ b/apps/web-antd/src/views/iot/product/category/modules/form.vue
@@ -69,6 +69,7 @@ const [Modal, modalApi] = useVbenModal({
     const data = modalApi.getData<IotProductCategoryApi.ProductCategory>();
     if (!data || !data.id) {
       // 新增模式：设置默认值
+      // TODO @AI：可以参考部门，进一步简化代码；通过 defaultValue 在 schema 里设置默认值
       formData.value = undefined;
       await formApi.setValues({
         sort: 0,
diff --git a/apps/web-antd/src/views/iot/product/product/data.ts b/apps/web-antd/src/views/iot/product/product/data.ts
index 57d2c3818..e9e7809bf 100644
--- a/apps/web-antd/src/views/iot/product/product/data.ts
+++ b/apps/web-antd/src/views/iot/product/product/data.ts
@@ -21,6 +21,7 @@ async function loadCategoryData() {
 }
 
 // 初始化加载分类数据
+// TODO @haohao：可以参考 /Users/yunai/Java/yudao-ui-admin-vben-v5/apps/web-antd/src/views/system/tenant/data.ts 简洁一点。
 loadCategoryData();
 
 /** 新增/修改产品的表单 */
diff --git a/apps/web-antd/src/views/iot/product/product/index.vue b/apps/web-antd/src/views/iot/product/product/index.vue
index 421514c36..da7930c82 100644
--- a/apps/web-antd/src/views/iot/product/product/index.vue
+++ b/apps/web-antd/src/views/iot/product/product/index.vue
@@ -7,13 +7,12 @@ import { onMounted, ref } from 'vue';
 import { useRouter } from 'vue-router';
 
 import { Page, useVbenModal } from '@vben/common-ui';
+import { ProductStatusEnum } from '@vben/constants';
 import { IconifyIcon } from '@vben/icons';
 import { downloadFileFromBlobPart } from '@vben/utils';
 
 import { Button, Card, Input, message, Space } from 'ant-design-vue';
 
-import { ProductStatusEnum } from '@vben/constants';
-
 import { ACTION_ICON, TableAction, useVbenVxeGrid } from '#/adapter/vxe-table';
 import { getSimpleProductCategoryList } from '#/api/iot/product/category';
 import {
@@ -33,7 +32,7 @@ const router = useRouter();
 const categoryList = ref<IotProductCategoryApi.ProductCategory[]>([]);
 const viewMode = ref<'card' | 'list'>('card');
 const cardViewRef = ref();
-const searchParams = ref({
+const queryParams = ref({
   name: '',
   productKey: '',
 }); // 搜索参数
@@ -51,17 +50,18 @@ async function loadCategories() {
 /** 搜索产品 */
 function handleSearch() {
   if (viewMode.value === 'list') {
-    gridApi.formApi.setValues(searchParams.value);
+    gridApi.formApi.setValues(queryParams.value);
     gridApi.query();
   } else {
-    cardViewRef.value?.search(searchParams.value);
+    // TODO @haohao：要不 search 也改成 query 方法，更统一一点哈。
+    cardViewRef.value?.search(queryParams.value);
   }
 }
 
 /** 重置搜索 */
 function handleReset() {
-  searchParams.value.name = '';
-  searchParams.value.productKey = '';
+  queryParams.value.name = '';
+  queryParams.value.productKey = '';
   handleSearch();
 }
 
@@ -76,7 +76,7 @@ function handleRefresh() {
 
 /** 导出表格 */
 async function handleExport() {
-  const data = await exportProduct(searchParams.value);
+  const data = await exportProduct(queryParams.value);
   downloadFileFromBlobPart({ fileName: '产品列表.xls', source: data });
 }
 
@@ -133,7 +133,7 @@ const [Grid, gridApi] = useVbenVxeGrid({
           return await getProductPage({
             pageNo: page.currentPage,
             pageSize: page.pageSize,
-            ...searchParams.value,
+            ...queryParams.value,
           });
         },
       },
@@ -164,7 +164,7 @@ onMounted(() => {
       <!-- 搜索表单 -->
       <div class="mb-3 flex items-center gap-3">
         <Input
-          v-model:value="searchParams.name"
+          v-model:value="queryParams.name"
           placeholder="请输入产品名称"
           allow-clear
           class="w-[220px]"
@@ -175,7 +175,7 @@ onMounted(() => {
           </template>
         </Input>
         <Input
-          v-model:value="searchParams.productKey"
+          v-model:value="queryParams.productKey"
           placeholder="请输入产品标识"
           allow-clear
           class="w-[220px]"
@@ -230,7 +230,7 @@ onMounted(() => {
       </div>
     </Card>
 
-    <Grid v-show="viewMode === 'list'">
+    <Grid table-title="产品列表" v-show="viewMode === 'list'">
       <template #actions="{ row }">
         <TableAction
           :actions="[
@@ -271,14 +271,13 @@ onMounted(() => {
       v-show="viewMode === 'card'"
       ref="cardViewRef"
       :category-list="categoryList"
-      :search-params="searchParams"
+      :search-params="queryParams"
       @create="handleCreate"
       @edit="handleEdit"
       @delete="handleDelete"
       @detail="openProductDetail"
       @thing-model="openThingModel"
     />
-
   </Page>
 </template>
 <style scoped>
diff --git a/apps/web-antd/src/views/iot/product/product/modules/card-view.vue b/apps/web-antd/src/views/iot/product/product/modules/card-view.vue
index 300042b89..ac297355f 100644
--- a/apps/web-antd/src/views/iot/product/product/modules/card-view.vue
+++ b/apps/web-antd/src/views/iot/product/product/modules/card-view.vue
@@ -137,6 +137,7 @@ onMounted(() => {
                 </div>
                 <div class="info-item">
                   <span class="info-label">产品类型</span>
+                  <!-- TODO @AI：这个要不完全用字典的 dict-tag？ -->
                   <Tag
                     :color="getDeviceTypeColor(item.deviceType)"
                     class="info-tag m-0"
@@ -231,7 +232,7 @@ onMounted(() => {
     </div>
 
     <!-- 分页 -->
-    <div v-if="list.length > 0" class="flex justify-end">
+    <div v-if="list.length > 0" class="mt-3 flex justify-end">
       <Pagination
         v-model:current="queryParams.pageNo"
         v-model:page-size="queryParams.pageSize"
@@ -266,6 +267,7 @@ onMounted(() => {
       width: 36px;
       height: 36px;
       color: white;
+      // TODO @haohao：这里的紫色，和下面的紫色按钮，看看能不能换下。嘿嘿，感觉 AI 比较喜欢用紫色，但是放现有的后台，有点突兀
       background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
       border-radius: 8px;
     }
diff --git a/apps/web-antd/src/views/iot/product/product/modules/detail/index.vue b/apps/web-antd/src/views/iot/product/product/modules/detail/index.vue
index 5fc1fc7bd..1769c8017 100644
--- a/apps/web-antd/src/views/iot/product/product/modules/detail/index.vue
+++ b/apps/web-antd/src/views/iot/product/product/modules/detail/index.vue
@@ -28,6 +28,7 @@ const activeTab = ref('info');
 provide('product', product); // 提供产品信息给子组件
 
 /** 获取产品详情 */
+// TODO @haohao：因为 detail 是独立界面，所以不放在 modules 里，应该放在 web-antd/src/views/iot/product/product/detail/index.vue 里，更合理一些哈。
 async function getProductData(productId: number) {
   loading.value = true;
   try {
diff --git a/apps/web-antd/src/views/iot/product/product/modules/detail/modules/header.vue b/apps/web-antd/src/views/iot/product/product/modules/detail/modules/header.vue
index 62df0cae1..e298afe1d 100644
--- a/apps/web-antd/src/views/iot/product/product/modules/detail/modules/header.vue
+++ b/apps/web-antd/src/views/iot/product/product/modules/detail/modules/header.vue
@@ -4,11 +4,10 @@ import type { IotProductApi } from '#/api/iot/product/product';
 import { useRouter } from 'vue-router';
 
 import { useVbenModal } from '@vben/common-ui';
+import { ProductStatusEnum } from '@vben/constants';
 
 import { Button, Card, Descriptions, message, Modal } from 'ant-design-vue';
 
-import { ProductStatusEnum } from '@vben/constants';
-
 import { updateProductStatus } from '#/api/iot/product/product';
 
 import Form from '../../form.vue';
diff --git a/apps/web-antd/src/views/iot/product/product/modules/form.vue b/apps/web-antd/src/views/iot/product/product/modules/form.vue
index ca59e864b..1ead43b64 100644
--- a/apps/web-antd/src/views/iot/product/product/modules/form.vue
+++ b/apps/web-antd/src/views/iot/product/product/modules/form.vue
@@ -40,6 +40,7 @@ const [Form, formApi] = useVbenForm({
   wrapperClass: 'grid-cols-2',
 });
 
+// TODO @haohao：这个要不还是一行一个？这样样式好看点哈。
 const [AdvancedForm, advancedFormApi] = useVbenForm({
   commonConfig: {
     componentProps: { class: 'w-full' },
@@ -51,10 +52,10 @@ const [AdvancedForm, advancedFormApi] = useVbenForm({
 });
 
 /** 基础表单需要 formApi 引用，所以通过 setState 设置 schema */
+// TODO haohao：@haohao：要不要把 generateProductKey 拿到这个 vue 里，作为参数传递到 useBasicFormSchema 里？
 formApi.setState({ schema: useBasicFormSchema(formApi) });
 
 const [Modal, modalApi] = useVbenModal({
-  /** 提交表单 */
   async onConfirm() {
     const { valid } = await formApi.validate();
     if (!valid) {
@@ -63,6 +64,7 @@ const [Modal, modalApi] = useVbenModal({
     modalApi.lock();
     // 合并两个表单的值
     const basicValues = await formApi.getValues();
+    // TODO @haohao：有 linter 修复下；“formData.value?.id”；另外，这里直接两个表单合并，是不是就可以了呀？因为 2 个 schema 本身不同，字段就不同，不会冲突。
     const advancedValues = activeKey.value.includes('advanced')
       ? await advancedFormApi.getValues()
       : formData.value?.id
@@ -85,7 +87,6 @@ const [Modal, modalApi] = useVbenModal({
       modalApi.unlock();
     }
   },
-  /** 弹窗打开/关闭 */
   async onOpenChange(isOpen: boolean) {
     if (!isOpen) {
       formData.value = undefined;
@@ -96,9 +97,11 @@ const [Modal, modalApi] = useVbenModal({
     const data = modalApi.getData<IotProductApi.Product>();
     if (!data || !data.id) {
       // 新增：设置默认值
+      // TODO @AI：
       await formApi.setValues({
+        // TODO @haohao：要不要把 generateProductKey 拿到这个 vue 里，作为参数传递到 useBasicFormSchema 里？
         productKey: generateProductKey(),
-        status: 0,
+        status: 0, // TODO @haohao：通过 defaultValue 即可；
       });
       return;
     }
@@ -108,12 +111,15 @@ const [Modal, modalApi] = useVbenModal({
       formData.value = await getProduct(data.id);
       await formApi.setValues(formData.value);
       // 设置高级表单（不等待）
+      // TODO @haohao：直接把 formData 传过去？没关系的哈。因为会 filter 掉不存在的值，可以试试哈。
+      // TODO @haohao：这里是不是要 await 下呀？有黄色的告警；
       advancedFormApi.setValues({
         icon: formData.value.icon,
         picUrl: formData.value.picUrl,
         description: formData.value.description,
       });
       // 有高级字段时自动展开
+      // TODO @haohao：默认不用展开哈。
       if (
         formData.value.icon ||
         formData.value.picUrl ||