PushToZhaoShang/docs/自动化营业额系统/DESIGN.md

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

技术栈

• 后端：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 示例

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 管理数据库与通知凭据
• 简易登录：基于环境变量开关，默认关闭