docs(api): 说明接口文档启用方式

.env.example

@@ -1,8 +1,12 @@
 DATABASE_URL=mysql://user:password@localhost:3306/database
 
+# 默认关闭公开 OpenAPI 文档/规格；仅在受控本地或内网演示环境显式启用。
+# ENABLE_API_DOCS=false
+
 # 必填：外部 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
 
 # 可选：日志级别与输出格式

README.md

@@ -40,10 +40,21 @@ DATABASE_URL=mysql://user:password@host:3306/database
 ```bash
 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 小时；单台设备预测失败或历史数据不足时，仅该设备显示为“预测不可用”。
+服务端会调用 `${SOH_PREDICTION_API_BASE_URL}/predict`，使用返回的当前健康度、30 天趋势、90 天趋势和风险评分生成看板视图。预测结果会按设备与最新采集记录缓存，默认 24 小时；单台设备预测失败或历史数据不足时会短暂缓存不可用状态，默认 5 分钟，避免反复打满预测服务，同时仅该设备显示为“预测不可用”。
+
+## 接口文档
+
+OpenAPI 文档和规格默认不公开，生产或生产类运行环境应保持默认值：
+
+```bash
+ENABLE_API_DOCS=false
+```
+
+仅在受控本地开发或内网演示环境显式设置 `ENABLE_API_DOCS=true` 后，才会开放 `http://localhost:3000/api/docs` 与 `http://localhost:3000/api/spec.json`。`/api/rpc` 不受此开关影响。
 
 ## 快速开始
 
@@ -57,7 +68,7 @@ bun run dev
 
 - `http://localhost:3000/`：设备健康运营看板
 - `http://localhost:3000/batteries`：设备状态明细
-- `http://localhost:3000/api/docs`：接口文档
+- `http://localhost:3000/api/docs`：接口文档（需设置 `ENABLE_API_DOCS=true`）
 
 ## 本地演示环境
 
@@ -73,6 +84,8 @@ Compose 会启动：
 - `seed`：初始化本地 `ls_battery_info` 演示数据
 - `app`：启动应用服务
 
+Compose 的 `app` 服务会为本地演示显式启用 `ENABLE_API_DOCS=true`；生产部署不应沿用该设置，除非已通过网络边界或上游认证限制访问。
+
 也可以手动初始化本地数据：
 
 ```bash

compose.yaml

@@ -41,6 +41,7 @@ services:
     environment:
       - DATABASE_URL=mysql://battery:battery@db:3306/battery_soh
       - SOH_PREDICTION_API_BASE_URL=http://host.docker.internal:8000
+      - ENABLE_API_DOCS=true
 
 volumes:
   mysql_data: