推送给招商

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

@@ -0,0 +1,75 @@
+# 自动化营业额数据推送与展示系统 技术架构
+
+## 技术栈
+- 后端：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` 管理数据库与通知凭据
+- 简易登录：基于环境变量开关，默认关闭
+