681f3ba517
- Create user/ - User guides and configuration documentation - Create features/ - Feature specifications and business flows - Create debugging/ - Debug guides and quick references - Create testing/ - Test infrastructure, reports, and plans - Create internal/ - Internal plans, analyses, and templates - Move cleaner/*.md to cleaner/ directory - Move LOGGING_*.md to developer/guides/ Add docs/README.md as documentation index with category navigation and quick lookup guide. The reorganized structure makes it easier for users and developers to quickly locate relevant documentation.
242 lines
5.0 KiB
Markdown
242 lines
5.0 KiB
Markdown
# ERP 登录调试工具 - 快速参考
|
||
|
||
## 创建的文件
|
||
|
||
### 1. 调试脚本
|
||
|
||
**路径**: `src/main/tools/erp-login-debug.ts`
|
||
|
||
用途：人工调试 ERP 登录流程，定位主界面特征元素
|
||
|
||
### 2. 使用文档
|
||
|
||
**路径**: `docs/erp-login-debug-guide.md`
|
||
|
||
详细的调试工具使用说明
|
||
|
||
### 3. package.json 更新
|
||
|
||
添加了新的 npm 脚本和依赖：
|
||
|
||
- `debug:erp-login` - 运行调试脚本
|
||
- `debug:config-path` - 运行配置路径调试（已有）
|
||
- `tsx` - TypeScript 执行器依赖
|
||
|
||
## 快速开始
|
||
|
||
### 步骤 1：配置登录信息
|
||
|
||
编辑 `src/main/tools/erp-login-debug.ts` 第 19-23 行：
|
||
|
||
```typescript
|
||
const ERP_CONFIG = {
|
||
url: 'https://your-erp-server.com', // ← 修改
|
||
username: 'your_username', // ← 修改
|
||
password: 'your_password' // ← 修改
|
||
}
|
||
```
|
||
|
||
### 步骤 2：运行调试
|
||
|
||
```bash
|
||
npm run debug:erp-login
|
||
```
|
||
|
||
### 步骤 3：定位元素
|
||
|
||
登录成功后：
|
||
|
||
1. 按 **F12** 打开开发者工具
|
||
2. 按 **Ctrl+Shift+C** 启用元素选择器
|
||
3. 点击主界面特征元素
|
||
4. 右键 → Copy → Copy selector
|
||
|
||
### 步骤 4：更新定位器
|
||
|
||
将找到的元素添加到 `src/main/services/erp/locators.ts`：
|
||
|
||
```typescript
|
||
export const ERP_LOCATORS = {
|
||
// ... 现有配置 ...
|
||
|
||
// 新增：主界面特征元素
|
||
mainPage: {
|
||
// 在此添加找到的元素
|
||
topNav: '#top-nav',
|
||
userMenu: '.user-menu'
|
||
}
|
||
}
|
||
```
|
||
|
||
## 脚本功能
|
||
|
||
### 自动执行
|
||
|
||
- ✅ 启动浏览器（可见窗口，非无头模式）
|
||
- ✅ 导航到登录页面
|
||
- ✅ 输入用户名和密码
|
||
- ✅ 点击登录按钮
|
||
- ✅ 处理强制登录确认对话框
|
||
|
||
### 调试支持
|
||
|
||
- ✅ 登录成功后自动暂停
|
||
- ✅ 保持浏览器打开
|
||
- ✅ 支持 F12 开发者工具
|
||
- ✅ 支持 Playwright Inspector
|
||
|
||
### 安全特性
|
||
|
||
- ✅ 密码显示为星号
|
||
- ✅ 需要按 Enter 确认后才开始
|
||
- ✅ 退出前 5 秒缓冲时间
|
||
|
||
## 常用命令
|
||
|
||
```bash
|
||
# 运行调试脚本
|
||
npm run debug:erp-login
|
||
|
||
# 或使用 npx 直接运行
|
||
npx tsx src/main/tools/erp-login-debug.ts
|
||
|
||
# 查看帮助
|
||
npx tsx --help
|
||
```
|
||
|
||
## 调试技巧
|
||
|
||
### 测试 Locator 有效性
|
||
|
||
在浏览器控制台（登录后暂停时）：
|
||
|
||
```javascript
|
||
// 测试 CSS 选择器
|
||
await page.locator('#top-nav').count()
|
||
|
||
// 测试文本选择器
|
||
await page.getByText('欢迎').isVisible()
|
||
|
||
// 测试 role 选择器
|
||
await page.getByRole('navigation').count()
|
||
```
|
||
|
||
返回值 > 0 或 true 表示选择器有效。
|
||
|
||
### 查看元素详细信息
|
||
|
||
```javascript
|
||
// 获取元素 HTML
|
||
const element = await page.$('#top-nav')
|
||
console.log(await element.innerHTML())
|
||
|
||
// 获取元素属性
|
||
console.log(await element.getAttributes())
|
||
```
|
||
|
||
### 截图保存
|
||
|
||
```javascript
|
||
// 全屏截图
|
||
await page.screenshot({ path: 'login-success.png' })
|
||
|
||
// 元素截图
|
||
const element = await page.$('#top-nav')
|
||
await element.screenshot({ path: 'top-nav.png' })
|
||
```
|
||
|
||
## 推荐的特征元素
|
||
|
||
选择登录成功判定元素的标准：
|
||
|
||
| 标准 | 说明 | 示例 |
|
||
| ---------- | -------------- | ------------------- |
|
||
| **唯一性** | 只在登录后出现 | 用户菜单、工作台 |
|
||
| **稳定性** | 不易随版本变更 | ID 选择器优于 class |
|
||
| **易定位** | 有明确的标识 | 有 id、独特文本 |
|
||
|
||
### 推荐元素类型
|
||
|
||
1. **顶部导航栏** - `#top-nav`, `.navbar`
|
||
2. **用户信息区域** - `.user-info`, `.user-menu`
|
||
3. **欢迎消息** - 包含用户名的文本
|
||
4. **功能模块入口** - 主界面的模块网格
|
||
5. **侧边菜单栏** - `.sidebar`, `.menu`
|
||
|
||
## 故障排查
|
||
|
||
### 问题：脚本启动后立即退出
|
||
|
||
**原因**: tsx 未安装
|
||
|
||
**解决**:
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
### 问题：找不到用户名/密码输入框
|
||
|
||
**原因**:
|
||
|
||
1. ERP URL 不正确
|
||
2. 页面结构已变更
|
||
3. 登录页面加载超时
|
||
|
||
**解决**:
|
||
|
||
1. 检查 ERP_CONFIG.url 是否正确
|
||
2. 手动打开 URL 确认页面结构
|
||
3. 增加 timeout 值（第 25 行）
|
||
|
||
### 问题：登录后没有暂停
|
||
|
||
**原因**: 登录流程抛出异常
|
||
|
||
**解决**: 查看控制台错误信息，检查：
|
||
|
||
- 网络连接
|
||
- ERP 系统可用性
|
||
- 用户名密码正确性
|
||
|
||
### 问题：无法定位元素
|
||
|
||
**原因**:
|
||
|
||
1. 元素在 iframe 中
|
||
2. 元素动态加载
|
||
3. 选择器不正确
|
||
|
||
**解决**:
|
||
|
||
1. 检查元素是否在嵌套 iframe 中
|
||
2. 增加等待时间 `await page.waitForTimeout(2000)`
|
||
3. 使用更具体的选择器
|
||
|
||
## 下一步
|
||
|
||
找到稳定的主界面元素后：
|
||
|
||
1. **更新 locators.ts**
|
||
- 添加 `mainPage` 配置节
|
||
- 定义登录成功判定元素
|
||
|
||
2. **修改 erp-auth.ts**
|
||
- 在 `login()` 方法末尾
|
||
- 等待主界面元素出现
|
||
- 作为登录成功的最终判定
|
||
|
||
3. **验证修改**
|
||
- 重新运行调试脚本
|
||
- 确认新的判定逻辑有效
|
||
- 更新相关文档
|
||
|
||
## 相关文件
|
||
|
||
| 文件 | 用途 |
|
||
| ----------------------------------- | ---------- |
|
||
| `src/main/tools/erp-login-debug.ts` | 调试脚本 |
|
||
| `src/main/services/erp/locators.ts` | 元素定位器 |
|
||
| `src/main/services/erp/erp-auth.ts` | 登录服务 |
|
||
| `docs/erp-login-debug-guide.md` | 详细文档 |
|