docs: add comprehensive user documentation

- Add README.md with installation, configuration, and usage guide - Add docs/USER_GUIDE.md with detailed step-by-step workflows - Include database setup scripts for MySQL and SQL Server - Add troubleshooting section with common issues
2026-03-01 15:57:07 +08:00
parent 484ca31d79
commit e794470d69
2 changed files with 422 additions and 18 deletions
--- a/README.md
+++ b/README.md
@@ -1,34 +1,176 @@
-# erpauto
+# ERPAuto - ERP 数据自动化处理工具

-An Electron application with React and TypeScript
+一个基于 Electron 的桌面应用程序，用于自动化处理 ERP 系统中的数据提取和清理任务。

-## Recommended IDE Setup
+## 功能特性

- [VSCode](https://code.visualstudio.com/) + [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) + [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)
+- **数据提取**：从 ERP 系统批量下载物料计划数据
+- **物料清理**：自动删除指定的物料代码，支持干运行模式
+- **数据库支持**：支持 MySQL 和 SQL Server 数据存储
+- **Excel 解析**：自动解析下载的 Excel 文件

-## Project Setup
+## 快速开始

-### Install
+### 环境要求
+
+- Node.js >= 18
+- npm >= 9
+- 可访问的 ERP 系统
+
+### 安装

 ```bash
-$ npm install
+# 克隆项目
+git clone <repository-url>
+cd ERPAuto
+
+# 安装依赖
+npm install
 ```

-### Development
+### 配置
+
+在项目根目录创建 `.env` 文件：

 ```bash
-$ npm run dev
+# ERP 配置
+ERP_URL=https://your-erp-server.com
+ERP_USERNAME=your_username
+ERP_PASSWORD=your_password
+
+# MySQL 配置（可选）
+MYSQL_HOST=localhost
+MYSQL_PORT=3306
+MYSQL_USER=root
+MYSQL_PASSWORD=password
+MYSQL_DATABASE=erpauto
+
+# SQL Server 配置（可选）
+SQL_SERVER_HOST=localhost
+SQL_SERVER_PORT=1433
+SQL_SERVER_USER=sa
+SQL_SERVER_PASSWORD=password
+SQL_SERVER_DATABASE=erpauto
 ```

-### Build
+### 运行开发环境

 ```bash
-# For windows
-$ npm run build:win
-
-# For macOS
-$ npm run build:mac
-
-# For Linux
-$ npm run build:linux
+npm run dev
 ```
+
+### 构建应用
+
+```bash
+# Windows
+npm run build:win
+
+# macOS
+npm run build:mac
+
+# Linux
+npm run build:linux
+```
+
+## 使用指南
+
+### 数据提取
+
+1. 启动应用后，点击主页的「数据提取」进入提取页面
+2. 在订单号输入框中输入订单号，每行一个
+3. 设置批量大小（默认 100）
+4. 点击「开始提取」按钮
+5. 等待提取完成，查看结果
+
+### 物料清理
+
+1. 点击主页的「物料清理」进入清理页面
+2. 输入订单号（每行一个）
+3. 输入要删除的物料代码（每行一个）
+4. 勾选「干运行模式」可预览删除结果（不实际删除）
+5. 点击「开始清理」按钮
+6. 查看清理结果和详细统计
+
+## 测试
+
+```bash
+# 运行单元测试
+npm run test
+
+# 运行 E2E 测试
+npm run test:e2e
+
+# 查看测试报告
+npm run test:e2e:report
+```
+
+## 项目结构
+
+```
+ERPAuto/
+├── src/
+│   ├── main/           # 主进程代码
+│   │   ├── services/   # 业务服务
+│   │   ├── ipc/        # IPC 处理器
+│   │   └── types/      # TypeScript 类型
+│   ├── preload/        # 预加载脚本
+│   └── renderer/       # 渲染进程（React UI）
+├── tests/
+│   ├── unit/           # 单元测试
+│   ├── integration/    # 集成测试
+│   └── e2e/            # E2E 测试
+└── docs/               # 文档
+```
+
+## 技术栈
+
+- **框架**：Electron 39
+- **前端**：React 19 + TypeScript
+- **构建工具**：electron-vite
+- **浏览器自动化**：Playwright
+- **数据库**：mysql2, mssql
+- **Excel 处理**：ExcelJS
+- **测试**：Vitest, Playwright Test
+
+## 常见问题
+
+### 无法连接 ERP 系统
+
+1. 检查 `.env` 文件中的 ERP_URL 是否正确
+2. 确认网络连接正常
+3. 检查 ERP 系统是否可访问
+
+### 提取失败
+
+1. 确认订单号格式正确
+2. 检查 ERP 系统账号权限
+3. 查看应用日志获取详细错误信息
+
+### 数据库连接失败
+
+1. 确认数据库服务已启动
+2. 检查 `.env` 中的数据库配置
+3. 确认防火墙允许数据库端口访问
+
+## 开发
+
+```bash
+# 安装依赖
+npm install
+
+# 启动开发服务器
+npm run dev
+
+# 类型检查
+npm run typecheck
+
+# 代码格式化
+npm run format
+
+# Lint 检查
+npm run lint
+```
+
+## 许可证
+
+MIT License
--- a/docs/USER_GUIDE.md
+++ b/docs/USER_GUIDE.md
@@ -0,0 +1,262 @@
+# ERPAuto 用户指南
+
+## 目录
+
+1. [简介](#简介)
+2. [安装指南](#安装指南)
+3. [配置说明](#配置说明)
+4. [使用指南](#使用指南)
+5. [数据库设置](#数据库设置)
+6. [常见问题](#常见问题)
+
+---
+
+## 简介
+
+ERPAuto 是一个专为 ERP 系统设计的自动化工具，主要功能包括：
+
+- **数据提取**：自动从 ERP 系统批量下载物料计划数据为 Excel 文件
+- **物料清理**：自动删除指定订单的物料代码
+- **数据库存储**：支持将提取的数据存储到 MySQL 或 SQL Server 数据库
+
+---
+
+## 安装指南
+
+### 系统要求
+
+- **操作系统**：Windows 10/11, macOS 10.15+, Linux
+- **内存**：至少 4GB RAM
+- **Node.js**：版本 18 或更高
+
+### 安装步骤
+
+1. **下载应用**
+   - 从发布页面下载对应系统的安装包
+   - Windows: `ERPAuto-Setup-x.x.x.exe`
+   - macOS: `ERPAuto-x.x.x.dmg`
+   - Linux: `ERPAuto-x.x.x.AppImage`
+
+2. **安装**
+   - Windows: 运行安装程序，按照提示完成安装
+   - macOS: 将应用拖拽到 Applications 文件夹
+   - Linux: 赋予执行权限后运行
+
+3. **首次运行**
+   - 启动应用
+   - 首次运行需要先配置 ERP 连接信息
+
+---
+
+## 配置说明
+
+### ERP 连接配置
+
+应用需要配置 ERP 系统的连接信息。在主界面点击「设置」->「ERP 配置」：
+
+| 配置项  | 说明           | 示例                          |
+| ------- | -------------- | ----------------------------- |
+| ERP URL | ERP 系统地址   | `https://192.168.1.100:8082/` |
+| 用户名  | ERP 登录用户名 | `admin`                       |
+| 密码    | ERP 登录密码   | `******`                      |
+
+### 数据库配置（可选）
+
+如需将提取的数据存储到数据库，需要配置数据库连接：
+
+**MySQL 配置：**
+
+| 配置项   | 默认值      | 说明             |
+| -------- | ----------- | ---------------- |
+| 主机     | `localhost` | MySQL 服务器地址 |
+| 端口     | `3306`      | MySQL 端口       |
+| 用户名   | `root`      | 数据库用户名     |
+| 密码     | -           | 数据库密码       |
+| 数据库名 | `erpauto`   | 数据库名称       |
+
+**SQL Server 配置：**
+
+| 配置项   | 默认值      | 说明               |
+| -------- | ----------- | ------------------ |
+| 服务器   | `localhost` | SQL Server 地址    |
+| 端口     | `1433`      | SQL Server 端口    |
+| 用户名   | `sa`        | 登录用户名         |
+| 密码     | -           | 登录密码           |
+| 数据库   | `erpauto`   | 数据库名称         |
+| 加密     | `false`     | 是否启用 SSL 加密  |
+| 信任证书 | `true`      | 是否信任服务器证书 |
+
+---
+
+## 使用指南
+
+### 数据提取功能
+
+**使用场景：** 从 ERP 系统批量下载多个订单的物料计划数据。
+
+**操作步骤：**
+
+1. 进入「数据提取」页面
+2. 在左侧输入框中输入订单号，每行一个：
+   ```
+   SC70202602120085
+   SC70202602120120
+   SC70202602120137
+   ```
+3. 设置批量大小（建议 100-500）
+4. 点击「开始提取」
+5. 等待提取完成，查看结果统计
+
+**提取结果说明：**
+
+- **下载文件数**：成功下载的 Excel 文件数量
+- **记录数**：提取的总记录数
+- **错误数**：失败的订单数量
+
+### 物料清理功能
+
+**使用场景：** 删除指定订单中的特定物料代码。
+
+**操作步骤：**
+
+1. 进入「物料清理」页面
+2. 输入订单号（每行一个）
+3. 输入要删除的物料代码（每行一个）
+4. **重要**：首次使用建议勾选「干运行模式」
+5. 点击「开始清理」
+6. 查看清理结果
+
+**干运行模式：**
+
+- 勾选后，系统仅预览将要删除的数据，不实际执行删除
+- 建议先用干运行模式确认数据正确
+- 确认无误后，取消勾选执行实际删除
+
+**清理结果说明：**
+
+- **处理订单数**：成功处理的订单数量
+- **删除物料数**：实际删除的物料数量
+- **跳过物料数**：未找到或跳过的物料数量
+- **订单详情**：每个订单的详细处理结果
+
+---
+
+## 数据库设置
+
+### MySQL 数据库初始化
+
+```sql
+CREATE DATABASE IF NOT EXISTS erpauto CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+USE erpauto;
+
+-- 创建物料数据表
+CREATE TABLE IF NOT EXISTS material_data (
+    id INT AUTO_INCREMENT PRIMARY KEY,
+    order_number VARCHAR(50) NOT NULL,
+    material_code VARCHAR(100) NOT NULL,
+    material_name VARCHAR(255),
+    quantity DECIMAL(10, 2),
+    unit VARCHAR(20),
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    INDEX idx_order (order_number),
+    INDEX idx_material (material_code)
+);
+```
+
+### SQL Server 数据库初始化
+
+```sql
+CREATE DATABASE erpauto;
+GO
+
+USE erpauto;
+GO
+
+-- 创建物料数据表
+CREATE TABLE material_data (
+    id INT IDENTITY(1,1) PRIMARY KEY,
+    order_number NVARCHAR(50) NOT NULL,
+    material_code NVARCHAR(100) NOT NULL,
+    material_name NVARCHAR(255),
+    quantity DECIMAL(10, 2),
+    unit NVARCHAR(20),
+    created_at DATETIME DEFAULT GETDATE()
+);
+GO
+
+CREATE INDEX idx_order ON material_data(order_number);
+CREATE INDEX idx_material ON material_data(material_code);
+GO
+```
+
+---
+
+## 常见问题
+
+### 1. 无法登录 ERP 系统
+
+**问题描述：** 点击登录后提示认证失败
+
+**解决方法：**
+
+1. 确认用户名和密码正确
+2. 检查 ERP 系统是否可访问
+3. 确认账号有足够权限
+
+### 2. 提取时卡在加载中
+
+**问题描述：** 点击提取后一直显示加载中
+
+**解决方法：**
+
+1. 检查网络连接
+2. 减少批量大小
+3. 确认 ERP 系统运行正常
+4. 刷新页面后重试
+
+### 3. 物料清理无数据
+
+**问题描述：** 清理时显示没有可删除的数据
+
+**解决方法：**
+
+1. 确认订单号正确
+2. 确认物料代码在该订单中存在
+3. 先用干运行模式查看是否有匹配数据
+
+### 4. 数据库连接失败
+
+**问题描述：** 无法连接到数据库
+
+**解决方法：**
+
+1. 确认数据库服务已启动
+2. 检查数据库配置信息
+3. 确认防火墙允许数据库端口
+4. 测试数据库连接：
+
+   ```bash
+   # MySQL
+   mysql -h localhost -u root -p
+
+   # SQL Server
+   sqlcmd -S localhost -U sa
+   ```
+
+### 5. 应用闪退
+
+**问题描述：** 应用启动后立即关闭
+
+**解决方法：**
+
+1. 查看日志文件获取错误信息
+2. 重新安装应用
+3. 确认系统满足最低要求
+4. 尝试以管理员身份运行
+
+---
+
+## 技术支持
+
+如有其他问题，请联系技术支持团队或提交 Issue。