121 lines
4.3 KiB
Markdown
121 lines
4.3 KiB
Markdown
# 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 预测服务是必填依赖；未配置时应用会在环境变量校验阶段失败，避免把预测缺失误展示为真实 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 小时；如果单次预测失败或历史数据不足，对应设备显示“预测不可用”，但不会把缺失值展示成 `0%`。
|
||
|
||
## 快速开始
|
||
|
||
```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
|
||
```
|