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**：
```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