docs: 创建Windows开发和测试详细指南
新增 WINDOWS_GUIDE.md 文件，包含Windows系统下的完整操作指南： 1. 软件安装步骤 - Node.js 20.x LTS 安装（含官网下载链接） - pnpm 安装命令和验证方法 - VSCode 推荐安装和扩展配置 2. 项目准备和启动 - 命令提示符操作方法 - VSCode使用方式（含快捷键Ctrl+~打开终端） - 依赖安装命令和等待时间说明 - 开发服务器启动和浏览器访问 3. 数据库初始化（首次运行） - 浏览器直接访问方式 - curl命令方式 - PowerShell Invoke-WebRequest方式 4. 功能测试清单 - 配置创建（选择企业/用户、字段、求和） - 日报生成（选择配置、预设时间） - 单个下载和批量下载测试 - 定时任务测试说明 5. Windows常见问题解决 - 端口占用（netstat + taskkill命令） - pnpm找不到（重启终端或重新安装） - 数据库连接失败（防火墙设置） - Excel无法打开（软件版本建议） - 页面空白（浏览器缓存清除） 6. 开发和测试技巧 - 实时日志查看 - 代码错误检查 - 重启服务器方法 - 清除缓存命令 7. Windows特别说明 - 命令提示符和PowerShell使用 - 路径使用反斜杠 - 推荐浏览器Chrome/Edge - 防火墙放行Node.js 8. 性能优化建议 - 使用SSD硬盘 - Node.js内存限制调整 - 浏览器选择建议 包含完整的命令示例、错误信息、解决方法，适合Windows用户快速上手开发和测试！ Coze-Commit-Type: user Coze-User-ID: 3722323274763196 Coze-Conversation-ID: 9894087
This commit is contained in:
user9994793890
457
WINDOWS_GUIDE.md
Normal file
457
WINDOWS_GUIDE.md
Normal file
@@ -0,0 +1,457 @@
|
||||
# Windows系统开发和测试指南
|
||||
|
||||
## 一、安装必需软件
|
||||
|
||||
### 1. 安装 Node.js
|
||||
|
||||
#### 下载和安装
|
||||
1. 访问官网：https://nodejs.org/
|
||||
2. 下载 **Node.js 20.x LTS** 版本（推荐20.10.0或更高）
|
||||
3. 双击安装包，按照提示完成安装
|
||||
- 安装路径建议：默认路径即可
|
||||
- 确保勾选 "Add to PATH" 选项
|
||||
|
||||
#### 验证安装
|
||||
打开 **命令提示符** 或 **PowerShell**：
|
||||
```cmd
|
||||
node --version
|
||||
npm --version
|
||||
```
|
||||
|
||||
应该看到类似输出：
|
||||
```
|
||||
v20.10.0
|
||||
10.2.0
|
||||
```
|
||||
|
||||
### 2. 安装 pnpm
|
||||
|
||||
#### 使用 npm 安装
|
||||
打开命令提示符或PowerShell：
|
||||
```cmd
|
||||
npm install -g pnpm
|
||||
```
|
||||
|
||||
#### 验证安装
|
||||
```cmd
|
||||
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. 回车打开命令提示符
|
||||
|
||||
#### 进入项目目录
|
||||
```cmd
|
||||
cd C:\path\to\your\project
|
||||
```
|
||||
（将 `C:\path\to\your\project` 替换为实际项目路径）
|
||||
|
||||
### 方式2：使用 VSCode 打开
|
||||
1. 打开 VSCode
|
||||
2. 点击 "文件" → "打开文件夹"
|
||||
3. 选择项目目录
|
||||
4. 按 `Ctrl + ~` 打开终端（VSCode内置终端）
|
||||
|
||||
## 三、安装项目依赖
|
||||
|
||||
### 执行安装命令
|
||||
在命令提示符或VSCode终端中：
|
||||
```cmd
|
||||
pnpm install
|
||||
```
|
||||
|
||||
**等待时间**：约5-10分钟
|
||||
**输出信息**：会显示安装进度和依赖列表
|
||||
|
||||
### 如果遇到权限错误
|
||||
如果提示权限不足，以管理员身份运行：
|
||||
1. 右键点击 "命令提示符"
|
||||
2. 选择 "以管理员身份运行"
|
||||
3. 再次执行 `pnpm install`
|
||||
|
||||
## 四、启动开发服务器
|
||||
|
||||
### 启动命令
|
||||
```cmd
|
||||
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（如果已安装）
|
||||
在新的命令提示符窗口中：
|
||||
```cmd
|
||||
curl -X POST http://localhost:5000/api/init-tables
|
||||
```
|
||||
|
||||
### 方式3：使用 PowerShell
|
||||
```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. 再次运行：
|
||||
```cmd
|
||||
pnpm run dev
|
||||
```
|
||||
|
||||
### 4. 清除缓存
|
||||
如果遇到奇怪的错误：
|
||||
```cmd
|
||||
# 停止服务器（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
|
||||
```
|
||||
|
||||
**解决方法**：
|
||||
```cmd
|
||||
# 查看占用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已安装：
|
||||
```cmd
|
||||
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. 检查网络连接：
|
||||
```cmd
|
||||
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. 尝试重新初始化数据库表
|
||||
|
||||
## 九、停止开发服务器
|
||||
|
||||
### 正常停止
|
||||
在命令提示符窗口：
|
||||
```cmd
|
||||
按 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文件
|
||||
```cmd
|
||||
# 进入项目目录
|
||||
cd C:\path\to\project\public\reports
|
||||
|
||||
# 列出所有Excel文件
|
||||
dir *.xlsx
|
||||
```
|
||||
|
||||
## 十一、生产环境部署（可选）
|
||||
|
||||
### 1. 构建生产版本
|
||||
```cmd
|
||||
pnpm run build
|
||||
```
|
||||
**等待时间**：2-5分钟
|
||||
|
||||
### 2. 启动生产服务器
|
||||
```cmd
|
||||
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. **早上**：启动开发服务器
|
||||
```cmd
|
||||
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`：清除浏览器数据
|
||||
|
||||
## 十四、备份和恢复
|
||||
|
||||
### 备份配置
|
||||
数据库配置表在数据库中，可定期备份：
|
||||
```sql
|
||||
-- 导出配置表
|
||||
SELECT * FROM t_daily_report_config;
|
||||
```
|
||||
|
||||
### 备份生成的Excel文件
|
||||
```cmd
|
||||
# 复制到备份目录
|
||||
xcopy C:\path\to\project\public\reports D:\backup\reports /E /I
|
||||
```
|
||||
|
||||
## 十五、性能优化建议
|
||||
|
||||
### 1. 使用 SSD 硬盘
|
||||
将项目放在SSD硬盘可显著提高：
|
||||
- 依赖安装速度
|
||||
- 构建速度
|
||||
- Excel文件生成速度
|
||||
|
||||
### 2. 调整Node.js内存限制（大数据量）
|
||||
```cmd
|
||||
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
|
||||
Reference in New Issue
Block a user