docs(prediction): 说明 AI 预测服务配置

.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

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

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