131 lines
4.3 KiB
Markdown
131 lines
4.3 KiB
Markdown
# battery-soh
|
|
|
|
电池健康运营看板，用于接入客户现有设备数据，持续呈现电量状态、健康预测、风险分布与维护建议。系统以只读方式连接客户数据库，不改动生产数据；当健康预测暂不可用时，页面会明确显示不可用状态，避免用误导性数值替代真实结果。
|
|
|
|
## 产品能力
|
|
|
|
- **健康总览**：聚合展示设备规模、平均健康度、30/90 天趋势与预警设备占比。
|
|
- **风险识别**：按健康度、低电量、充电状态与预测风险生成重点关注设备清单。
|
|
- **实时明细**：支持按设备名称、编号、电量与充电状态筛选设备，快速定位需要排查的对象。
|
|
- **维护建议**：基于当前可用数据给出巡检、复查与优先处理建议。
|
|
- **可信展示**：缺少预测结果时显示“预测不可用”，不会将缺失值渲染为 `0%`。
|
|
|
|
## 数据接入
|
|
|
|
系统接入客户现有 MySQL 数据源，业务运行时仅执行只读查询。需要配置：
|
|
|
|
```bash
|
|
DATABASE_URL=mysql://user:password@host:3306/database
|
|
```
|
|
|
|
客户设备表：`ls_battery_info`。
|
|
|
|
| 字段名 | 数据类型 | 业务含义 |
|
|
| --- | --- | --- |
|
|
| `id` | `int(11)` auto increment | 记录 ID |
|
|
| `user_id` | `int(11)` | 用户 ID |
|
|
| `mac` | `varchar(50)` | 设备编号 |
|
|
| `dev_model` | `varchar(20)` | 设备型号 |
|
|
| `dev_name` | `varchar(50)` | 设备名称 |
|
|
| `is_low_power` | `varchar(10)` | 是否低电量：`true` / `false` |
|
|
| `power_status` | `tinyint(4)` | `0` 未充电，`1` 充电中，`2` 已充满 |
|
|
| `power` | `tinyint(4)` | 当前电量 `0~100` |
|
|
| `create_time` | `datetime` | 采集时间 |
|
|
| `remark` | `varchar(500)` | 备注 |
|
|
|
|
## 健康预测
|
|
|
|
看板需要接入外部 SoH 预测服务：
|
|
|
|
```bash
|
|
SOH_PREDICTION_API_BASE_URL=http://127.0.0.1:8000
|
|
SOH_PREDICTION_CACHE_TTL_SECONDS=86400
|
|
SOH_PREDICTION_TIMEOUT_MS=10000
|
|
```
|
|
|
|
服务端会调用 `${SOH_PREDICTION_API_BASE_URL}/predict`，使用返回的当前健康度、30 天趋势、90 天趋势和风险评分生成看板视图。预测结果会按设备与最新采集记录缓存，默认 24 小时；单台设备预测失败或历史数据不足时，仅该设备显示为“预测不可用”。
|
|
|
|
## 快速开始
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
bun install
|
|
bun run dev
|
|
```
|
|
|
|
打开浏览器：
|
|
|
|
- `http://localhost:3000/`：设备健康运营看板
|
|
- `http://localhost:3000/batteries`：设备状态明细
|
|
- `http://localhost:3000/api/docs`：接口文档
|
|
|
|
## 本地演示环境
|
|
|
|
如果暂时没有生产数据库连接，可以使用 Docker Compose 启动本地 MySQL 并填充演示数据：
|
|
|
|
```bash
|
|
docker compose up --build
|
|
```
|
|
|
|
Compose 会启动：
|
|
|
|
- `db`：本地 MySQL 8.4
|
|
- `seed`：初始化本地 `ls_battery_info` 演示数据
|
|
- `app`：启动应用服务
|
|
|
|
也可以手动初始化本地数据：
|
|
|
|
```bash
|
|
DATABASE_URL=mysql://battery:battery@localhost:3306/battery_soh bun run seed
|
|
```
|
|
|
|
`seed` 仅用于本地开发和演示环境；应用运行时仍保持只读查询，不写入业务数据库。
|
|
|
|
## 系统结构
|
|
|
|
```text
|
|
src/
|
|
├── routes/ # 页面与 API 路由
|
|
├── server/
|
|
│ ├── api/ # 接口契约与路由
|
|
│ ├── battery/mysql.ts # 设备数据只读查询
|
|
│ └── prediction/client.ts # 健康预测服务客户端
|
|
├── domain/battery.ts # 电池领域模型与看板聚合
|
|
├── client/orpc.ts # 前端接口客户端
|
|
└── styles.css # 全局样式入口
|
|
```
|
|
|
|
核心接口：
|
|
|
|
- `battery.dashboard`：生成健康运营看板数据。
|
|
- `battery.batteries`：分页返回每台设备的最新状态，支持搜索、筛选和排序。
|
|
- `battery.history`：返回单台设备最近 500 条历史记录。
|
|
|
|
## 部署
|
|
|
|
```bash
|
|
bun run build
|
|
bun run compile
|
|
./out/server-<target>
|
|
```
|
|
|
|
构建产物为单个服务二进制文件，运行时需要配置 `DATABASE_URL` 与 SoH 预测服务地址。
|
|
|
|
## 常用命令
|
|
|
|
| 命令 | 作用 |
|
|
| --- | --- |
|
|
| `bun run dev` | 启动开发服务 |
|
|
| `bun run build` | 构建应用 |
|
|
| `bun run compile` | 生成单二进制产物 |
|
|
| `bun run seed` | 初始化本地演示数据 |
|
|
| `bun run typecheck` | TypeScript 类型检查 |
|
|
| `bun run test` | 运行测试 |
|
|
| `bun run fix` | 格式化与静态检查 |
|
|
|
|
交付前验证：
|
|
|
|
```bash
|
|
bun run fix && bun run typecheck && bun run test && bun run build
|
|
```
|