# 订单日报系统 - 项目开发指南

## 项目概述

订单日报系统是一个基于 Flask 的 Web 应用，用于自动生成充电订单的日报报表。系统支持按企业/用户/场站拆分数据，自定义字段和求和功能，并支持合并特来电平台数据。

## 技术栈

- **后端**: Python 3.12 + Flask 3.0
- **数据库**: Apache Doris (MySQL 兼容)
- **前端**: 原生 HTML/CSS/JavaScript
- **依赖**: PyMySQL, APScheduler, openpyxl, Flask-CORS

## 项目结构

```
.
├── app.py                      # Flask 主应用（页面路由 + 定时任务）
├── lib/
│   ├── __init__.py
│   ├── db.py                   # 数据库连接配置
│   ├── field_mapping.py        # 字段映射定义
│   ├── report_generator.py     # 日报生成核心逻辑
│   ── api/                    # API 蓝图模块
│       ├── __init__.py         # 蓝图注册
│       ├── config_api.py       # 配置管理 API
│       ├── entity_api.py       # 实体管理 API（企业/用户/场站）
│       ├── field_api.py        # 字段列表 API
│       ├── report_api.py       # 日报生成和历史记录 API
│       ├── init_api.py         # 数据库初始化 API
│       └── download_api.py     # 文件下载 API
├── static/
│   ├── css/
│   │   └── style.css           # 全局样式
│   └── js/
│       ├── common.js           # 通用工具函数、标签切换
│       ├── config.js           # 配置管理（创建/编辑/复制/删除）
│       ├── entity.js           # 实体管理（分页/搜索）
│       ├── report.js           # 日报生成
│       └── history.js          # 历史记录（查看/下载/删除）
── templates/
│   └── index.html              # 主页面 HTML 结构
└── public/
    └── reports/                # 生成的报表文件目录
```

## 核心功能模块

### 1. 配置管理 (`lib/api/config_api.py`)
- 创建/编辑/删除/复制配置
- 启用/禁用配置
- 配置排序（上移/下移）
- 配置字段：
  - `config_name`: 配置名称
  - `split_type`: 拆分方式（company_id/user_id/station_id）
  - `split_value`: 拆分值（支持多选，逗号分隔）
  - `selected_fields`: 选择的字段列表（JSON）
  - `sum_fields`: 求和字段列表（JSON）
  - `time_periods`: 分时段电量配置（JSON）
  - `merge_telecom`: 是否合并特来电数据
  - `telecom_vehicle_no`: 特来电车量自编号
  - `field_custom_names`: 字段自定义报表名头（JSON）

### 2. 实体管理 (`lib/api/entity_api.py`)
- 企业列表（t_company，company_state=0 为启用）
- 用户列表（t_user，支持手机号搜索）
- 场站列表（t_station）
- 支持分页和搜索

### 3. 日报生成 (`lib/report_generator.py`)
- 按配置生成日报
- 支持分时段电量统计（尖/峰/平/谷）
- 支持合并特来电平台数据（t_hlht_tld 表）
- 补单检测（finish_type=2）
- 报表命名：`{config_name}_{month}月{day}日消费记录.xlsx`

### 4. 历史记录 (`lib/api/report_api.py`)
- 查看生成历史
- 下载报表文件
- 批量删除历史记录
- 按日期范围查询

## 数据库表

### t_daily_report_config（配置表）
- 存储日报生成配置
- 支持 JSON 字段存储复杂配置

### t_daily_report_history（历史表）
- 存储每次生成的历史记录
- 包含报表日期、时间范围、订单数、总金额等

### 业务表
- `t_equipment_charge_order`: 充电订单表
- `t_equipment_charge_order_detail`: 分时段电量表
- `t_company`: 企业表
- `t_user`: 用户表
- `t_station`: 场站表
- `t_equipment`: 设备表
- `t_connector`: 连接器表
- `t_hlht_tld`: 特来电平台数据表

## 开发规范

### 后端开发
1. 新增 API 路由时，在 `lib/api/` 目录下创建对应的蓝图模块
2. 在 `lib/api/__init__.py` 中注册新蓝图
3. 数据库操作使用 `lib/db.py` 提供的工具函数
4. 字段映射定义在 `lib/field_mapping.py` 中维护

### 前端开发
1. CSS 样式统一在 `static/css/style.css` 中维护
2. JavaScript 按功能模块拆分到 `static/js/` 目录
3. HTML 结构保持在 `templates/index.html` 中
4. 使用语义化类名，避免硬编码颜色值

### 代码风格
- Python 遵循 PEP 8 规范
- JavaScript 使用 ES6+ 语法
- 注释使用中文，关键逻辑必须添加注释

## 定时任务

系统使用 APScheduler 实现定时任务：
- 每天 08:01 自动执行日报生成
- 遍历所有启用的配置，逐一生成日报

## 部署说明

### 环境变量
- `DEPLOY_RUN_PORT`: 服务监听端口（默认 5000）
- `DB_HOST`: 数据库主机（默认 haoslm2.xicp.net）
- `DB_PORT`: 数据库端口（默认 10216）

### 启动命令
```bash
# 开发环境
coze dev

# 生产环境
coze build && coze start
```

## 常见问题

### 1. 数据库连接失败
- 检查数据库配置（lib/db.py）
- 确认数据库服务正常运行

### 2. 报表生成失败
- 检查配置是否正确
- 查看日志文件（/app/work/logs/bypass/）
- 确认订单数据存在

### 3. 前端页面加载异常
- 检查静态文件路径是否正确
- 清除浏览器缓存后重试