ylt_diy/WINDOWS_GUIDE.md

Windows系统开发和测试指南

一、安装必需软件

1. 安装 Node.js

下载和安装

1. 访问官网：https://nodejs.org/
2. 下载 Node.js 20.x LTS 版本（推荐20.10.0或更高）
3. 双击安装包，按照提示完成安装
   • 安装路径建议：默认路径即可
   • 确保勾选 "Add to PATH" 选项

验证安装

打开 命令提示符 或 PowerShell：

node --version
npm --version

应该看到类似输出：

v20.10.0
10.2.0

2. 安装 pnpm

使用 npm 安装

打开命令提示符或PowerShell：

npm install -g pnpm

验证安装

pnpm --version

应该看到版本号，如：8.15.0

3. 安装 VSCode（推荐编辑器）

虽然不是必需，但推荐使用 Visual Studio Code：

1. 访问：https://code.visualstudio.com/
2. 下载并安装
3. 安装后打开VSCode
4. 安装推荐扩展：
   • "ES7+ React/Redux/React-Native snippets"
   • "TypeScript Importer"
   • "Tailwind CSS IntelliSense"

二、下载和准备项目

方式1：从现有目录运行

如果项目文件已在本地：

打开命令提示符

1. 按 Win + R
2. 输入 cmd
3. 回车打开命令提示符

进入项目目录

cd C:\path\to\your\project

（将 C:\path\to\your\project 替换为实际项目路径）

方式2：使用 VSCode 打开

1. 打开 VSCode
2. 点击 "文件" → "打开文件夹"
3. 选择项目目录
4. 按 Ctrl + ~ 打开终端（VSCode内置终端）

三、安装项目依赖

执行安装命令

在命令提示符或VSCode终端中：

pnpm install

等待时间：约5-10分钟 输出信息：会显示安装进度和依赖列表

如果遇到权限错误

如果提示权限不足，以管理员身份运行：

1. 右键点击 "命令提示符"
2. 选择 "以管理员身份运行"
3. 再次执行 pnpm install

四、启动开发服务器

启动命令

pnpm run dev

等待启动成功

看到以下信息表示启动成功：

✓ Compiled in xxxms
✓ Ready in xxxms

  Local:   http://localhost:5000
  Network: http://192.168.x.x:5000

打开浏览器访问

在浏览器（Chrome/Edge推荐）中访问：

http://localhost:5000

成功标志：看到配置管理、日报生成、历史记录三个标签页。

五、初始化数据库表（首次运行）

方式1：浏览器访问

在浏览器中直接访问：

http://localhost:5000/api/init-tables

方式2：使用 curl（如果已安装）

在新的命令提示符窗口中：

curl -X POST http://localhost:5000/api/init-tables

方式3：使用 PowerShell

Invoke-WebRequest -Uri "http://localhost:5000/api/init-tables" -Method POST

成功标志：看到 "数据库表初始化成功" 的JSON响应。

六、开始使用和测试

1. 创建测试配置

在浏览器页面中：

1. 点击 "配置管理" 标签
2. 填写配置名称（如："测试79路"）
3. 选择拆分方式："按企业ID"
4. 从下拉列表选择企业："国营-西南-79路"
5. 选择字段（勾选：订单号、充电开始时间、充电结束时间、充电电量）
6. 选择求和字段（勾选：充电电量）
7. 点击 "创建配置"

2. 测试日报生成

1. 点击 "日报生成" 标签
2. 选择刚才创建的配置："测试79路"
3. 选择时间：点击 "预设时间"，选择 "昨天"
4. 点击 "生成日报"

等待时间：约2-5秒 成功标志：显示 "日报生成成功"，包含订单数量和求和结果。

3. 测试下载功能

1. 点击 "历史记录" 标签
2. 查看刚才生成的日报记录
3. 点击 "下载" 按钮
4. Excel文件会下载到浏览器默认下载目录

4. 测试批量下载

1. 在历史记录页面，勾选多个日报记录
2. 点击 "批量下载" 按钮
3. 所有选中的Excel文件会打包下载

七、开发测试常用操作

1. 查看实时日志

开发模式下，日志会显示在命令提示符窗口：

• API请求日志
• 错误信息
• 定时任务执行情况

2. 检查代码错误

如果页面出现错误，查看命令提示符窗口的错误日志。

3. 重启服务器

如果需要重启：

1. 在命令提示符窗口按 Ctrl + C 停止服务
2. 再次运行：

   pnpm run dev
   

4. 清除缓存

如果遇到奇怪的错误：

# 停止服务器（Ctrl + C）

# 删除缓存和依赖
rmdir /s .next
rmdir /s node_modules

# 重新安装
pnpm install

# 重新启动
pnpm run dev

5. 测试定时任务

定时任务（每天8:01）需要在服务持续运行时才会执行。

测试定时任务是否正常：

1. 保持服务器运行（不要关闭命令提示符）
2. 查看命令提示符输出，确认是否有定时任务启动日志
3. 或手动测试（访问相应的测试接口）

八、常见Windows问题解决

问题1：端口5000被占用

Error: listen EADDRINUSE: address already in use :::5000

解决方法：

# 查看占用5000端口的进程
netstat -ano | findstr :5000

# 会显示类似：
# TCP    0.0.0.0:5000    0.0.0.0:0    LISTENING    12345

# 最后的数字是进程ID（如12345）

# 结束该进程
taskkill /PID 12345 /F

问题2：pnpm命令找不到

'pnpm' 不是内部或外部命令

解决方法：

1. 确认pnpm已安装：

   npm list -g pnpm
   

2. 如果已安装但仍找不到，重启命令提示符

3. 或添加到PATH环境变量：

   • 搜索 "环境变量"
   • 编辑 "系统环境变量"
   • 在PATH中添加：C:\Users\你的用户名\AppData\Local\pnpm

问题3：数据库连接失败

Error: connect ETIMEDOUT
Error: connect ECONNREFUSED

解决方法：

1. 检查防火墙设置：

   • 控制面板 → Windows Defender 防火墙
   • 允许应用通过防火墙
   • 确保 Node.js 允许通过

2. 检查网络连接：

   ping haoslm2.xicp.net
   telnet haoslm2.xicp.net 10216
   

3. 如果网络不通，联系数据库管理员

问题4：Excel文件无法打开

下载的Excel文件打开报错。

解决方法：

• 使用 Microsoft Excel 2016+ 打开
• 或使用免费软件：LibreOffice Calc
• 检查文件是否完整下载（文件大小>0）

问题5：浏览器页面空白

访问 http://localhost:5000 显示空白。

解决方法：

1. 检查服务器是否正常启动（命令提示符有无错误）
2. 尝试刷新页面（F5）
3. 清除浏览器缓存（Ctrl + Shift + Delete）
4. 尝试其他浏览器（Chrome推荐）

问题6：创建配置失败

点击"创建配置"显示错误。

解决方法：

1. 查看命令提示符的错误日志
2. 检查数据库表是否已初始化
3. 尝试重新初始化数据库表

九、停止开发服务器

正常停止

在命令提示符窗口：

按 Ctrl + C

会提示：终止批处理操作吗(Y/N)?，输入 Y 并回车。

强制停止

如果Ctrl+C无效：

1. 关闭命令提示符窗口
2. 或使用任务管理器结束 node.exe 进程

十、项目文件位置说明

Windows常用路径

C:\Users\你的用户名\Documents\项目目录\
  ├── src\               ← 主程序源码
  ├── public\reports\    ← Excel文件存储位置
  ├── package.json       ← 项目配置
  └── README.md          ← 说明文档

Excel文件下载位置

默认下载到浏览器设置的位置：

• Chrome: C:\Users\你的用户名\Downloads\
• Edge: C:\Users\你的用户名\Downloads\

查看生成的Excel文件

# 进入项目目录
cd C:\path\to\project\public\reports

# 列出所有Excel文件
dir *.xlsx

十一、生产环境部署（可选）

1. 构建生产版本

pnpm run build

等待时间：2-5分钟

2. 启动生产服务器

pnpm run start

3. 使用 PM2 管理进程（Windows不支持PM2）

Windows系统推荐使用：

• NSSM（Non-Sucking Service Manager）
• 或直接使用 pnpm run start + Windows任务计划程序

4. 设置开机自启（Windows任务计划）

1. 搜索 "任务计划程序"
2. 创建基本任务
3. 设置触发器："计算机启动时"
4. 操作："启动程序"
5. 程序路径：C:\Program Files\nodejs\node.exe
6. 参数：项目的启动脚本路径

十二、开发建议

推荐工作流程

1. 早上：启动开发服务器

   pnpm run dev
   

2. 白天：在浏览器中测试功能

   • 创建配置
   • 生成日报
   • 检查结果

3. 晚上：停止服务器（Ctrl+C）

4. 持续开发：修改代码后自动热更新，无需重启

测试功能清单

✅ 配置创建和编辑 ✅ 配置启用/禁用 ✅ 配置排序（上移下移） ✅ 配置删除 ✅ 日报生成（选择配置+时间） ✅ 历史记录查看 ✅ 单个下载 ✅ 批量下载 ✅ 定时任务（需长时间运行）

十三、快捷键和技巧

VSCode快捷键

• Ctrl + ~：打开/关闭终端
• Ctrl + S：保存文件（自动热更新）
• Ctrl + Shift + P：命令面板
• Ctrl + B：显示/隐藏侧边栏

命令提示符快捷键

• Ctrl + C：停止当前命令
• Tab：自动补全路径
• ↑ ↓：历史命令

浏览器快捷键

• F5：刷新页面
• Ctrl + Shift + R：强制刷新（清除缓存）
• Ctrl + Shift + Delete：清除浏览器数据

十四、备份和恢复

备份配置

数据库配置表在数据库中，可定期备份：

-- 导出配置表
SELECT * FROM t_daily_report_config;

备份生成的Excel文件

# 复制到备份目录
xcopy C:\path\to\project\public\reports D:\backup\reports /E /I

十五、性能优化建议

1. 使用 SSD 硬盘

将项目放在SSD硬盘可显著提高：

• 依赖安装速度
• 构建速度
• Excel文件生成速度

2. 调整Node.js内存限制（大数据量）

set NODE_OPTIONS=--max-old-space-size=4096
pnpm run dev

3. 使用更快的浏览器

Chrome 或 Edge 比 IE 快得多。

获取帮助

如果遇到问题：

1. 查看命令提示符的错误日志
2. 查看浏览器控制台（F12）的错误
3. 参考 README.md 文件
4. 查看项目 AGENTS.md 文件

---

Windows系统特别说明：

• 使用命令提示符或PowerShell运行命令
• 路径使用反斜杠 \（如 C:\Users\...）
• Excel文件使用 .xlsx 格式
• 推荐使用Chrome或Edge浏览器
• 防火墙可能需要放行Node.js

最后更新：2025-07-08