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

添加Postman环境配置和API集合文件，用于接口测试更新README和API文档，补充部署说明和接口细节
2025-12-09 15:00:57 +08:00 · 2025-12-09 15:00:57 +08:00 · 4a3e39d76d
commit 4a3e39d76d
parent a46dd6eb74
4 changed files with 265 additions and 11 deletions
--- a/README.md
+++ b/README.md
@ -3,12 +3,18 @@
 ## 快速部署（Docker）
 - 1：准备环境变量（不要提交真实口令到仓库）
  - 复制 `.env.example` 到 `.env` 并填写 `ADMIN_TOKEN`
- 2：启动服务
+- 2：配置映射（确保容器读取宿主机配置与数据）
+  - `docker-compose.yml` 已映射：`./data:/app/data`、`./config.json:/app/config.json:ro`
+- 3：启动服务
 ```bash
-docker-compose up -d
+docker-compose up -d --build
 ```
- 3：访问入口
+- 4：访问入口
  - 浏览器打开 `http://<服务器IP或域名>:57778`
+- 5：在线重载截止时间（无需重启）
+```bash
+curl -X POST "http://<服务器>:57778/api/admin/reload_cutoff" -H "X-Admin-Token: $ADMIN_TOKEN"
+```

 ## 腾讯云环境优化
 - 使用腾讯云 PyPI 镜像：Dockerfile 已设置 `pip -i https://mirrors.cloud.tencent.com/pypi/simple`
@ -16,22 +22,33 @@ docker-compose up -d
 - 数据持久化：`docker-compose.yml` 将宿主机 `./data` 映射为容器 `/app/data`，数据库路径 `sqlite:///data/data.db`

 ## 功能概览
- 每日 23:00（服务器本地时区）自动生成并定版当日营业额
+- 每日截止时间（本地时区，支持分钟级，如 `13:18`）自动生成并定版当日营业额
 - 修正接口：支持按日期修正金额，前端即时一致更新；修正过程不直接在前端展示
 - 审计与日志：所有生成/修正写入审计表，兼容追加到 `app.log`
 - 看板：今日/昨日/前日、本周（周一～昨日）、上周（周一～周日）、本月
 - 折线图：最近 7 天、本月、上月、最近 90 天；支持缩放、导出图片/CSV
+ - 飞书推送：卡片 → 帖子 → 文本三段式兼容；支持签名与 IP 白名单

 ## 项目结构
 ```
 .
 ├── backend/                     # Flask API + APScheduler
 ├── frontend/                    # 单页 HTML（Tailwind+Chart.js）
-├── data/              # SQLite 数据卷（自动创建/挂载）
+├── data/                        # SQLite 数据卷（容器映射 /app/data）
+├── instance/                    # 历史/本地副本（当前不作为权威数据源）
+├── docs/
+│   └── 自动化营业额系统/
+│       ├── API.md               # 全量接口文档
+│       ├── DESIGN.md            # 设计说明
+│       └── PRD.md               # 需求说明
+├── scripts/
+│   ├── deploy.ps1               # Windows 一键部署/重载/试推
+│   └── deploy.sh                # Linux 一键部署/重载/试推
 ├── Dockerfile                   # 生产镜像（已适配腾讯云）
-├── docker-compose.yml # 一键部署
+├── docker-compose.yml           # 一键部署（映射 data 与 config）
 ├── .env.example                 # 环境变量示例（不要提交真实 .env）
-└── README.md
+├── README.md
+└── app.log                      # 运行日志（含飞书返回体片段）
 ```

 ## 环境变量
@ -39,6 +56,7 @@ docker-compose up -d
 - `ADMIN_TOKEN`：管理修正口令；修正时在请求头加入 `X-Admin-Token`
 - `TZ`：容器时区（默认 `Asia/Shanghai`）
 - `PORT`：应用监听端口（默认 `5000`，示例已改为 `57778`）
+ - `AUTO_IMPORT_ON_START`：启动时自动导入 `data/import.csv`（DB 为空时）

 ## 修正接口示例
 ```bash
@ -48,6 +66,16 @@ curl -X PUT http://localhost:5000/api/admin/turnover \
  -d '{"date":"2025-12-06","amount":3123.45,"reason":"调整入账"}'
 ```

+## 在线重载截止时间（无需重启）
+```bash
+curl -X POST "http://localhost:57778/api/admin/reload_cutoff" -H "X-Admin-Token: $ADMIN_TOKEN"
+```
+
+## 读取运行日志（含推送返回体片段）
+```bash
+curl "http://localhost:57778/api/admin/logs?lines=200" -H "X-Admin-Token: $ADMIN_TOKEN"
+```
+
 ## 数据预置与迁移
 - 首次启动自动导入（开启 `AUTO_IMPORT_ON_START=1` 且 DB为空）：
  - 如果存在 `/app/data/import.csv`（宿主机 `./data/import.csv`），自动导入该文件
@ -75,6 +103,20 @@ curl -X PUT http://localhost:5000/api/admin/turnover \
  $env:DATABASE_URL="sqlite:////e:/2025Code/python/YixuanYingye/data/data.db"; python backend/app.py
  ```

+## 飞书机器人配置
+- 使用飞书自定义机器人 Webhook：`https://open.feishu.cn/open-apis/bot/v2/hook/<ID>`
+- 如开启签名校验，在 `config.json` 设置 `feishu_secret`；未开启则留空
+- 如启用 IP 白名单，需在机器人配置中加入服务器出口公网 IP；否则会返回 `{"code":19022,"msg":"Ip Not Allowed"}`
+
+## API 文档
+- 详见 `docs/自动化营业额系统/API.md`
+
+## 归档建议
+- 保留以下文件以便复现与审计：
+  - `docs/自动化营业额系统/*`、`Dockerfile`、`docker-compose.yml`、`config.json`、`app.log`
+  - 生产数据卷：`data/data.db`（或导出的 CSV）
+- 如迁移外部数据库，建议取消数据卷映射并设置 `DATABASE_URL`（PostgreSQL/MySQL）
+
 ## 环境优化（最优解）
 - 基础镜像切换为 `python:3.11-alpine`，构建更快、体积更小
 - 依赖安装走腾讯云 PyPI 镜像：`PIP_INDEX_URL=https://mirrors.cloud.tencent.com/pypi/simple`
--- a/docs/自动化营业额系统/API.html
+++ b/docs/自动化营业额系统/API.html
@ -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>
--- a/docs/自动化营业额系统/Postman_Collection.json
+++ b/docs/自动化营业额系统/Postman_Collection.json
@ -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"
+      }
+    }
+  ]
+}
--- a/docs/自动化营业额系统/Postman_Environment.json
+++ b/docs/自动化营业额系统/Postman_Environment.json
@ -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 }
+  ]
+}