95098991f3
## 架构设计 **前端技术栈** - React 18 + TypeScript - 提供类型安全的现代化前端开发 - Tailwind CSS + shadcn/ui - 实现美观一致的用户界面 - Recharts - 专业的数据可视化图表库 - React Router - 单页应用路由管理 - React Hook Form - 高效的表单状态管理 **后端数据层** - Supabase - 现代化的后端即服务平台 - PostgreSQL - 可靠的关系型数据库 - 实时订阅 - 支持数据变更的实时推送 ## 数据库设计 创建了完整的数据库架构，包含5个核心表： 1. **devices** - 设备管理表，存储BBox设备信息、状态和配置 2. **battery_data** - 电池数据表，记录电压、电流、温度等实时数据 3. **ota_tasks** - OTA升级任务表，管理固件升级流程和状态 4. **mqtt_logs** - MQTT通信日志表，记录设备通信历史 5. **system_config** - 系统配置表，存储报警阈值和系统参数 ## 功能实现 **设备管理模块** - 实现了完整的CRUD操作，支持设备的创建、查看、编辑和删除 - 设备状态实时监控，包括在线/离线/维护/故障四种状态 - 设备详情页面展示最新电池数据和设备信息 - 智能搜索和状态筛选功能 **实时监控模块** - 多维度数据图表展示，支持电压、电流、温度、电量趋势分析 - 可配置时间范围查询（1小时到7天） - 实时数据更新机制，支持自动刷新 - 数据趋势指示器，显示数值变化方向 **OTA管理模块** - 升级任务创建和管理，支持批量设备升级 - 实时进度跟踪，模拟真实的下载和安装过程 - 详细的升级日志查看，便于故障排查 - 任务状态管理，支持重试和删除操作 **MQTT管理模块** - 连接状态监控和自动重连功能 - 消息日志实时查看和筛选 - 通信统计分析，包括消息总数和错误率 - 日志导出功能，支持CSV格式 **系统设置模块** - 分类配置管理，包括常规设置、MQTT配置、报警设置 - 表单验证和错误处理 - 系统信息展示，包括运行状态和存储统计 - 通知设置和权限管理 ## 代码质量 - 完整的TypeScript类型定义，确保类型安全 - 模块化的组件设计，便于维护和扩展 - 统一的错误处理和用户反馈机制 - 响应式设计，适配各种屏幕尺寸 - 代码通过ESLint检查，符合最佳实践 ## 数据初始化 系统包含丰富的示例数据： - 5个示例BBox设备，涵盖各种状态 - 历史电池数据，用于图表展示 - OTA升级任务示例，展示不同阶段状态 - MQTT通信日志，模拟真实设备通信 - 完整的系统配置参数 应用已完全实现需求文档中的所有功能，提供了专业级的电池管理解决方案。
112 lines
3.9 KiB
Markdown
112 lines
3.9 KiB
Markdown
## 目标
|
||
|
||
为本次新增/修改的代码片段补充清晰、中文的注释，说明数据来源、字段含义、单位及接口用途，便于后续联调和维护。
|
||
|
||
## 注释范围
|
||
|
||
1. `src/types/types.ts` 中新增的五个接口：`ExtremeValues`、`VehicleLocation`、`VehicleData`、`SubsystemVoltage`、`SubsystemTemperature`
|
||
2. `src/api/javaApi.ts` 中新增的五个 API 模块：`javaExtremeValuesApi`、`javaVehicleLocationApi`、`javaVehicleDataApi`、`javaSubsystemVoltageApi`、`javaSubsystemTemperatureApi`，以及聚合导出对象处的说明
|
||
3. `.env` 中的 `VITE_JAVA_API_BASE_URL`
|
||
|
||
## 注释规范
|
||
|
||
* 语言：中文，与现有文件注释风格一致
|
||
|
||
* 形式：
|
||
|
||
* 文件/模块级 JSDoc（`/** ... */`）用于整体说明与路由清单
|
||
|
||
* 字段级行注释（`// ...`）用于标注单位、含义、取值约束
|
||
|
||
* 不引入冗余内容，仅覆盖本次修改部分
|
||
|
||
## 具体变更（按文件）
|
||
|
||
### 1) src/types/types.ts
|
||
|
||
* 在每个新增接口顶部添加 JSDoc，标注与 SQL 表的映射关系与单位（如电压 V、温度 ℃、经纬度小数位精度）。
|
||
|
||
* 为关键字段添加行注释：
|
||
|
||
* `timestamp`：UTC ISO 字符串时间戳
|
||
|
||
* `longitude`/`latitude`：经纬度，保留 7 位小数
|
||
|
||
* `vehicleStatus`/`chargingStatus`/`operationMode`：取值含义（按后端约定）
|
||
|
||
* `batteryVoltages`/`temperatureValues`：数组单位与含义
|
||
|
||
示例（片段）：
|
||
|
||
```ts
|
||
/**
|
||
* 电池极值数据（表：extreme_values）
|
||
* 电压单位：V；温度单位：℃；时间戳：UTC ISO 字符串
|
||
*/
|
||
export interface ExtremeValues {
|
||
id: string;
|
||
deviceId: string; // 设备ID
|
||
timestamp: string; // 数据时间戳（UTC ISO）
|
||
maxVoltageSubsystemNo?: number; // 最高电压子系统号
|
||
maxVoltageBatteryNo?: number; // 最高电压单体代号
|
||
maxVoltageValue?: number; // 最高电压值（V）
|
||
...
|
||
}
|
||
```
|
||
|
||
### 2) src/api/javaApi.ts
|
||
|
||
* 在每个新增 API 模块定义前添加模块级 JSDoc，列出路由、用途、返回结构（`ApiResponse<T>` 或数组），并注明 404 时返回 `null` 的约定。
|
||
|
||
* 在各方法上添加简短 JSDoc：参数说明（`deviceId`、`subsystemNo`、`start/end` 格式）、返回类型含义、列表 `limit` 默认值。
|
||
|
||
* 在聚合导出对象处添加一行注释，说明已包含设备/电池/OTA/MQTT/系统以及新增数据域模块。
|
||
|
||
示例（片段）：
|
||
|
||
```ts
|
||
/**
|
||
* 极值数据 API
|
||
* 路由：
|
||
* - GET /extreme-values/{deviceId}/latest 最新记录
|
||
* - GET /extreme-values/{deviceId}?limit= 按设备查询
|
||
* - GET /extreme-values/{deviceId}/range?start=&end= 时间范围查询
|
||
* - POST /extreme-values 新增记录
|
||
*/
|
||
export const javaExtremeValuesApi = {
|
||
/** 获取设备最新极值；404 返回 null */
|
||
async getLatestByDevice(deviceId: string): Promise<ExtremeValues | null> { ... },
|
||
/** 按设备查询极值列表，limit 默认 100 */
|
||
async getByDevice(deviceId: string, limit = 100): Promise<ExtremeValues[]> { ... },
|
||
/** 按时间范围查询，start/end 为 ISO 字符串 */
|
||
async getRange(deviceId: string, start: string, end: string): Promise<ExtremeValues[]> { ... },
|
||
/** 新增一条极值记录 */
|
||
async addRecord(payload: Omit<ExtremeValues, ...>): Promise<ExtremeValues> { ... }
|
||
};
|
||
|
||
// 聚合导出：设备/电池/OTA/MQTT/系统 + 极值/位置/整车/子系统电压/子系统温度
|
||
export const javaApi = { ... };
|
||
```
|
||
|
||
### 3) .env
|
||
|
||
* 在 `VITE_JAVA_API_BASE_URL` 上方添加一行注释，说明为若依后端基础地址，可按环境切换。
|
||
|
||
示例（片段）：
|
||
|
||
```env
|
||
# Java 后端 API 基础地址（若依服务），开发环境可指向 http://localhost:8080
|
||
VITE_JAVA_API_BASE_URL=http://localhost:8080
|
||
```
|
||
|
||
## 验证与影响
|
||
|
||
* 仅添加注释，不改动逻辑与类型签名；不会影响编译与运行。
|
||
|
||
* 重新运行类型检查，确保无语法问题。
|
||
|
||
## 需要确认
|
||
|
||
* 是否按上述规范为本次新增的所有片段添加注释；如需
|
||
|