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) |
备注，可空 |
环境变量：
DATABASE_URL=mysql://user:password@host:3306/database
AI SoH 预测服务是必填依赖；未配置时应用会在环境变量校验阶段失败，避免把预测缺失误展示为真实 SoH：
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%。
快速开始
cp .env.example .env
bun install
bun run dev
如果甲方暂时没有提供数据库连接，可以用 Docker Compose 启动本地 MySQL 并填充示例数据：
docker compose up --build
Compose 会启动三个服务：
db：本地 MySQL 8.4seed：执行bun run seed，用 Drizzle MySQL schema +drizzle-seed重置本地ls_battery_info并写入示例数据app：使用同一个DATABASE_URL启动单二进制应用
也可以手动 seed 本地库：
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 数据。
部署
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 |
验证
bun run fix && bun run typecheck && bun run test && bun run build