130 lines
5.8 KiB
Markdown
130 lines
5.8 KiB
Markdown
# 自动化营业额数据推送与展示系统
|
||
|
||
## 快速部署（Docker）
|
||
- 1：准备环境变量（不要提交真实口令到仓库）
|
||
- 复制 `.env.example` 到 `.env` 并填写 `ADMIN_TOKEN`
|
||
- 2：配置映射（确保容器读取宿主机配置与数据）
|
||
- `docker-compose.yml` 已映射：`./data:/app/data`、`./config.json:/app/config.json:ro`
|
||
- 3：启动服务
|
||
```bash
|
||
docker-compose up -d --build
|
||
```
|
||
- 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`
|
||
- 设置时区为 `Asia/Shanghai`：Dockerfile 安装并配置 `tzdata`
|
||
- 数据持久化：`docker-compose.yml` 将宿主机 `./data` 映射为容器 `/app/data`，数据库路径 `sqlite:///data/data.db`
|
||
|
||
## 功能概览
|
||
- 每日截止时间（本地时区，支持分钟级，如 `13:18`）自动生成并定版当日营业额
|
||
- 修正接口：支持按日期修正金额，前端即时一致更新；修正过程不直接在前端展示
|
||
- 审计与日志：所有生成/修正写入审计表，兼容追加到 `app.log`
|
||
- 看板：今日/昨日/前日、本周（周一～昨日）、上周（周一～周日）、本月
|
||
- 折线图：最近 7 天、本月、上月、最近 90 天；支持缩放、导出图片/CSV
|
||
- 飞书推送：卡片 → 帖子 → 文本三段式兼容；支持签名与 IP 白名单
|
||
|
||
## 项目结构
|
||
```
|
||
.
|
||
├── 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 # 运行日志（含飞书返回体片段）
|
||
```
|
||
|
||
## 环境变量
|
||
- `DATABASE_URL`：数据库连接字符串（默认 `sqlite:///data/data.db`）
|
||
- `ADMIN_TOKEN`：管理修正口令；修正时在请求头加入 `X-Admin-Token`
|
||
- `TZ`：容器时区（默认 `Asia/Shanghai`）
|
||
- `PORT`：应用监听端口（默认 `5000`，示例已改为 `57778`）
|
||
- `AUTO_IMPORT_ON_START`：启动时自动导入 `data/import.csv`（DB 为空时）
|
||
|
||
## 修正接口示例
|
||
```bash
|
||
curl -X PUT http://localhost:5000/api/admin/turnover \
|
||
-H "Content-Type: application/json" \
|
||
-H "X-Admin-Token: $ADMIN_TOKEN" \
|
||
-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`），自动导入该文件
|
||
- CSV格式：
|
||
```
|
||
date,amount
|
||
2025-12-01,12345.67
|
||
2025-12-02,11890.12
|
||
```
|
||
- 手动导入接口：
|
||
```bash
|
||
curl -X POST http://<服务器>:57778/api/admin/import \
|
||
-H "X-Admin-Token: $ADMIN_TOKEN" -H "Content-Type: text/csv" \
|
||
--data-binary @revenue.csv
|
||
```
|
||
|
||
## 本地运行（默认数据库路径）
|
||
- 默认数据库：`sqlite:///data/data.db`（项目根目录下的 `data/data.db`）
|
||
- 启动：
|
||
```powershell
|
||
$env:PORT=57778; $env:ADMIN_TOKEN="<你的口令>"; python backend/app.py
|
||
```
|
||
- 自定义路径（Windows 绝对路径示例）：
|
||
```powershell
|
||
$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`
|
||
- 自动数据导入：环境变量 `AUTO_IMPORT_ON_START=1`，启动时按顺序导入
|
||
- `/app/data/import.csv`（宿主机 `./data/import.csv`）
|
||
|
||
## 生产建议
|
||
- 建议使用反向代理（Nginx）暴露 `5000` 端口，并开启 gzip
|
||
- 建议通过 `docker-compose` 的 `restart: unless-stopped` 保持服务稳定
|
||
- 如需外部数据库，设置 `DATABASE_URL`（例如 PostgreSQL），并移除数据卷映射
|