diff --git a/README.md b/README.md index 7bd96ee..7dba0d5 100644 --- 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 数据卷（自动创建/挂载） -├── Dockerfile # 生产镜像（已适配腾讯云） -├── docker-compose.yml # 一键部署 -├── .env.example # 环境变量示例（不要提交真实 .env） -└── README.md +├── backend/ # Flask API + APScheduler +├── frontend/ # 单页 HTML（Tailwind+Chart.js） +├── data/ # SQLite 数据卷（容器映射 /app/data） +├── instance/ # 历史/本地副本（当前不作为权威数据源） +├── docs/ +│ └── 自动化营业额系统/ +│ ├── API.md # 全量接口文档 +│ ├── DESIGN.md # 设计说明 +│ └── PRD.md # 需求说明 +├── scripts/ +│ ├── deploy.ps1 # Windows 一键部署/重载/试推 +│ └── deploy.sh # Linux 一键部署/重载/试推 +├── Dockerfile # 生产镜像（已适配腾讯云） +├── docker-compose.yml # 一键部署（映射 data 与 config） +├── .env.example # 环境变量示例（不要提交真实 .env） +├── 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/` +- 如开启签名校验，在 `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` diff --git a/docs/自动化营业额系统/API.html b/docs/自动化营业额系统/API.html new file mode 100644 index 0000000..6837b96 --- /dev/null +++ b/docs/自动化营业额系统/API.html @@ -0,0 +1,121 @@ + + + + + + 项目 API 文档（益选营业额系统） + + + +

项目 API 文档（益选营业额系统）

+

基础地址：http://<服务器或域名>:<PORT>（默认 57778） | 本地时区：Asia/Shanghai

+

认证

+ +

公共字段

+ + +
+

GET /api/metrics

+

指标看板：今日/昨日/前日、本周、上周、本月；达到截止时间且今日已定版时显示金额。

+ 
{
+  "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 }
+}
+
+ +
+

GET /api/series7

+

最近 N 天序列（默认 7，范围 7～90）。未到截止或今日未定版时，截止到昨日；未定版日期按区间估算并标记 estimated=true。

+ 
[ { "date": "2025-12-06", "amount": 1803.09, "estimated": false }, ... ]
+
+ +
+

GET /api/revenue

+

历史营业额查询（仅定版数据）。参数：days 默认 30。

+
+ +
+

GET /api/audit

+

审计日志。参数：days 默认 30。

+
+ +
+

GET /api/health

+

健康检查。

+
+ +
+

GET /api/export

+

导出 CSV（仅定版）。

+
+ +
+

GET /

+

看板入口（静态）。

+

GET /admin

+

管理入口（静态）。

+
+ +
+

PUT /api/admin/turnover

+

修正某日营业额（置为定版并推送）。头：X-Admin-Token

+ 
{ "date":"YYYY-MM-DD", "amount":1234.56, "reason":"调整入账", "actor":"admin" }
+
+ +
+

POST /api/admin/test_push

+

试发飞书（卡片→帖子→文本）。头：X-Admin-Token

+ 
{ "date":"YYYY-MM-DD", "amount":1234.56, "reason":"manual_test" }
+
+ +
+

POST /api/admin/import

+

批量导入 CSV（两列：date,amount）。头：X-Admin-Token，Content-Type: text/csv

+
+ +
+

GET /api/admin/logs

+

读取 app.log 最近 N 行。参数：lines；头：X-Admin-Token

+
+ +
+

POST /api/admin/reload_cutoff

+

在线重载截止时间（更新 APScheduler 的每日触发任务并立即执行一次结算检查）。头：X-Admin-Token

+
+ +
+

GET /api/events

+

SSE 心跳事件（每 30 秒；在每小时第 0/1 分触发强制刷新与结算检查）。

+
+ +

打印为 PDF

+ + + diff --git a/docs/自动化营业额系统/Postman_Collection.json b/docs/自动化营业额系统/Postman_Collection.json new file mode 100644 index 0000000..6dec0fd --- /dev/null +++ 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" + } + } + ] +} diff --git a/docs/自动化营业额系统/Postman_Environment.json b/docs/自动化营业额系统/Postman_Environment.json new file mode 100644 index 0000000..d87e3f6 --- /dev/null +++ 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 } + ] +}