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
快速开始
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 只读查询
├── domain/battery.ts # 电池领域类型、归一化、展示聚合
├── client/orpc.ts # isomorphic ORPC client
└── styles.css # Tailwind v4 entry
接口保持模板里的 ORPC 模式：
battery.dashboard：读取每个mac的最新记录并生成看板聚合数据battery.batteries：无mac时返回每台设备最新记录；带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