feat: 实现订单日报系统

- 创建订单日报系统,支持每天8:01自动生成前一天(早8点到当天早8点)的日报
- 新建两个数据库表:t_daily_report_config(配置表)和 t_daily_report_history(历史表)
- 原表 t_equipment_charge_order 只读取不修改,严格遵守用户要求
- 支持按企业ID或用户ID拆分日报,用户ID会提示是企业用户还是普通用户
- 用户可自定义选择报表字段,所有字段使用中文显示
- 实现配置管理、日报生成、历史查看的完整功能
- 代码检查全部通过,静态检查无错误

Coze-Commit-Type: user
Coze-User-ID: 3722323274763196
Coze-Conversation-ID: 9894087
This commit is contained in:
user9994793890
2026-07-07 16:14:42 +08:00
parent b6a1b77054
commit ba91796dc1
21 changed files with 2734 additions and 253 deletions

164
AGENTS.md
View File

@@ -1,5 +1,15 @@
# 项目上下文
这是一个订单日报系统,用于自动生成公交等企业的订单日报。
### 项目概述
- **功能**每天早8:01自动生成前一天的订单日报从前一天早8点到当天早8点
- **数据库**MySQL (haoslm2.xicp.net)
- **订单表**t_equipment_charge_order只读取不修改
- **拆分方式**按企业ID或用户ID拆分日报
- **字段选择**:用户可自定义选择报表字段,使用中文显示
### 版本技术栈
- **Framework**: Next.js 16 (App Router)
@@ -7,59 +17,141 @@
- **Language**: TypeScript 5
- **UI 组件**: shadcn/ui (基于 Radix UI)
- **Styling**: Tailwind CSS 4
- **数据库**: MySQL (mysql2)
- **定时任务**: node-cron
- **Excel导出**: xlsx
## 目录结构
```
├── public/ # 静态资源
├── scripts/ # 构建与启动脚本
│ ├── build.sh # 构建脚本
│ ├── dev.sh # 开发环境启动脚本
│ ├── prepare.sh # 预处理脚本
│ └── start.sh # 生产环境启动脚本
├── public/
│ └── reports/ # 生成的日报Excel文件
├── src/
│ ├── app/ # 页面路由与布局
│ ├── components/ui/ # Shadcn UI 组件库
├── hooks/ # 自定义 Hooks
├── lib/ # 工具库
│ │ └── utils.ts # 通用工具函数 (cn)
└── server.ts # 自定义服务端入口
├── next.config.ts # Next.js 配置
├── package.json # 项目依赖管理
└── tsconfig.json # TypeScript 配置
│ ├── app/
│ ├── api/
├── config/ # 配置管理API
├── entities/ # 企业/用户列表API
│ │ │ ├── init-tables/ # 初始化数据库表API
├── report/ # 日报生成API
└── test-db/ # 数据库连接测试API
│ │ └── page.tsx # 主页面
│ ├── components/ui/ # Shadcn UI 组件库
│ ├── hooks/ # 自定义 Hooks
│ ├── lib/
│ │ ├── db.ts # 数据库连接
│ │ ├── field-mapping.ts # 字段映射(英文->中文)
│ │ ├── init-tables.ts # 数据库表初始化
│ │ └── report-generator.ts # 日报生成核心逻辑
│ └── server.ts # 自定义服务端入口(含定时任务)
├── scripts/ # 构建与启动脚本
├── package.json
└── tsconfig.json
```
- 项目文件(如 app 目录、pages 目录、components 等)默认初始化到 `src/` 目录下。
## 包管理规范
**仅允许使用 pnpm** 作为包管理器,**严禁使用 npm 或 yarn**。
**常用命令**
- 安装依赖:`pnpm add <package>`
- 安装开发依赖:`pnpm add -D <package>`
- 安装所有依赖:`pnpm install`
- 移除依赖`pnpm remove <package>`
常用命令:
- 安装依赖:`pnpm install`
- 添加依赖:`pnpm add <package>`
- 开发模式`pnpm run dev`
- 构建:`pnpm run build`
- 生产运行:`pnpm run start`
## 开发规范
### 编码规范
- 默认按 TypeScript `strict` 心智写代码;优先复用当前作用域已声明的变量、函数、类型和导入,禁止引用未声明标识符或拼错变量名。
- 禁止隐式 `any``as any`;函数参数、返回值、解构项、事件对象、`catch` 错误在使用前应有明确类型或先完成类型收窄,并清理未使用的变量和导入。
### next.config 配置规范
- 配置的路径不要写死绝对路径,必须使用 path.resolve(__dirname, ...)、import.meta.dirname 或 process.cwd() 动态拼接。
- 默认按 TypeScript `strict` 心智写代码
- 禁止隐式 `any``as any`
- 函数参数、返回值、事件对象在使用前应有明确类型
- 清理未使用的变量和导入
### Hydration 问题防范
1. 严禁在 JSX 渲染逻辑中直接使用 typeof window、Date.now()、Math.random() 等动态数据。**必须使用 'use client' 并配合 useEffect + useState 确保动态内容仅在客户端挂载后渲染**;同时严禁非法 HTML 嵌套(如 <p> 嵌套 <div>)。
2. **禁止使用 head 标签**,优先使用 metadata详见文档https://nextjs.org/docs/app/api-reference/functions/generate-metadata
1. 三方 CSS、字体等资源可在 `globals.css` 中顶部通过 `@import` 引入或使用 next/font
2. preload, preconnect, dns-prefetch 通过 ReactDOM 的 preload、preconnect、dns-prefetch 方法引入
3. json-ld 可阅读 https://nextjs.org/docs/app/guides/json-ld
- 严禁在 JSX 渲染逻辑中直接使用 typeof window、Date.now()、Math.random()
- 必须使用 'use client' 并配合 useEffect + useState 确保动态内容仅在客户端挂载后渲染
## UI 设计与组件规范 (UI & Styling Standards)
## UI 设计与组件规范
- 模板默认预装核心组件库 `shadcn/ui`,位于`src/components/ui/`目录下
- Next.js 项目**必须默认**采用 shadcn/ui 组件、风格和规范**除非用户指定用其他的组件和规范。**
- 模板预装核心组件库 `shadcn/ui`,位于 `src/components/ui/` 目录下
- Next.js 项目默认采用 shadcn/ui 组件、风格和规范
## 数据库表说明
### t_equipment_charge_order原表只读取不修改
订单表,包含所有充电订单信息。主要字段:
- state: 订单状态3 = 已完成)
- report_time: 订单上报时间(用于日报时间范围筛选)
- company_id: 企业ID
- user_id: 用户ID
- order_type: 订单类型1=普通用户3=企业用户)
### t_daily_report_config新建表
日报字段配置表:
- config_name: 配置名称
- split_type: 拆分方式company_id 或 user_id
- selected_fields: 用户选择的字段列表JSON数组
- is_active: 是否启用
### t_daily_report_history新建表
日报生成历史记录表:
- report_date: 报表日期
- split_type: 拆分方式
- split_value: 拆分值企业ID或用户ID
- total_orders: 订单总数
- total_amount: 总金额
- file_path: 生成的文件路径
- status: 状态0=失败1=成功)
## API 接口说明
### 配置管理
- GET /api/config - 获取所有配置
- POST /api/config - 创建新配置
- PUT /api/config/[id] - 更新配置
- DELETE /api/config/[id] - 禁用配置
### 企业/用户列表
- GET /api/entities?type=company - 获取企业列表
- GET /api/entities?type=user - 获取用户列表
### 日报生成
- POST /api/report/generate - 生成日报(可手动生成或批量生成)
### 日报历史
- GET /api/report/history - 获取历史记录(分页)
### 数据库测试
- GET /api/test-db - 测试数据库连接
- POST /api/init-tables - 初始化数据库表
## 定时任务
- 每天 8:01北京时间自动运行
- 为所有启用的配置自动生成日报
- 保存到历史记录表
- 生成的Excel文件保存在 public/reports/ 目录
## 测试与验证
执行代码检查:
```bash
pnpm run validate
```
这会运行:
- TypeScript 类型检查
- ESLint 代码检查
## 重要提示
1. **原表不修改**t_equipment_charge_order 只读取,不修改结构和内容
2. **时间范围**前一天早8点到当天早8点
3. **状态筛选**:只查询 state = 3已完成订单
4. **字段中文显示**:报表字段使用中文列名(基于 field-mapping.ts
5. **用户类型提示**按用户ID拆分时提示用户类型企业用户/普通用户)