# 自动化营业额数据推送与展示系统

## 快速部署（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），并移除数据卷映射