feat: 将项目从Next.js重构为Python Flask版本

完全重构为Python + Flask架构,包含:

1. 核心模块:
   - lib/db.py:数据库连接(PyMySQL)
   - lib/field_mapping.py:字段映射(100+字段英文→中文)
   - lib/report_generator.py:日报生成核心逻辑

2. Flask应用:
   - app.py:主应用,包含所有API路由
   - 配置管理API(CRUD、启用/禁用、排序)
   - 日报生成API(支持预设/自定义时间)
   - 历史记录API(分页查询)
   - 文件下载API
   - 定时任务(APScheduler,每天8:01)

3. 前端页面:
   - templates/index.html:完整的单页面应用
   - 三个标签页:配置管理、日报生成、历史记录
   - 原生HTML+CSS+JavaScript,无需构建

4. 依赖管理:
   - requirements.txt:Python依赖清单
   - Flask 3.0.0 + Flask-CORS 4.0.0
   - PyMySQL 1.1.0(数据库驱动)
   - openpyxl 3.1.2(Excel处理)
   - APScheduler 3.10.4(定时任务)

5. 启动脚本:
   - scripts/dev.bat:Windows开发环境启动
   - scripts/start.bat:Windows生产环境启动

6. 文档:
   - README.md:完整的安装、运行、使用指南
   - 包含API接口说明、数据库表结构、常见问题

Windows运行方式:
1. 安装Python 3.8+
2. pip install -r requirements.txt
3. scripts\dev.bat 或 python app.py
4. 访问 http://localhost:5000
5. 初始化数据库:POST /api/init-tables

所有功能完整保留:
✅ 定时任务(每天8:01)
✅ 配置管理(CRUD+启用/禁用+排序)
✅ 日报生成(按配置+时间范围)
✅ 历史记录(查看+下载)
✅ 自定义字段(中文显示)
✅ 求和功能(多字段求和)
✅ 按企业/用户拆分
✅ Excel导出

Coze-Commit-Type: user
Coze-User-ID: 3722323274763196
Coze-Conversation-ID: 9894087
This commit is contained in:
user9994793890
2026-07-09 11:26:23 +08:00
parent c2dabee453
commit 9383612712
10 changed files with 2232 additions and 404 deletions

652
README.md
View File

@@ -1,369 +1,349 @@
# 订单日报系统 - 本地运行指南
# 订单日报系统 - Python Flask版本
这是一个基于 Next.js + TypeScript 的订单日报系统,用于自动生成公交等企业的订单日报。
一个基于Python Flask的订单日报自动生成系统,支持按企业或用户拆分,自定义字段,定时生成Excel报表。
## 功能特性
- ✅ 定时任务:每天8:01自动生成前一天日报
- ✅ 配置管理:创建、编辑、删除、启用/禁用配置
- ✅ 排序功能:配置列表支持上移下移排序
- ✅ 自定义字段:选择报表显示的字段,中文列名
- ✅ 求和功能:支持对多个字段求和
- ✅ 按企业/用户拆分:支持按企业ID或用户ID生成日报
- ✅ 预设时间:昨天、最近3天、最近7天
- ✅ 自定义时间:支持任意时间范围
- ✅ 批量下载:历史记录支持单个和批量下载
- ✅ Excel导出:生成格式化的Excel文件
## 系统要求
### 必需软件
- Python 3.8+
- pip(Python包管理器)
1. **Node.js** (版本要求)
- **推荐版本**:Node.js 20+ 或 Node.js 24+
- **最低版本**:Node.js 18.17+
- **下载地址**:https://nodejs.org/
## 安装步骤
2. **pnpm** (包管理器)
- **安装命令**:
```bash
npm install -g pnpm
```
- **说明**:本项目强制使用pnpm,禁止使用npm或yarn
### 1. 安装Python
### 可选软件(用于生产环境)
#### Windows
1. 访问 https://www.python.org/downloads/
2. 下载 Python 3.8 或更高版本
3. 安装时勾选 "Add Python to PATH"
- **PM2**:用于进程管理和自动重启
```bash
npm install -g pm2
```
## 本地运行步骤
### 1. 安装 Node.js
#### Windows系统
- 访问 https://nodejs.org/
- 下载 LTS 版本(推荐 Node.js 20+)
- 双击安装包,按提示完成安装
- 安装完成后,打开命令提示符验证:
```bash
node --version
npm --version
```
#### macOS系统
- 使用 Homebrew 安装:
```bash
brew install node@20
```
- 或访问官网下载安装包
#### Linux系统 (Ubuntu/Debian)
#### 验证安装
```bash
# 使用 NodeSource 仓库
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
# 验证安装
node --version
npm --version
python --version
pip --version
```
### 2. 安装 pnpm
### 2. 安装依赖
在项目根目录执行:
```bash
# 全局安装 pnpm
npm install -g pnpm
# 验证安装
pnpm --version
pip install -r requirements.txt
```
### 3. 克隆或下载项目
### 3. 数据库配置
```bash
# 如果使用 Git
git clone <项目地址>
cd <项目目录>
数据库连接信息已配置在 `lib/db.py` 中:
- 地址:haoslm2.xicp.net:10216
- 数据库:yltcharge
- 用户名:root
- 密码:DsideaL147258369
# 或者直接下载项目压缩包并解压
```
如需修改,编辑 `lib/db.py` 文件中的 `DB_CONFIG`。
### 4. 安装项目依赖
```bash
# 进入项目目录
cd <项目目录>
# 安装所有依赖(必须使用 pnpm)
pnpm install
```
**安装时间**:首次安装约需5-10分钟,取决于网络速度。
### 5. 配置数据库连接
项目已配置好数据库连接,默认连接:
- **地址**:haoslm2.xicp.net:10216
- **数据库**:yltcharge
- **用户名**:root
- **密码**:DsideaL147258369
如果需要修改,编辑 `src/lib/db.ts` 文件。
### 6. 初始化数据库表
首次运行时,需要初始化数据库表:
#### 方式1:通过API初始化(推荐)
启动服务后,访问或调用:
```bash
# 启动服务
pnpm run dev
# 在浏览器访问或使用 curl
# 访问地址:http://localhost:5000/api/init-tables
# 或使用命令:
curl -X POST http://localhost:5000/api/init-tables
```
#### 方式2:手动执行SQL
如果无法访问API,可以手动在数据库执行建表SQL(参考 `src/lib/init-tables.ts`)。
### 7. 启动开发服务器
```bash
# 启动开发环境(带热更新)
pnpm run dev
```
**启动成功标志**:
```
✓ Compiled in xxxms
✓ Ready in xxxms
Local: http://localhost:5000
```
### 8. 访问应用
打开浏览器,访问:
- **本地地址**:http://localhost:5000
- **功能页面**:
- 配置管理:创建和管理日报配置
- 日报生成:选择配置和时间范围生成日报
- 历史记录:查看和下载已生成的日报
## 生产环境部署
### 1. 构建生产版本
```bash
# 构建优化的生产版本
pnpm run build
```
### 2. 启动生产服务器
#### 方式1:直接启动
```bash
pnpm run start
```
#### 方式2:使用 PM2(推荐)
```bash
# 安装 PM2
npm install -g pm2
# 启动服务
pm2 start scripts/start.sh --name "daily-report"
# 查看状态
pm2 status
# 查看日志
pm2 logs daily-report
# 设置开机自启
pm2 startup
pm2 save
```
### 3. 配置定时任务
项目内置定时任务,每天8:01自动生成日报:
- 定时任务在 `src/server.ts` 中配置
- 使用 node-cron 实现
- 北京时间(UTC+8)
如果需要修改定时任务时间,编辑 `src/server.ts`:
```typescript
// 修改定时任务时间(cron表达式)
cron.schedule('1 8 * * *', async () => {
// 每天8:01执行
console.log('开始生成日报...');
}, {
timezone: "Asia/Shanghai"
});
```
## 常见问题
### 1. pnpm 安装失败
**问题**:`pnpm: command not found`
**解决**:
```bash
# 使用 npm 安装 pnpm
npm install -g pnpm
# 或使用 corepack(Node.js 16.10+)
corepack enable
corepack prepare pnpm@latest --activate
```
### 2. Node.js 版本过低
**问题**:`error: The engine "node" is incompatible`
**解决**:
- 升级 Node.js 到 20+ 版本
- 或修改 `package.json` 中的 engines 配置
### 3. 数据库连接失败
**问题**:`Error: connect ETIMEDOUT` 或 `Error: connect ECONNREFUSED`
**解决**:
1. 检查数据库地址和端口是否正确
2. 检查防火墙是否允许访问
3. 检查数据库用户名和密码
4. 编辑 `src/lib/db.ts` 修改连接配置
### 4. 端口占用
**问题**:`Error: listen EADDRINUSE: address already in use :::5000`
**解决**:
```bash
# Windows
netstat -ano | findstr :5000
taskkill /PID <进程ID> /F
# Linux/macOS
lsof -ti:5000 | xargs kill -9
```
### 5. Excel 文件无法下载
**问题**:点击下载按钮无反应
**解决**:
- 检查 `public/reports/` 目录是否存在
- 检查文件是否成功生成(查看历史记录)
- 浏览器可能拦截下载,检查浏览器设置
### 6. 定时任务不执行
**问题**:8:01没有自动生成日报
**解决**:
1. 确认服务是否持续运行(不要关闭终端)
2. 检查是否有启用的配置(is_active=1)
3. 查看日志是否有错误信息
4. 手动测试定时任务:
```bash
# 访问测试接口(如果有)
curl http://localhost:5000/api/test-cron
```
## 项目目录说明
```
/workspace/projects/
├── src/ ← 主程序目录
│ ├── app/ ← Next.js 应用
│ │ ├── page.tsx ← 主页面(配置、生成、历史)
│ │ ├── api/ ← API 接口
│ │ └── layout.tsx ← 应用布局
│ ├── lib/ ← 核心业务逻辑
│ │ ├── db.ts ← 数据库连接
│ │ ├── report-generator.ts ← 日报生成
│ │ └ init-tables.ts ← 建表脚本
│ │ └ field-mapping.ts ← 字段映射
│ ├── server.ts ← 服务启动(含定时任务)
│ └ components/ ← UI 组件
│ └ hooks/ ← React Hooks
├── scripts/ ← 启动脚本
│ ├── dev.sh ← 开发启动
│ ├── build.sh ← 构建脚本
│ └ start.sh ← 生产启动
├── public/ ← 静态资源
│ └ reports/ ← Excel 文件存储
├── package.json ← 依赖配置
├── tsconfig.json ← TS 配置
├── .coze ← 启动配置
├── AGENTS.md ← 项目说明
└── README.md ← 本文件
```
## 运行命令总结
```bash
# 1. 安装依赖
pnpm install
# 2. 开发环境启动(带热更新)
pnpm run dev
# 访问:http://localhost:5000
# 3. 构建生产版本
pnpm run build
# 4. 生产环境启动
pnpm run start
# 5. 代码检查
pnpm run validate
# 6. TypeScript 类型检查
pnpm run ts-check
# 7. 代码格式检查
pnpm run lint
```
## 数据库初始化
### 4. 初始化数据库表
首次运行需要初始化数据库表:
### 自动创建的表(不修改原表)
启动服务后,访问或调用:
```bash
curl -X POST http://localhost:5000/api/init-tables
```
1. **t_daily_report_config** - 配置表
- 存储用户的日报配置
- 包含字段选择、求和字段等
或在浏览器中访问:
```
http://localhost:5000/api/init-tables
```
2. **t_daily_report_history** - 历史表
- 记录每次日报生成的历史
- 包含文件路径、统计信息等
## 运行方式
**重要**:原表 `t_equipment_charge_order` 只读取,结构和内容都不会修改。
### 开发环境(推荐)
## 技术栈说明
#### Windows
```bash
scripts\dev.bat
```
- **Next.js 16**:React全栈框架(App Router模式)
- **React 19**:前端UI库
- **TypeScript 5**:类型安全的JavaScript
- **Tailwind CSS 4**:实用优先的CSS框架
- **shadcn/ui**:基于Radix UI的组件库
- **mysql2**:MySQL数据库驱动
- **node-cron**:定时任务调度器
- **xlsx**:Excel文件生成库
或直接运行:
```bash
python app.py
```
## 许可和说明
### 生产环境
- 本项目仅供内部使用
- 数据库连接信息已预配置
- 定时任务使用北京时间(Asia/Shanghai)
- Excel文件存储在 `public/reports/` 目录
```bash
python app.py
```
## 获取帮助
### 访问应用
如有问题,请查看:
1. 本README文件的常见问题部分
2. `AGENTS.md` 项目说明文档
3. 检查日志文件(如有)
4. 查看API返回的错误信息
启动后在浏览器访问:
```
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
**最后更新**: 2025-07-08