ylt_diy/AGENTS.md

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

项目概述

订单日报系统是一个基于 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）

启动命令

# 开发环境
coze dev

# 生产环境
coze build && coze start

常见问题

1. 数据库连接失败

• 检查数据库配置（lib/db.py）
• 确认数据库服务正常运行

2. 报表生成失败

• 检查配置是否正确
• 查看日志文件（/app/work/logs/bypass/）
• 确认订单数据存在

3. 前端页面加载异常

• 检查静态文件路径是否正确
• 清除浏览器缓存后重试