From c936167fc88016b2333a054b761828f4dafcfd97 Mon Sep 17 00:00:00 2001
From: imbytecat <imbytecat@gmail.com>
Date: Mon, 11 May 2026 22:21:57 +0800
Subject: [PATCH] =?UTF-8?q?docs(prediction):=20=E8=AF=B4=E6=98=8E=20AI=20?=
 =?UTF-8?q?=E9=A2=84=E6=B5=8B=E6=9C=8D=E5=8A=A1=E9=85=8D=E7=BD=AE?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .env.example |  5 +++++
 AGENTS.md    | 12 +++++++++++-
 README.md    | 13 ++++++++++++-
 3 files changed, 28 insertions(+), 2 deletions(-)

diff --git a/.env.example b/.env.example
index e3e3461..71f3a4f 100644
--- a/.env.example
+++ b/.env.example
@@ -1,5 +1,10 @@
 DATABASE_URL=mysql://user:password@localhost:3306/database
 
+# Optional: external AI SoH prediction service.
+# SOH_PREDICTION_API_BASE_URL=http://127.0.0.1:8000
+# SOH_PREDICTION_CACHE_TTL_SECONDS=86400
+# SOH_PREDICTION_TIMEOUT_MS=10000
+
 # Optional logging knobs (defaults are usually fine):
 # LOG_LEVEL=info       # trace|debug|info|warning|error|fatal
 # LOG_FORMAT=pretty    # pretty|json — defaults to TTY ? pretty : json
diff --git a/AGENTS.md b/AGENTS.md
index 61f4a3c..47baf64 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -33,6 +33,14 @@ Environment variable:
 DATABASE_URL=mysql://user:password@host:3306/database
 ```
 
+Optional AI prediction service:
+
+```bash
+SOH_PREDICTION_API_BASE_URL=http://127.0.0.1:8000
+SOH_PREDICTION_CACHE_TTL_SECONDS=86400
+SOH_PREDICTION_TIMEOUT_MS=10000
+```
+
 Customer table: `ls_battery_info`.
 
 | Column | Type | Meaning |
@@ -56,6 +64,7 @@ Rules:
 - `power_status` is normalized to `0 | 1 | 2`.
 - Without `mac`, battery list queries return the latest record per `mac`.
 - With `mac`, battery list queries return 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.
 
 ## Layout
 
@@ -67,7 +76,8 @@ src/
 │   └── api/            # ORPC handlers
 ├── server/
 │   ├── api/            # contracts / routers / interceptors
-│   └── battery/mysql.ts
+│   ├── battery/mysql.ts
+│   └── prediction/client.ts
 ├── domain/battery.ts
 ├── client/orpc.ts
 └── styles.css
diff --git a/README.md b/README.md
index 867be17..6c8ffdb 100644
--- a/README.md
+++ b/README.md
@@ -25,6 +25,16 @@
 DATABASE_URL=mysql://user:password@host:3306/database
 ```
 
+可选 AI 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 小时；如果未配置或预测服务失败，看板仍使用 MySQL 采集数据生成展示，不写入数据库。
+
 ## 快速开始
 
 ```bash
@@ -66,7 +76,8 @@ src/
 ├── routes/                 # TanStack Start 文件路由：页面 + API 端点
 ├── server/
 │   ├── api/                # ORPC contract / router
-│   └── battery/mysql.ts    # 甲方 MySQL 只读查询
+│   ├── battery/mysql.ts    # 甲方 MySQL 只读查询
+│   └── prediction/client.ts # AI SoH 预测客户端与缓存
 ├── domain/battery.ts       # 电池领域类型、归一化、展示聚合
 ├── client/orpc.ts          # isomorphic ORPC client
 └── styles.css              # Tailwind v4 entry