docs: 添加Postman配置文件和更新API文档

添加Postman环境配置和API集合文件，用于接口测试更新README和API文档，补充部署说明和接口细节
2025-12-09 15:00:57 +08:00
parent a46dd6eb74
commit 4a3e39d76d
4 changed files with 265 additions and 11 deletions
@@ -0,0 +1,121 @@
+<!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://&lt;服务器或域名&gt;:&lt;PORT&gt;</code>（默认 <code>57778</code>） | 本地时区：<code>Asia/Shanghai</code></p>
+  <h2>认证</h2>
+  <ul>
+    <li>管理接口需在请求头携带 <code>X-Admin-Token: &lt;ADMIN_TOKEN&gt;</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>
@@ -0,0 +1,83 @@
+{
+  "info": {
+    "name": "PushToZhaoShang API",
+    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
+  },
+  "item": [
+    {
+      "name": "Metrics",
+      "request": { "method": "GET", "url": "{{baseUrl}}/api/metrics" }
+    },
+    {
+      "name": "Series7",
+      "request": { "method": "GET", "url": "{{baseUrl}}/api/series7?days=7" }
+    },
+    {
+      "name": "Revenue",
+      "request": { "method": "GET", "url": "{{baseUrl}}/api/revenue?days=30" }
+    },
+    {
+      "name": "Audit",
+      "request": { "method": "GET", "url": "{{baseUrl}}/api/audit?days=30" }
+    },
+    {
+      "name": "Health",
+      "request": { "method": "GET", "url": "{{baseUrl}}/api/health" }
+    },
+    {
+      "name": "Export CSV",
+      "request": { "method": "GET", "url": "{{baseUrl}}/api/export" }
+    },
+    {
+      "name": "Root",
+      "request": { "method": "GET", "url": "{{baseUrl}}/" }
+    },
+    {
+      "name": "Admin Page",
+      "request": { "method": "GET", "url": "{{baseUrl}}/admin" }
+    },
+    {
+      "name": "Admin Turnover",
+      "request": {
+        "method": "PUT",
+        "header": [ { "key": "X-Admin-Token", "value": "{{adminToken}}" }, { "key": "Content-Type", "value": "application/json" } ],
+        "body": { "mode": "raw", "raw": "{\n  \"date\": \"2025-12-06\",\n  \"amount\": 3123.45,\n  \"reason\": \"调整入账\",\n  \"actor\": \"admin\"\n}" },
+        "url": "{{baseUrl}}/api/admin/turnover"
+      }
+    },
+    {
+      "name": "Admin Test Push",
+      "request": {
+        "method": "POST",
+        "header": [ { "key": "X-Admin-Token", "value": "{{adminToken}}" }, { "key": "Content-Type", "value": "application/json" } ],
+        "body": { "mode": "raw", "raw": "{\n  \"date\": \"2025-12-09\",\n  \"amount\": 1234.56,\n  \"reason\": \"manual_test\"\n}" },
+        "url": "{{baseUrl}}/api/admin/test_push"
+      }
+    },
+    {
+      "name": "Admin Import CSV",
+      "request": {
+        "method": "POST",
+        "header": [ { "key": "X-Admin-Token", "value": "{{adminToken}}" }, { "key": "Content-Type", "value": "text/csv" } ],
+        "body": { "mode": "raw", "raw": "date,amount\n2025-12-01,12345.67\n2025-12-02,11890.12\n" },
+        "url": "{{baseUrl}}/api/admin/import"
+      }
+    },
+    {
+      "name": "Admin Logs",
+      "request": {
+        "method": "GET",
+        "header": [ { "key": "X-Admin-Token", "value": "{{adminToken}}" } ],
+        "url": "{{baseUrl}}/api/admin/logs?lines=200"
+      }
+    },
+    {
+      "name": "Admin Reload Cutoff",
+      "request": {
+        "method": "POST",
+        "header": [ { "key": "X-Admin-Token", "value": "{{adminToken}}" } ],
+        "url": "{{baseUrl}}/api/admin/reload_cutoff"
+      }
+    }
+  ]
+}
@@ -0,0 +1,8 @@
+{
+  "id": "f6c3b3a1-3c2d-4b62-bc35-0c6ef873a001",
+  "name": "PushToZhaoShang-Env",
+  "values": [
+    { "key": "baseUrl", "value": "http://localhost:57778", "enabled": true },
+    { "key": "adminToken", "value": "", "enabled": true }
+  ]
+}