SaleShow/README.md

# 📊 销售数据分析器

一个现代化的Web应用程序，用于分析和可视化销售数据。支持Excel文件上传、自动从 secsion.com 获取数据，提供丰富的分析功能和美观的界面展示。

## ✨ 功能特性

### 🎯 核心功能
- **Excel文件上传** - 支持.xlsx和.xls格式文件
- **智能数据解析** - 自动识别销售数据结构
- **多文件管理** - 支持多个Excel文件的切换查看
- **数据筛选** - 按金额范围进行数据筛选
- **搜索功能** - 支持商品名称搜索

### 🤖 自动化功能
- **自动获取数据** - 从 secsion.com 自动下载销售报表
- **店铺筛选** - 支持指定店铺 ID，仅导出目标店铺数据
- **Web UI 触发** - 在页面上选择日期范围一键下载
- **定时自动下载** - 每日凌晨自动获取前一天数据（APScheduler）
- **设置页面** - 在 Web UI 配置 secsion.com 账号密码、店铺 ID、定时任务
- **CLI 支持** - 命令行直接运行 `python -m automation.secsion --start 2026-04-28`

### 📊 数据展示
- **销售总览** - 显示总销售额、销售天数、商品种类等统计信息
- **每日详情** - 按日期分组展示销售数据
- **双视图模式** - 支持卡片视图和表格视图切换
- **表格排序** - 点击表头实现数据排序（升序/降序/原始顺序）

### 🎨 用户界面 (New)
- **玻璃拟态设计** - 采用现代流行的 Glassmorphism 风格，视觉精致小巧。
- **移动端深度优化** - 针对手机屏幕调整布局，商品信息单行显示，更紧凑易读。
- **流畅交互** - 添加数字滚动、展开/折叠等微交互动画。

### 🔧 技术特性
- **智能解析** - 支持“扁平表”和“层级表”两种格式，精准识别交易时间（精确到秒）。
- **高性能** - 基于 Pandas 向量化操作，快速处理大数据量。
- **Docker支持** - 提供完整的 Docker 容器化部署方案。

## 🚀 快速开始

### 系统要求

- **Python** 3.8+
- **操作系统** Windows/Linux/macOS
- **浏览器** 现代浏览器（Chrome、Firefox、Safari、Edge）

### 安装步骤

#### 1. 克隆项目
```bash
git clone https://gitea.94kan.cn/houhuan/SaleShow.git
cd SaleShow
```

#### 2. 创建虚拟环境（推荐）
```bash
# Windows
python -m venv venv
venv\Scripts\activate

# Linux/macOS
python -m venv venv
source venv/bin/activate
```

#### 3. 安装依赖
```bash
pip install -r requirements.txt
```

#### 4. 运行应用
```bash
python app.py
```

#### 5. 访问应用
打开浏览器，访问：http://localhost:5000

## 📖 使用指南

### 上传文件
1. 点击"上传Excel文件"按钮
2. 选择.xlsx或.xls格式的Excel文件
3. 等待文件处理完成
4. 查看分析结果

### 查看数据
- **左侧面板** - 显示已上传的文件列表，点击可切换查看不同文件
- **顶部统计** - 显示销售总览信息
- **每日数据** - 按日期分组展示详细销售记录

### 数据操作
- **视图切换** - 点击日期卡片右上角的图标可在卡片视图和表格视图间切换
- **表格排序** - 在表格视图中点击列标题可进行排序
- **数据筛选** - 使用底部的筛选按钮按金额范围筛选数据
- **搜索功能** - 在搜索框中输入商品名称进行搜索

### 文件管理
- **清理文件** - 点击"清理文件"按钮可删除所有上传的Excel文件
- **自动加载** - 页面刷新时自动加载最新上传的文件

### 自动获取数据
1. **配置凭据** - 点击"设置"进入设置页面，填写 secsion.com 账号密码和店铺 ID
2. **手动获取** - 点击"自动获取"按钮，选择日期范围，点击"开始下载"
3. **定时获取** - 在设置页面启用定时任务，系统每日凌晨自动下载前一天数据
4. **CLI 模式** - 命令行运行：
   ```bash
   # 下载指定日期数据
   python -m automation.secsion --start 2026-04-28 --end 2026-04-28

   # 指定用户名密码
   python -m automation.secsion --start 2026-04-28 --username 18190686888 --password yourpassword
   ```

> **配置优先级**: Web UI 设置页 > 环境变量 (.env) > 默认值

## 🏗️ 部署说明

### 开发环境部署
按照"快速开始"部分的步骤即可。

### 生产环境部署

#### 使用Gunicorn（推荐）
```bash
pip install gunicorn
gunicorn -w 4 -b 0.0.0.0:8000 app:app
```

### 使用 Docker Compose 部署 (推荐)

我们在项目中提供了 `docker-compose.yml`，这是最简单的部署方式。

1. **一键启动**
   ```bash
   docker-compose up -d
   ```

2. **访问应用**
   浏览器访问 `http://localhost:5000`

3. **修改端口 (可选)**
   ```bash
   # Linux/Mac
   APP_PORT=8080 docker-compose up -d
   
   # Windows PowerShell
   $env:APP_PORT="8080"; docker-compose up -d
   ```

### 环境变量配置

复制 `.env.example` 为 `.env` 并填写：

```bash
cp .env.example .env
```

主要配置项：

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `SECSION_USERNAME` | secsion.com 用户名 | - |
| `SECSION_PASSWORD` | secsion.com 密码 | - |
| `SECSION_SHOP_ID` | 店铺 ID（留空导出所有） | 空 |
| `SCHEDULER_ENABLED` | 是否启用定时任务 | true |
| `SCHEDULER_HOUR` | 定时任务执行小时 | 1 |
| `SCHEDULER_MINUTE` | 定时任务执行分钟 | 0 |
| `FLASK_DEBUG` | Flask 调试模式 | False |
| `PORT` | 服务端口 | 5000 |

## 📁 项目结构

```
SaleShow/
├── app.py                 # Flask应用主文件
├── config.py              # 配置管理模块
├── automation/            # 自动化模块
│   ├── __init__.py
│   ├── secsion.py         # secsion.com 登录+导出逻辑
│   ├── uploader.py        # 本地文件导入
│   └── scheduler.py       # APScheduler 定时任务
├── requirements.txt       # Python依赖包列表
├── Dockerfile             # Docker构建文件
├── docker-compose.yml     # Docker Compose配置
├── .env.example           # 环境变量配置示例
├── static/                # 静态资源目录
│   ├── css/
│   │   └── style.css      # 样式文件
│   └── js/
│       └── main.js        # 交互逻辑
├── templates/
│   ├── index.html         # 前端HTML模板
│   └── settings.html      # 设置页面
├── uploads/               # 上传文件存储目录（持久化挂载）
├── data/                  # 配置数据目录（持久化挂载）
├── downloads/             # 自动下载临时目录
└── README.md              # 项目说明文档
```

## 🛠️ 技术栈

### 后端
- **Flask** 2.3.3 - Web框架
- **pandas** 2.3.3 - 数据处理
- **openpyxl** 3.1.5 - Excel文件处理
- **xlrd** 2.0.1 - 旧版Excel文件支持
- **Playwright** - 浏览器自动化（secsion.com 数据获取）
- **APScheduler** - 定时任务调度
- **python-dotenv** - 环境变量管理

### 前端
- **HTML5** - 页面结构
- **CSS3** - 样式设计
- **JavaScript (ES6+)** - 交互功能
- **Font Awesome 6.4.0** - 图标库

### 开发工具
- **Git** - 版本控制
- **pip** - 包管理
- **Docker** - 容器化部署

## 📡 API 接口

| 路由 | 方法 | 说明 |
|------|------|------|
| `/` | GET | 首页（数据分析页面） |
| `/settings` | GET | 设置页面 |
| `/files` | GET | 获取已上传文件列表 |
| `/load/<filename>` | GET | 加载指定文件数据 |
| `/upload` | POST | 上传 Excel 文件 |
| `/delete/<filename>` | POST | 删除指定文件 |
| `/cleanup` | POST | 清理所有上传文件 |
| `/api/settings` | GET/POST | 获取/保存配置 |
| `/api/auto-download` | POST | 触发自动下载 |
| `/api/auto-download/status` | GET | 查询下载任务状态 |
| `/api/scheduler/status` | GET | 查询定时任务状态 |

## 🔒 安全说明

- 文件上传仅支持.xlsx和.xls格式
- 文件大小限制为16MB
- 使用安全的文件名处理
- 定期清理上传的文件以释放磁盘空间

## 🤝 贡献指南

1. Fork 本项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 📞 联系方式

如有问题或建议，请通过以下方式联系：
- 项目地址：https://gitea.94kan.cn/houhuan/SaleShow
- 提交 Issue：项目仓库的Issues页面

---

**最后更新时间：** 2026年4月29日

*享受数据分析的乐趣！📊✨*