订单日报系统 - 本地运行指南

这是一个基于 Next.js + TypeScript 的订单日报系统，用于自动生成公交等企业的订单日报。

系统要求

必需软件

1. Node.js (版本要求)

   • 推荐版本：Node.js 20+ 或 Node.js 24+
   • 最低版本：Node.js 18.17+
   • 下载地址：https://nodejs.org/

2. pnpm (包管理器)

   • 安装命令：

     npm install -g pnpm
     

   • 说明：本项目强制使用pnpm，禁止使用npm或yarn

可选软件（用于生产环境）

• PM2：用于进程管理和自动重启

  npm install -g pm2
  

本地运行步骤

1. 安装 Node.js

Windows系统

• 访问 https://nodejs.org/
• 下载 LTS 版本（推荐 Node.js 20+）
• 双击安装包，按提示完成安装
• 安装完成后，打开命令提示符验证：

  node --version
  npm --version
  

macOS系统

• 使用 Homebrew 安装：

  brew install node@20
  

• 或访问官网下载安装包

Linux系统 (Ubuntu/Debian)

# 使用 NodeSource 仓库
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# 验证安装
node --version
npm --version

2. 安装 pnpm

# 全局安装 pnpm
npm install -g pnpm

# 验证安装
pnpm --version

3. 克隆或下载项目

# 如果使用 Git
git clone <项目地址>
cd <项目目录>

# 或者直接下载项目压缩包并解压

4. 安装项目依赖

# 进入项目目录
cd <项目目录>

# 安装所有依赖（必须使用 pnpm）
pnpm install

安装时间：首次安装约需5-10分钟，取决于网络速度。

5. 配置数据库连接

项目已配置好数据库连接，默认连接：

• 地址：haoslm2.xicp.net:10216
• 数据库：yltcharge
• 用户名：root
• 密码：DsideaL147258369

如果需要修改，编辑 src/lib/db.ts 文件。

6. 初始化数据库表

首次运行时，需要初始化数据库表：

方式1：通过API初始化（推荐）

启动服务后，访问或调用：

# 启动服务
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. 启动开发服务器

# 启动开发环境（带热更新）
pnpm run dev

启动成功标志：

✓ Compiled in xxxms
✓ Ready in xxxms
Local:   http://localhost:5000

8. 访问应用

打开浏览器，访问：

• 本地地址：http://localhost:5000
• 功能页面：
  • 配置管理：创建和管理日报配置
  • 日报生成：选择配置和时间范围生成日报
  • 历史记录：查看和下载已生成的日报

生产环境部署

1. 构建生产版本

# 构建优化的生产版本
pnpm run build

2. 启动生产服务器

方式1：直接启动

pnpm run start

方式2：使用 PM2（推荐）

# 安装 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：

// 修改定时任务时间（cron表达式）
cron.schedule('1 8 * * *', async () => {
  // 每天8:01执行
  console.log('开始生成日报...');
}, {
  timezone: "Asia/Shanghai"
});

常见问题

1. pnpm 安装失败

问题：pnpm: command not found

解决：

# 使用 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

解决：

# 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. 手动测试定时任务：

   # 访问测试接口（如果有）
   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                 ← 本文件

运行命令总结

# 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

数据库初始化

首次运行需要初始化数据库表：

自动创建的表（不修改原表）

1. t_daily_report_config - 配置表

   • 存储用户的日报配置
   • 包含字段选择、求和字段等

2. t_daily_report_history - 历史表

   • 记录每次日报生成的历史
   • 包含文件路径、统计信息等

重要：原表 t_equipment_charge_order 只读取，结构和内容都不会修改。

技术栈说明

• 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文件生成库

许可和说明

• 本项目仅供内部使用
• 数据库连接信息已预配置
• 定时任务使用北京时间（Asia/Shanghai）
• Excel文件存储在 public/reports/ 目录

获取帮助

如有问题，请查看：

1. 本README文件的常见问题部分
2. AGENTS.md 项目说明文档
3. 检查日志文件（如有）
4. 查看API返回的错误信息

---

最后更新时间：2025-07-08