ylt_diy/README.md

# 订单日报系统 - Python Flask版本

一个基于Python Flask的订单日报自动生成系统，支持按企业或用户拆分，自定义字段，定时生成Excel报表。

## 功能特性

- ✅ 定时任务：每天8:01自动生成前一天日报
- ✅ 配置管理：创建、编辑、删除、启用/禁用配置
- ✅ 排序功能：配置列表支持上移下移排序
- ✅ 自定义字段：选择报表显示的字段，中文列名
- ✅ 求和功能：支持对多个字段求和
- ✅ 按企业/用户拆分：支持按企业ID或用户ID生成日报
- ✅ 预设时间：昨天、最近3天、最近7天
- ✅ 自定义时间：支持任意时间范围
- ✅ 批量下载：历史记录支持单个和批量下载
- ✅ Excel导出：生成格式化的Excel文件

## 系统要求

- Python 3.8+
- pip（Python包管理器）

## 安装步骤

### 1. 安装Python

#### Windows
1. 访问 https://www.python.org/downloads/
2. 下载 Python 3.8 或更高版本
3. 安装时勾选 "Add Python to PATH"

#### 验证安装
```bash
python --version
pip --version
```

### 2. 安装依赖

在项目根目录执行：
```bash
pip install -r requirements.txt
```

### 3. 数据库配置

数据库连接信息已配置在 `lib/db.py` 中：
- 地址：haoslm2.xicp.net:10216
- 数据库：yltcharge
- 用户名：root
- 密码：DsideaL147258369

如需修改，编辑 `lib/db.py` 文件中的 `DB_CONFIG`。

### 4. 初始化数据库表

首次运行需要初始化数据库表：

启动服务后，访问或调用：
```bash
curl -X POST http://localhost:5000/api/init-tables
```

或在浏览器中访问：
```
http://localhost:5000/api/init-tables
```

## 运行方式

### 开发环境（推荐）

#### Windows
```bash
scripts\dev.bat
```

或直接运行：
```bash
python app.py
```

### 生产环境

```bash
python app.py
```

### 访问应用

启动后在浏览器访问：
```
http://localhost:5000
```

## 使用指南

### 1. 创建配置

1. 点击"配置管理"标签
2. 点击"创建配置"按钮
3. 填写配置信息：
   - 配置名称：如"79路公交日报"
   - 拆分方式：选择"按企业ID"或"按用户ID"
   - 选择企业/用户：从下拉列表选择
   - 选择字段：勾选需要显示的字段
   - 求和字段：勾选需要求和的字段（可选）
4. 点击"保存"

### 2. 生成日报

1. 点击"日报生成"标签
2. 选择配置
3. 选择时间范围：
   - 点击预设按钮（昨天、最近3天、最近7天）
   - 或自定义时间范围
4. 点击"生成日报"
5. 生成成功后点击"下载Excel"

### 3. 查看历史

1. 点击"历史记录"标签
2. 查看所有生成的日报记录
3. 点击"下载"按钮下载Excel文件

### 4. 定时任务

系统会在每天8:01（北京时间）自动为所有启用的配置生成日报。

## 项目结构

```
.
├── app.py                      # Flask主应用
├── requirements.txt            # Python依赖
├── lib/                        # 业务逻辑模块
│   ├── __init__.py
│   ├── db.py                   # 数据库连接
│   ├── field_mapping.py        # 字段映射（英文->中文）
│   └── report_generator.py     # 日报生成核心逻辑
├── templates/                  # HTML模板
│   └── index.html              # 主页面
├── public/                     # 静态文件
│   └── reports/                # 生成的Excel文件
├── scripts/                    # 启动脚本
│   ├── dev.bat                 # Windows开发环境启动
│   └── start.bat               # Windows生产环境启动
└── README.md                   # 说明文档
```

## API接口

### 配置管理
- `GET /api/config` - 获取所有配置
- `POST /api/config` - 创建配置
- `PUT /api/config/<id>` - 更新配置
- `DELETE /api/config/<id>` - 删除配置
- `POST /api/config/<id>/toggle` - 启用/禁用配置
- `POST /api/config/<id>/move` - 移动配置排序

### 企业和用户
- `GET /api/entities?type=company` - 获取企业列表
- `GET /api/entities?type=user` - 获取用户列表

### 字段
- `GET /api/fields` - 获取所有可用字段

### 日报生成
- `POST /api/report/generate` - 生成日报

### 历史记录
- `GET /api/report/history` - 获取历史记录（分页）

### 文件下载
- `GET /api/download?path=<file_path>` - 下载Excel文件

### 数据库初始化
- `POST /api/init-tables` - 初始化数据库表

## 数据库表说明

### t_daily_report_config（配置表）

存储日报配置信息：
- id: 配置ID
- config_name: 配置名称
- split_type: 拆分方式（company_id/user_id）
- split_value: 拆分值
- split_name: 拆分显示名称
- selected_fields: 选择的字段列表（JSON）
- sum_fields: 求和字段列表（JSON）
- is_active: 是否启用
- sort_order: 排序顺序
- create_time: 创建时间
- update_time: 更新时间

### t_daily_report_history（历史表）

存储日报生成历史：
- id: 历史ID
- report_date: 报表日期
- start_time: 开始时间
- end_time: 结束时间
- split_type: 拆分方式
- split_value: 拆分值
- split_name: 拆分显示名称
- config_id: 配置ID
- total_orders: 订单总数
- total_amount: 总金额
- sum_results: 求和结果（JSON）
- file_path: 文件路径
- status: 状态（0=失败，1=成功）
- create_time: 创建时间

## 常见问题

### 1. 端口5000被占用

修改 `app.py` 中的端口：
```python
port = int(os.environ.get('PORT', 5001))  # 改为其他端口
```

或设置环境变量：
```bash
set PORT=5001  # Windows
export PORT=5001  # Linux/Mac
python app.py
```

### 2. 数据库连接失败

检查：
- 数据库地址和端口是否正确
- 防火墙是否放行
- 数据库用户名和密码是否正确

测试连接：
```python
python -c "from lib.db import execute_query; print(execute_query('SELECT 1'))"
```

### 3. 定时任务不执行

确保：
- 服务持续运行（不要关闭终端）
- 至少有一个启用的配置
- 系统时区正确（Asia/Shanghai）

### 4. Excel文件无法下载

检查：
- `public/reports/` 目录是否存在
- 文件是否已生成
- 浏览器是否允许下载

### 5. 中文乱码

确保：
- 数据库字符集为 utf8mb4
- Python文件编码为 UTF-8
- HTML页面编码为 UTF-8

## 开发说明

### 添加新字段

编辑 `lib/field_mapping.py`，在 `FIELD_MAPPING` 字典中添加：
```python
'new_field': '新字段中文名'
```

### 修改定时任务时间

编辑 `app.py`，修改：
```python
scheduler.add_job(scheduled_job, 'cron', hour=8, minute=1)  # 改为其他时间
```

### 修改数据库配置

编辑 `lib/db.py`，修改 `DB_CONFIG`：
```python
DB_CONFIG = {
    'host': '新地址',
    'port': 新端口,
    'user': '新用户名',
    'password': '新密码',
    'database': '新数据库',
}
```

## 部署建议

### 使用Gunicorn（生产环境）

```bash
pip install gunicorn
gunicorn -w 4 -b 0.0.0.0:5000 app:app
```

### 使用Supervisor管理进程

创建 `/etc/supervisor/conf.d/daily-report.conf`：
```ini
[program:daily-report]
command=/usr/bin/python /path/to/app.py
directory=/path/to/project
autostart=true
autorestart=true
stderr_logfile=/var/log/daily-report.err.log
stdout_logfile=/var/log/daily-report.out.log
```

### 使用Nginx反向代理

```nginx
server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

## 技术栈

- **后端**: Python 3.8+ / Flask 3.0
- **数据库**: MySQL / Apache Doris
- **数据库驱动**: PyMySQL
- **Excel处理**: openpyxl
- **定时任务**: APScheduler
- **前端**: HTML + CSS + JavaScript（原生）

## 许可证

MIT License

## 联系方式

如有问题，请联系开发团队。

---

**最后更新**: 2025-07-08