# battery-soh

一个基于 **Bun + TanStack Start + ORPC** 的电池健康展示系统。应用会被打包成单个二进制文件，前端页面、SSR 服务和 ORPC API 一起发布；业务数据只读接入甲方现有 MySQL 表 `ls_battery_info`，本项目不写入、不迁移、不修改甲方数据库。

## 数据源

甲方提供的只读表结构：

| 字段名 | 数据类型 | 说明 |
| --- | --- | --- |
| `id` | `int(11)` 自增 | 主键 ID |
| `user_id` | `int(11)` | 用户 ID |
| `mac` | `varchar(50)` | 设备 MAC |
| `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)` | 备注，可空 |

环境变量：

```bash
DATABASE_URL=mysql://user:password@host:3306/database
```

可选 AI 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` 发起 POST 请求，并把返回的 `now_soh`、`month_soh`、`trmonth_soh`、`risk_score` 等字段用于看板展示。预测结果按设备和最新采集记录做内存 TTL 缓存，默认 24 小时；如果未配置或预测服务失败，看板仍使用 MySQL 采集数据生成展示，不写入数据库。

## 快速开始

```bash
cp .env.example .env
bun install
bun run dev
```

如果甲方暂时没有提供数据库连接，可以用 Docker Compose 启动本地 MySQL 并填充示例数据：

```bash
docker compose up --build
```

Compose 会启动三个服务：

- `db`：本地 MySQL 8.4
- `seed`：执行 `bun run seed`，用 Drizzle MySQL schema + `drizzle-seed` 重置本地 `ls_battery_info` 并写入示例数据
- `app`：使用同一个 `DATABASE_URL` 启动单二进制应用

也可以手动 seed 本地库：

```bash
DATABASE_URL=mysql://battery:battery@localhost:3306/battery_soh bun run seed
```

`seed` 是本地开发/验收脚本，会建表并重置示例数据；应用运行时仍然只执行 `SELECT`，不会写入数据库。

打开浏览器：

- `http://localhost:3000/`：SoH 预测与风险洞察看板
- `http://localhost:3000/batteries`：设备电池实时状态
- `http://localhost:3000/api/docs`：Scalar 渲染的 ORPC OpenAPI 文档

## 架构

```
src/
├── routes/                 # TanStack Start 文件路由：页面 + API 端点
├── server/
│   ├── api/                # ORPC contract / router
│   ├── battery/mysql.ts    # 甲方 MySQL 只读查询
│   └── prediction/client.ts # AI SoH 预测客户端与缓存
├── domain/battery.ts       # 电池领域类型、归一化、展示聚合
├── client/orpc.ts          # isomorphic ORPC client
└── styles.css              # Tailwind v4 entry
```

接口保持模板里的 ORPC 模式：

- `battery.dashboard`：读取每个 `mac` 的最新记录并生成看板聚合数据
- `battery.batteries`：分页返回每台设备最新记录，支持 `pageSize`、`cursor`、`search`、`lowPower`、`powerStatus`、`sort` 筛选/排序
- `battery.history`：按 `mac` 返回该设备历史记录，按 `create_time desc` 限制 500 条

所有业务查询都是 `SELECT`，没有 mutation，也没有 mock/fallback 数据。

## 部署

```bash
bun run build
bun run compile
./out/server-<target>
```

Docker 镜像会在构建阶段产出单个 `./server` 二进制，运行阶段只需要配置 `DATABASE_URL`。

## 脚本

| 命令 | 作用 |
| --- | --- |
| `bun run dev` | Vite 开发服务器 |
| `bun run build` | 构建到 `.output/` |
| `bun run compile` | 生成单二进制 `out/server-<target>` |
| `bun run seed` | 为本地 MySQL 创建甲方表并填充示例数据 |
| `bun run typecheck` | TypeScript 类型检查 |
| `bun run test` | 运行所有 `*.test.ts` |
| `bun run fix` | Biome 格式化 + lint + 整理 imports |

## 验证

```bash
bun run fix && bun run typecheck && bun run test && bun run build
```