Files
web-Iot/.trae/documents/add-rule-config-tab.md

201 lines
7.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 在 systemSetting/systemMaintenance 下新增「规则配置」Tab
## Context
当前「系统维护」页面已有「故障码管理」「告警设置」「工单设置」三个 Tab。用户希望在 `systemSetting/systemMaintenance` 页面下再新增一个「规则配置」Tab,用于管理场站的自动规则(autoRule)。该功能复用 `src/api/rule.tsx` 中的接口:
- `selectRuleBySiteId`:`GET /system/autoRule/selectBySiteId`
- `updateTriggerRule`:`POST /system/autoRule/save`(新增/编辑共用,按 `id` 区分)
- `deleteRule`:`POST /system/autoRule/delete`
后端实体结构(用户提供)包含 `ruleName`、`ruleType`、`deviceScope`、`conditions`(`TriggerConditions` JSON)、`actionConfig`(`ActionConfig` JSON)、`enabled`、`ForceExecute`。
## 目标
在 `SystemMaintenancePage` 增加「规则配置」Tab,点击后展示 `RuleConfigManagement` 组件:支持按场站查询规则列表、新增/编辑/查看/删除规则。
## 方案
### 1. 组件拆分
新增文件:`src/components/SystemSetting/RuleConfigManagement.tsx`
复用 `ErrorManagement.tsx` 的成熟模式:
- `Form` 搜索区(规则名称、规则类型、启用状态)
- `Table` 列表展示
- `Modal` + `Form` 新增/编辑/查看详情
### 2. 修改 SystemMaintain.tsx
在 `src/components/SystemSetting/SystemMaintain.tsx` 中:
- 在 `activeSubTab` 初始化 `useEffect` 的白名单里新增 `'rule'`。
- 在 `Tabs` 中新增一个 `TabPane`,key 为 `'rule'`,tab 文案使用 `t('systemSetting.ruleConfig')`。
- 条件渲染 `{activeSubTab === 'rule' && <RuleConfigManagement />}`。
- 引入新组件 `RuleConfigManagement`。
### 3. 接口调用
在 `RuleConfigManagement.tsx` 中引入:
```tsx
import {
updateTriggerRule,
selectRuleBySiteId,
deleteRule,
} from '@/api/rule';
```
- 列表:`selectRuleBySiteId({ siteId: stationId })`,兼容 `res.data` / `res.rows`。
- 保存:`updateTriggerRule(submitData)`,包含 `id`(编辑时)、`ruleName`、`ruleType`、`deviceScope`、`conditions`、`actionConfig`、`enabled`、`ForceExecute`、`orgId`、`siteId`。
- 删除:`deleteRule({ ids: [record.id] })`。
### 4. 前端枚举/选项
由于用户只给出 Java 实体,前端需要定义以下选项(放在组件内或 `src/lib/utils.ts`):
- `RuleTypeOptions`:
- `LOW_BATTERY_RETURN`:低电量返航
- 预留更多 key,方便后续扩展。
- `DeviceScopeOptions`:
- `ALL`:所有设备
- `GROUP`:设备组
- `SOME`:特定的设备
- `ActionTypeOptions`:
- `AUTO_TASK`:路径规划任务
- `SEND_COMMAND`:下发指令
- `ALARM`:告警
- `WORK_ORDER`:工单下发
- `TriggerKeyOptions`:
- `battery`:电量
- `temperature`:温度
- `offline_duration`:离线时长
- `voltage`:电压
- 比较运算符:直接复用现有 `CompareEnumOptions`(EQ/NEQ/GT/LT/GTE/LTE/BETWEEN/NOT_BETWEEN)。
> 考虑到项目现有 `CompareEnumOptions` 使用 `i18n.t('constants.xxx')` 作为 label,规则相关枚举 label 也统一使用 `t('systemSetting.xxx')`,并在 `zh/index.ts` 与 `en/index.ts` 的 `systemSetting` 命名空间下补充 key。
### 5. 表单设计
#### 列表搜索区
- 规则名称(Input)
- 规则类型(Select)
- 启用状态(Select:启用/禁用)
#### Modal 表单字段
- `ruleName`:Input,必填
- `ruleType`:Select(`RuleTypeOptions`),必填,默认 `LOW_BATTERY_RETURN`
- `deviceScope`:Select(`DeviceScopeOptions`),必填
- `conditions.key`:Select(`TriggerKeyOptions`)
- `conditions.operator`:Select(`CompareEnumOptions`)
- `conditions.value`:InputNumber / Input
- 若 operator 为区间(`BETWEEN` / `NOT_BETWEEN`),拆分为 `min` / `max`,保存时拼接为 `value`(如 `"20,80"`)。
- `actionConfig.actionType`:Select(`ActionTypeOptions`)
- `actionConfig.args`:动态表单(根据 `actionType` 显示不同字段)。
- 第一阶段先提供通用 `Map<String, Object>` 文本域或一组 key-value 输入。
- 若时间允许,可针对 `AUTO_TASK` 提供「选择路径」下拉。
- `enabled`:Switch(1/0 或 true/false,按后端实际类型转换)
- `ForceExecute`:Switch
### 6. 数据结构
提交时组装为:
```tsx
const submitData = {
id: modalType === 'edit' ? currentRecord.id : undefined,
ruleName: values.ruleName,
ruleType: values.ruleType,
deviceScope: values.deviceScope,
conditions: {
key: values.key,
operator: values.operator,
value: values.operator === 'BETWEEN' || values.operator === 'NOT_BETWEEN'
? `${values.min},${values.max}`
: values.value,
},
actionConfig: {
actionType: values.actionType,
args: values.args || {},
},
enabled: values.enabled ? 1 : 0, // 或 true/false,按后端 Boolean
ForceExecute: values.ForceExecute ? 1 : 0,
orgId: currentStation?.orgId || '',
siteId: stationId || '',
};
```
> 后端 `enabled` / `ForceExecute` 为 `Boolean`,若后端接受 JSON boolean 可直接传 `true/false`;若接受 0/1 则按实际接口调整。
### 7. i18n 补充
在 `src/locales/zh/index.ts` 与 `src/locales/en/index.ts` 的 `systemSetting` 命名空间下新增:
```ts
ruleConfig: '规则配置',
ruleName: '规则名称',
ruleType: '规则类型',
ruleTypeLowBatteryReturn: '低电量返航',
deviceScope: '适用范围',
deviceScopeAll: '所有设备',
deviceScopeGroup: '设备组',
deviceScopeSome: '特定设备',
triggerKey: '触发字段',
triggerKeyBattery: '电量',
triggerKeyTemperature: '温度',
triggerKeyOfflineDuration: '离线时长',
triggerKeyVoltage: '电压',
operator: '比较运算符',
triggerValue: '阈值',
actionType: '执行动作',
actionTypeAutoTask: '路径规划任务',
actionTypeSendCommand: '下发指令',
actionTypeAlarm: '告警',
actionTypeWorkOrder: '工单下发',
actionArgs: '动作参数',
enabled: '是否启用',
forceExecute: '强制执行',
pleaseInputRuleName: '请输入规则名称',
pleaseSelectRuleType: '请选择规则类型',
pleaseSelectDeviceScope: '请选择适用范围',
pleaseSelectTriggerKey: '请选择触发字段',
pleaseSelectOperator: '请选择比较运算符',
pleaseInputTriggerValue: '请输入阈值',
pleaseSelectActionType: '请选择执行动作',
ruleList: '规则列表',
addRule: '新增规则',
editRule: '编辑规则',
viewRule: '查看规则',
```
### 8. 表格列
| 列名 | 字段 | 说明 |
|---|---|---|
| 规则名称 | ruleName | - |
| 规则类型 | ruleType | 使用 `RuleTypeOptions` 渲染 label |
| 适用范围 | deviceScope | 使用 `DeviceScopeOptions` 渲染 |
| 触发条件 | conditions | 渲染为 `key operator value` 文本 |
| 执行动作 | actionConfig.actionType | 使用 `ActionTypeOptions` 渲染 |
| 启用 | enabled | Switch 或 Tag |
| 强制 | ForceExecute | Tag |
| 操作 | action | 查看/编辑/删除 |
## 关键文件
- `src/components/SystemSetting/SystemMaintain.tsx`:新增 Tab 入口
- `src/components/SystemSetting/RuleConfigManagement.tsx`:新增规则配置组件
- `src/api/rule.tsx`:复用已有接口
- `src/locales/zh/index.ts`:中文 i18n
- `src/locales/en/index.ts`:英文 i18n
## 验证
1. 启动项目,进入「系统设置」→「系统维护」。
2. 确认出现「规则配置」Tab。
3. 列表为空时显示空状态;若已有规则则正确展示。
4. 点击「新增」打开弹窗,填写后保存,调用 `/system/autoRule/save`。
5. 编辑已有规则,确认表单回填正确(区间值拆分为 min/max)。
6. 删除规则,确认调用 `/system/autoRule/delete`。
7. 切换站点后,列表按 `siteId` 重新加载。
8. 运行 `npx esbuild src/components/SystemSetting/RuleConfigManagement.tsx --outfile=_tmp_rule.js --log-level=warning` 校验语法。