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

## 技术栈
- 后端：FastAPI（Python）
- 定时：APScheduler（内嵌）/ Celery（可选）
- 数据库：SQLite（开发默认）/ PostgreSQL（生产）
- 前端：React + Tailwind（或 Vue + Tailwind）
- 部署：Docker + Docker Compose

## 系统架构
```
[Generator & Scheduler] -> [FastAPI REST] -> [DB]
                           |                
                           -> [Web UI]
                           -> [Notifier]
```

## 数据模型
- 表：`turnover`
  - `id` INTEGER PK
  - `date` DATE UNIQUE
  - `amount` DECIMAL(12,2)
  - `created_at` TIMESTAMP
- 表：`config`
  - `key` TEXT PK
  - `value` TEXT

## API 契约
- `GET /api/turnover/today` 返回当日数据
- `GET /api/turnover/range?start=YYYY-MM-DD&end=YYYY-MM-DD` 区间查询
- `GET /api/turnover/export.csv` 导出 CSV
- `POST /api/admin/recompute?date=YYYY-MM-DD` 重新生成指定日期（管理员）

## 定时方案
- APScheduler `cron` 每日 `00:05` 触发生成任务
- 任务幂等：同日重复执行将覆盖/更新当日记录

## 容器化
- `backend`：FastAPI + APScheduler
- `frontend`：静态构建产物挂载到 `nginx` 或 `vite preview`
- `db`：SQLite 挂载卷 / 可切换 PostgreSQL 服务
- `notifier`：邮件/Webhook 可选模块

## Docker Compose 示例
```yaml
services:
  backend:
    build: ./backend
    env_file: .env
    volumes:
      - ./data:/app/data
    ports:
      - "8000:8000"
  frontend:
    build: ./frontend
    ports:
      - "3000:3000"
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: example
    volumes:
      - ./pgdata:/var/lib/postgresql/data
    ports:
      - "5432:5432"
```

## 异常与告警
- 生成失败：记录日志并触发邮件/Webhook（启用时）
- API 错误：统一异常处理中返回标准错误响应

## 安全与配置
- `.env` 管理数据库与通知凭据
- 简易登录：基于环境变量开关，默认关闭