# 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
```