From ba4aa96baff805ae270f3e50a8cf9e06f5b81f0b Mon Sep 17 00:00:00 2001
From: imbytecat <imbytecat@gmail.com>
Date: Mon, 11 May 2026 23:38:38 +0800
Subject: [PATCH] =?UTF-8?q?docs(prediction):=20=E6=98=8E=E7=A1=AE=20SoH=20?=
 =?UTF-8?q?=E9=A2=84=E6=B5=8B=E5=BF=85=E5=A1=AB=E4=BE=9D=E8=B5=96?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 AGENTS.md | 2 +-
 README.md | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 68a6b87..2ece570 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -64,7 +64,7 @@ Rules:
 - `power_status` is normalized to `0 | 1 | 2`.
 - `battery.batteries` returns paginated latest records per `mac`; supported filters are `pageSize`, `cursor`, `search`, `lowPower`, `powerStatus`, and `sort`.
 - `battery.history` takes `mac` and returns history ordered by `create_time DESC, id DESC`, limited to 500 rows.
-- Dashboard may call the external prediction API when `SOH_PREDICTION_API_BASE_URL` is configured. Prediction results are cached in memory by `mac` and latest history record.
+- Dashboard requires the external prediction API via `SOH_PREDICTION_API_BASE_URL`; missing configuration must fail environment validation. Per-device prediction failures may surface as unavailable values, but must not be rendered as `0%`.
 
 ## Layout
 
diff --git a/README.md b/README.md
index e18418f..6c217a7 100644
--- a/README.md
+++ b/README.md
@@ -25,7 +25,7 @@
 DATABASE_URL=mysql://user:password@host:3306/database
 ```
 
-可选 AI SoH 预测服务：
+AI SoH 预测服务是必填依赖；未配置时应用会在环境变量校验阶段失败，避免把预测缺失误展示为真实 SoH：
 
 ```bash
 SOH_PREDICTION_API_BASE_URL=http://127.0.0.1:8000
@@ -33,7 +33,7 @@ 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 采集数据生成展示，不写入数据库。
+服务端会向 `${SOH_PREDICTION_API_BASE_URL}/predict` 发起 POST 请求，并把返回的 `now_soh`、`month_soh`、`trmonth_soh`、`risk_score` 等字段用于看板展示。预测结果按设备和最新采集记录做内存 TTL 缓存，默认 24 小时；如果单次预测失败或历史数据不足，对应设备显示“预测不可用”，但不会把缺失值展示成 `0%`。
 
 ## 快速开始