# 项目 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`）