diff --git a/docs/自动化营业额系统/API.md b/docs/自动化营业额系统/API.md
new file mode 100644
index 0000000..dadc195
--- /dev/null
+++ b/docs/自动化营业额系统/API.md
@@ -0,0 +1,151 @@
+# 项目 API 文档（益选营业额系统）
+
+## 概述
+- 基础地址：`http://<服务器或域名>:<PORT>`（默认 `57778`，本地开发默认 `5000`）
+- 返回格式：`application/json`
+- 本地时区：`Asia/Shanghai`，时间字段按本地时区输出
+- 截止时间：支持分钟级配置（`config.json` 中 `cutoff_time`，例如 `13:18`；未设置时使用 `cutoff_hour`，分钟视为 `00`）
+
+## 认证
+- 管理接口需在请求头携带 `X-Admin-Token: <ADMIN_TOKEN>`（容器环境变量或 `.env` 配置）
+
+## 公共字段说明
+- `server_now`：服务器当前时间 ISO 字符串（含时区）
+- `cutoff_time` / `cutoff_hour`：当天营业额结算门槛；未到门槛时 `today.amount=null`
+- `is_final`：某日期是否已定版（仅定版数据会计入汇总）
+
+## 接口列表
+
+### 1. 指标看板
+- 路径：`GET /api/metrics`
+- 说明：返回今日/昨日/前日、本周、上周、本月汇总数据；`today.amount` 仅在达到截止时间且当日已定版时显示数值
+- 示例响应：
+```json
+{
+  "shop_name": "益选便利店",
+  "server_now": "2025-12-09T13:14:40+08:00",
+  "cutoff_hour": 13,
+  "cutoff_time": "13:18",
+  "today": { "date": "2025-12-09", "weekday": "周二", "amount": null },
+  "yesterday": { "date": "2025-12-08", "amount": 3629.76 },
+  "day_before": { "date": "2025-12-07", "amount": 2408.70 },
+  "this_week": { "start": "2025-12-08", "end": "2025-12-08", "total": 3629.76 },
+  "last_week": { "start": "2025-12-01", "end": "2025-12-07", "total": 4211.79 },
+  "this_month": { "start": "2025-12-01", "end": "2025-12-08", "total": 7841.55 }
+}
+```
+- 代码位置：`backend/app.py:225`
+
+### 2. 最近 7 天序列
+- 路径：`GET /api/series7`
+- 参数：`days`（可选，默认 7，范围 7～90）
+- 说明：返回最近 N 天每日营业额；在未到截止或今日未定版时，序列截止到昨日；未定版日期按区间估算并标记 `estimated=true`
+- 示例响应：
+```json
+[
+  { "date": "2025-12-06", "amount": 1803.09, "estimated": false },
+  { "date": "2025-12-07", "amount": 2408.70, "estimated": false },
+  { "date": "2025-12-08", "amount": 3629.76, "estimated": false }
+]
+```
+- 代码位置：`backend/app.py:287`
+
+### 3. 历史营业额查询
+- 路径：`GET /api/revenue`
+- 参数：`days`（可选，默认 30）
+- 说明：查询最近 N 天的历史营业额（仅定版数据）
+- 代码位置：`backend/app.py:365`
+
+### 4. 审计日志
+- 路径：`GET /api/audit`
+- 参数：`days`（可选，默认 30）
+- 说明：返回最近 N 天的审计记录（生成、修正、导入等）
+- 代码位置：`backend/app.py:373`
+
+### 5. 健康检查
+- 路径：`GET /api/health`
+- 说明：服务健康状态（数据库、调度器、时区）
+- 代码位置：`backend/app.py:389`
+
+### 6. 导出 CSV
+- 路径：`GET /api/export`
+- 说明：导出已定版营业额为 CSV 文本（`date,amount`）
+- 代码位置：`backend/app.py:402`
+
+### 7. 单页入口
+- 路径：`GET /`、`GET /admin`
+- 说明：前端看板与管理页入口（静态文件）
+- 代码位置：`backend/app.py:409`、`backend/app.py:414`
+
+### 8. 管理：修正某日营业额
+- 路径：`PUT /api/admin/turnover`
+- 认证：`X-Admin-Token`
+- 请求体：`{"date":"YYYY-MM-DD","amount":1234.56,"reason":"调整入账","actor":"admin"}`
+- 说明：修正指定日期金额并置为定版；写入审计日志并推送飞书
+- 示例响应：`{"ok":true}`
+- 代码位置：`backend/app.py:418`
+
+### 9. 管理：试发飞书
+- 路径：`POST /api/admin/test_push`
+- 认证：`X-Admin-Token`
+- 请求体（可选）：`{"date":"YYYY-MM-DD","amount":1234.56,"reason":"manual_test"}`
+- 说明：向已配置的飞书机器人发送一条测试消息（卡片→帖子→文本兼容）
+- 示例响应：`{"ok":true,"pushed":{"date":"...","amount":1234.56,"reason":"..."}}`
+- 代码位置：`backend/app.py:443`
+
+### 10. 管理：批量导入 CSV
+- 路径：`POST /api/admin/import`
+- 认证：`X-Admin-Token`
+- 请求头：`Content-Type: text/csv`
+- 请求体：CSV 内容（两列：`date,amount`）
+- 说明：批量导入历史数据，均置为定版并记录审计；逐条尝试推送飞书
+- 示例响应：`{"ok":true,"imported":N}`
+- 代码位置：`backend/app.py:487`
+
+### 11. 管理：读取服务器日志
+- 路径：`GET /api/admin/logs?lines=200`
+- 认证：`X-Admin-Token`
+- 说明：读取 `app.log` 最近 N 行（含飞书推送状态与返回体片段）
+- 示例响应：`{"lines":["飞书推送卡片成功: status=200 body=...", ...]}`
+- 代码位置：`backend/app.py:498`
+
+### 12. 管理：在线重载截止时间
+- 路径：`POST /api/admin/reload_cutoff`
+- 认证：`X-Admin-Token`
+- 说明：重新读取 `config.json` 的 `cutoff_time`/`cutoff_hour`，用新值更新 APScheduler 的每日触发任务，并立即执行一次结算检查
+- 示例响应：`{"ok":true,"cutoff_time":"13:18"}`
+- 代码位置：`backend/app.py:333`
+
+### 13. 服务器事件（SSE）
+- 路径：`GET /api/events`
+- 说明：服务端推送事件（每 30 秒心跳一次；在每小时第 0/1 分会强制刷新并调用结算检查）
+- 事件示例：
+  - `data: {"type":"tick","server_now":"2025-12-09T13:14:40+08:00"}`
+  - `data: {"type":"force_refresh"}`（在 0/1 分触发）
+- 代码位置：`backend/app.py:571`
+
+## 触发与结算逻辑（参考）
+- 结算判断：本地时区 `now >= cutoff_time` 时尝试 `daily_job()`（`backend/app.py:128-149`）
+- APScheduler：按 `hour:minute` 注册每日触发任务（`backend/app.py:490-511`）
+- 每日作业：
+  - 若当天无记录：生成金额 → 写库 → 审计 → 推送飞书
+  - 若当天已存在但未定版：置为定版 → 审计 → 推送飞书
+  - 若当天已存在且已定版：推送飞书（保底通知）
+  - 代码位置：`backend/app.py:101-126`
+
+## 配置文件（关键字段）
+- 路径：`/app/config.json`（容器内；通过 `docker-compose.yml` 映射宿主机 `./config.json`）
+- 字段：
+  - `feishu_webhook_url`：飞书机器人 Webhook（必填）
+  - `feishu_secret`：签名密钥（启用签名时填写，否则留空）
+  - `shop_name`：店名
+  - `weekday_range` / `weekend_range`：金额生成区间
+  - `cutoff_hour` / `cutoff_time`：截止时间（小时或分钟级）
+
+## 环境变量
+- `ADMIN_TOKEN`：管理口令（用于管理接口）
+- `DATABASE_URL`：数据库连接，默认 `sqlite:////app/data/data.db`（容器），本地默认 `sqlite:///data/data.db`
+- `TZ`：容器时区（默认 `Asia/Shanghai`）
+- `PORT`：服务端口（示例 `57778`）
+- `AUTO_IMPORT_ON_START`：启动时自动导入 CSV（`/app/data/import.csv`）
+