From 2d068fa66b2063d1ba40812ce831bdd960eb810c Mon Sep 17 00:00:00 2001
From: imbytecat <imbytecat@gmail.com>
Date: Tue, 12 May 2026 00:52:43 +0800
Subject: [PATCH] =?UTF-8?q?docs(api):=20=E8=AF=B4=E6=98=8E=E6=8E=A5?=
 =?UTF-8?q?=E5=8F=A3=E6=96=87=E6=A1=A3=E5=90=AF=E7=94=A8=E6=96=B9=E5=BC=8F?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .env.example |  4 ++++
 README.md    | 17 +++++++++++++++--
 compose.yaml |  1 +
 3 files changed, 20 insertions(+), 2 deletions(-)

diff --git a/.env.example b/.env.example
index 1ade53e..e27a1b4 100644
--- a/.env.example
+++ b/.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
 
 # 可选：日志级别与输出格式
diff --git a/README.md b/README.md
index f588cb1..9f4db02 100644
--- a/README.md
+++ b/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
diff --git a/compose.yaml b/compose.yaml
index 23dad1b..ba3b55c 100644
--- a/compose.yaml
+++ b/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: