6.5 KiB
6.5 KiB
项目 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=nullis_final：某日期是否已定版（仅定版数据会计入汇总）
接口列表
1. 指标看板
- 路径：
GET /api/metrics - 说明：返回今日/昨日/前日、本周、上周、本月汇总数据；
today.amount仅在达到截止时间且当日已定版时显示数值 - 示例响应：
{
"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 - 示例响应：
[
{ "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.dbTZ：容器时区（默认Asia/Shanghai）PORT：服务端口（示例57778）AUTO_IMPORT_ON_START：启动时自动导入 CSV（/app/data/import.csv）