From a8e3cf5f4beaa6ffd556e83af4e8a2b3428eed73 Mon Sep 17 00:00:00 2001
From: imbytecat <imbytecat@gmail.com>
Date: Mon, 11 May 2026 23:16:59 +0800
Subject: [PATCH] =?UTF-8?q?docs(api):=20=E6=9B=B4=E6=96=B0=E7=94=B5?=
 =?UTF-8?q?=E6=B1=A0=E5=88=86=E9=A1=B5=E6=8E=A5=E5=8F=A3=E8=AF=B4=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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

diff --git a/AGENTS.md b/AGENTS.md
index 47baf64..68a6b87 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -62,8 +62,8 @@ Rules:
 - Do not add mock/fallback rows. If MySQL is unavailable, surface the error.
 - `is_low_power` is stored as a string and normalized to boolean in `src/domain/battery.ts`.
 - `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.
+- `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.
 
 ## Layout
@@ -91,6 +91,7 @@ src/
 - Current business API:
   - `battery.dashboard`
   - `battery.batteries`
+  - `battery.history`
 
 ## CLI And Deploy
 
diff --git a/README.md b/README.md
index 6c8ffdb..e18418f 100644
--- a/README.md
+++ b/README.md
@@ -86,7 +86,8 @@ src/
 接口保持模板里的 ORPC 模式：
 
 - `battery.dashboard`：读取每个 `mac` 的最新记录并生成看板聚合数据
-- `battery.batteries`：无 `mac` 时返回每台设备最新记录；带 `mac` 时返回该设备历史记录，按 `create_time desc` 限制 500 条
+- `battery.batteries`：分页返回每台设备最新记录，支持 `pageSize`、`cursor`、`search`、`lowPower`、`powerStatus`、`sort` 筛选/排序
+- `battery.history`：按 `mac` 返回该设备历史记录，按 `create_time desc` 限制 500 条
 
 所有业务查询都是 `SELECT`，没有 mutation，也没有 mock/fallback 数据。