battery-soh
电池健康运营看板，用于接入客户现有设备数据，持续呈现电量状态、健康预测、风险分布与维护建议。系统以只读方式连接客户数据库，不改动生产数据；当健康预测暂不可用时，页面会明确显示不可用状态，避免用误导性数值替代真实结果。
产品能力
- 健康总览：聚合展示设备规模、平均健康度、30/90 天趋势与预警设备占比。
- 风险识别：按健康度、低电量、充电状态与预测风险生成重点关注设备清单。
- 实时明细：支持按设备名称、编号、电量与充电状态筛选设备，快速定位需要排查的对象。
- 维护建议：基于当前可用数据给出巡检、复查与优先处理建议。
- 可信展示：缺少预测结果时显示“预测不可用”，不会将缺失值渲染为
0%。
数据接入
系统接入客户现有 MySQL 数据源，业务运行时仅执行只读查询。需要配置：
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 预测服务：
SOH_PREDICTION_API_BASE_URL=http://127.0.0.1:8000
SOH_PREDICTION_CACHE_TTL_SECONDS=86400
SOH_PREDICTION_NEGATIVE_CACHE_TTL_SECONDS=300
SOH_PREDICTION_TIMEOUT_MS=10000
服务端会调用 ${SOH_PREDICTION_API_BASE_URL}/predict，使用返回的当前健康度、30 天趋势、90 天趋势和风险评分生成看板视图。预测结果会按设备与最新采集记录缓存，默认 24 小时；单台设备预测失败或历史数据不足时会短暂缓存不可用状态，默认 5 分钟，避免反复打满预测服务，同时仅该设备显示为“预测不可用”。
接口文档
OpenAPI 文档和规格默认不公开，生产或生产类运行环境应保持默认值：
ENABLE_API_DOCS=false
仅在受控本地开发或内网演示环境显式设置 ENABLE_API_DOCS=true 后，才会开放 http://localhost:3000/api/docs 与 http://localhost:3000/api/spec.json。/api/rpc 不受此开关影响。
快速开始
cp .env.example .env
bun install
bun run dev
打开浏览器：
http://localhost:3000/：设备健康运营看板http://localhost:3000/batteries：设备状态明细http://localhost:3000/api/docs：接口文档（需设置ENABLE_API_DOCS=true）
本地演示环境
如果暂时没有生产数据库连接，可以使用 Docker Compose 启动本地 MySQL 并填充演示数据：
docker compose up --build
Compose 会启动：
db：本地 MySQL 8.4seed：初始化本地ls_battery_info演示数据app：启动应用服务
Compose 的 app 服务会为本地演示显式启用 ENABLE_API_DOCS=true；生产部署不应沿用该设置，除非已通过网络边界或上游认证限制访问。
也可以手动初始化本地数据：
DATABASE_URL=mysql://battery:battery@localhost:3306/battery_soh bun run seed
seed 仅用于本地开发和演示环境；应用运行时仍保持只读查询，不写入业务数据库。
系统结构
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 条历史记录。
部署
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 |
格式化与静态检查 |
交付前验证：
bun run fix && bun run typecheck && bun run test && bun run build