122 lines
4.7 KiB
HTML
122 lines
4.7 KiB
HTML
<!doctype html>
|
||
<html lang="zh-CN">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||
<title>项目 API 文档（益选营业额系统）</title>
|
||
<style>
|
||
body { font-family: -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Helvetica, Arial, "Noto Sans", "Noto Sans CJK", "PingFang SC", "Microsoft YaHei", sans-serif; margin: 40px; line-height: 1.6; color: #222; }
|
||
h1 { font-size: 24px; margin: 0 0 16px; }
|
||
h2 { font-size: 18px; margin: 24px 0 8px; }
|
||
code, pre { background: #f6f8fa; border-radius: 6px; }
|
||
code { padding: 2px 4px; }
|
||
pre { padding: 12px; overflow: auto; }
|
||
.endpoint { border-left: 4px solid #3b82f6; padding-left: 12px; margin: 16px 0; }
|
||
.small { color: #555; font-size: 13px; }
|
||
ul { padding-left: 18px; }
|
||
</style>
|
||
</head>
|
||
<body>
|
||
<h1>项目 API 文档（益选营业额系统）</h1>
|
||
<p class="small">基础地址：<code>http://<服务器或域名>:<PORT></code>（默认 <code>57778</code>） | 本地时区：<code>Asia/Shanghai</code></p>
|
||
<h2>认证</h2>
|
||
<ul>
|
||
<li>管理接口需在请求头携带 <code>X-Admin-Token: <ADMIN_TOKEN></code></li>
|
||
</ul>
|
||
<h2>公共字段</h2>
|
||
<ul>
|
||
<li><code>server_now</code>：服务器当前时间（含时区）</li>
|
||
<li><code>cutoff_time</code>/<code>cutoff_hour</code>：截止时间；未到门槛时 <code>today.amount=null</code></li>
|
||
<li><code>is_final</code>：某日期是否已定版</li>
|
||
</ul>
|
||
|
||
<div class="endpoint">
|
||
<h2>GET /api/metrics</h2>
|
||
<p>指标看板：今日/昨日/前日、本周、上周、本月；达到截止时间且今日已定版时显示金额。</p>
|
||
<pre>{
|
||
"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 }
|
||
}</pre>
|
||
</div>
|
||
|
||
<div class="endpoint">
|
||
<h2>GET /api/series7</h2>
|
||
<p>最近 N 天序列（默认 7，范围 7～90）。未到截止或今日未定版时，截止到昨日；未定版日期按区间估算并标记 <code>estimated=true</code>。</p>
|
||
<pre>[ { "date": "2025-12-06", "amount": 1803.09, "estimated": false }, ... ]</pre>
|
||
</div>
|
||
|
||
<div class="endpoint">
|
||
<h2>GET /api/revenue</h2>
|
||
<p>历史营业额查询（仅定版数据）。参数：<code>days</code> 默认 30。</p>
|
||
</div>
|
||
|
||
<div class="endpoint">
|
||
<h2>GET /api/audit</h2>
|
||
<p>审计日志。参数：<code>days</code> 默认 30。</p>
|
||
</div>
|
||
|
||
<div class="endpoint">
|
||
<h2>GET /api/health</h2>
|
||
<p>健康检查。</p>
|
||
</div>
|
||
|
||
<div class="endpoint">
|
||
<h2>GET /api/export</h2>
|
||
<p>导出 CSV（仅定版）。</p>
|
||
</div>
|
||
|
||
<div class="endpoint">
|
||
<h2>GET /</h2>
|
||
<p>看板入口（静态）。</p>
|
||
<h2>GET /admin</h2>
|
||
<p>管理入口（静态）。</p>
|
||
</div>
|
||
|
||
<div class="endpoint">
|
||
<h2>PUT /api/admin/turnover</h2>
|
||
<p>修正某日营业额（置为定版并推送）。头：<code>X-Admin-Token</code></p>
|
||
<pre>{ "date":"YYYY-MM-DD", "amount":1234.56, "reason":"调整入账", "actor":"admin" }</pre>
|
||
</div>
|
||
|
||
<div class="endpoint">
|
||
<h2>POST /api/admin/test_push</h2>
|
||
<p>试发飞书（卡片→帖子→文本）。头：<code>X-Admin-Token</code></p>
|
||
<pre>{ "date":"YYYY-MM-DD", "amount":1234.56, "reason":"manual_test" }</pre>
|
||
</div>
|
||
|
||
<div class="endpoint">
|
||
<h2>POST /api/admin/import</h2>
|
||
<p>批量导入 CSV（两列：<code>date,amount</code>）。头：<code>X-Admin-Token</code>，<code>Content-Type: text/csv</code></p>
|
||
</div>
|
||
|
||
<div class="endpoint">
|
||
<h2>GET /api/admin/logs</h2>
|
||
<p>读取 <code>app.log</code> 最近 N 行。参数：<code>lines</code>；头：<code>X-Admin-Token</code></p>
|
||
</div>
|
||
|
||
<div class="endpoint">
|
||
<h2>POST /api/admin/reload_cutoff</h2>
|
||
<p>在线重载截止时间（更新 APScheduler 的每日触发任务并立即执行一次结算检查）。头：<code>X-Admin-Token</code></p>
|
||
</div>
|
||
|
||
<div class="endpoint">
|
||
<h2>GET /api/events</h2>
|
||
<p>SSE 心跳事件（每 30 秒；在每小时第 0/1 分触发强制刷新与结算检查）。</p>
|
||
</div>
|
||
|
||
<h2>打印为 PDF</h2>
|
||
<ul>
|
||
<li>在浏览器中打开本文件，使用“打印”选择“另存为 PDF”。</li>
|
||
<li>或将此文件纳入归档（与 <code>API.md</code> 同内容）。</li>
|
||
</ul>
|
||
</body>
|
||
</html>
|