refactor: 重构项目结构，按功能模块拆分文件
- 后端：将 app.py 拆分为 lib/api/ 目录下的多个蓝图模块 - config_api.py: 配置管理 API - entity_api.py: 实体管理 API - field_api.py: 字段列表 API - report_api.py: 日报生成和历史记录 API - init_api.py: 数据库初始化 API - download_api.py: 文件下载 API - 前端：将 index.html 拆分为多个文件 - static/css/style.css: CSS 样式 - static/js/common.js: 通用工具函数 - static/js/config.js: 配置管理 - static/js/entity.js: 实体管理 - static/js/report.js: 日报生成 - static/js/history.js: 历史记录 - 更新 app.py 使用蓝图注册 API - 创建 AGENTS.md 项目文档 Coze-Commit-Type: user Coze-User-ID: 3722323274763196 Coze-Conversation-ID: 9894087
This commit is contained in:
user9994793890
157
AGENTS.md
Normal file
157
AGENTS.md
Normal file
@@ -0,0 +1,157 @@
|
||||
# 订单日报系统 - 项目开发指南
|
||||
|
||||
## 项目概述
|
||||
|
||||
订单日报系统是一个基于 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. 前端页面加载异常
|
||||
- 检查静态文件路径是否正确
|
||||
- 清除浏览器缓存后重试
|
||||
Reference in New Issue
Block a user