BIPMaterialManager/docs/debugging/erp-login-debug-guide.md

ERP 登录调试工具使用说明

目的

用于人工调试 ERP 登录流程，定位主界面特征元素，以便优化登录成功的判定逻辑。

前置准备

1. 配置 ERP 登录信息

编辑 src/main/tools/erp-login-debug.ts 文件，修改以下配置：

const ERP_CONFIG = {
  url: 'https://your-erp-server.com', // ← 修改为你的 ERP 地址
  username: 'your_username', // ← 修改为你的用户名
  password: 'your_password' // ← 修改为你的密码
}

2. 确保 tsx 已安装

如果运行时报错提示找不到 tsx，请安装：

npm install -g tsx
# 或作为项目依赖
npm install --save-dev tsx

使用方法

方式一：使用 npm 脚本（推荐）

npm run debug:erp-login

方式二：直接运行

npx tsx src/main/tools/erp-login-debug.ts

调试流程

步骤 1：启动脚本

运行命令后，脚本会显示配置信息并等待你确认：

============================================================
ERP 登录调试工具
============================================================
目标 URL: https://your-erp-server.com
用户名：your_username
密码： ***
============================================================

操作步骤：
1. 浏览器将自动打开并尝试登录
2. 如果登录失败，请检查配置或手动重试
3. 登录成功后，会自动暂停并打开开发者工具
4. 使用元素选择器定位主界面特征元素
5. 记录元素选择器，按 Ctrl+C 退出脚本

按 Enter 键开始...

步骤 2：自动登录

脚本会自动执行：

• 打开浏览器
• 导航到登录页面
• 输入用户名和密码
• 点击登录按钮
• 处理强制登录确认对话框（如果有）

步骤 3：人工元素定位

登录成功后，脚本会暂停并显示：

============================================================
✓ 登录成功！
============================================================

现在进入调试模式，请进行以下操作：

1. 按 F12 打开浏览器开发者工具
2. 使用元素选择器 (Ctrl+Shift+C) 点击主界面特征元素
3. 在 Elements 面板中右键元素 → Copy → Copy selector
4. 或者使用 Playwright Inspector:
   - 在控制台输入：await page.pause()
   - 使用 Inspector 的元素选择工具

建议定位的特征元素：
- 主界面顶部导航栏
- 侧边菜单栏
- 主内容区域的唯一标识
- 用户信息显示区域
- 任何登录后独有的界面元素

============================================================

步骤 4：记录元素选择器

在开发者工具中：

1. 使用元素选择器 (Ctrl+Shift+C) 点击界面元素
2. 在 Elements 面板 查看元素 HTML
3. 右键元素 → Copy → 选择以下之一：
   • Copy selector - CSS 选择器
   • Copy XPath - XPath 路径
   • Copy JS path - JavaScript 路径

步骤 5：更新 locators.ts

将找到的元素选择器添加到 src/main/services/erp/locators.ts：

export const ERP_LOCATORS = {
  // ... 现有配置 ...

  // 新增：主界面特征元素（用于登录成功判定）
  mainPage: {
    topNavigationBar: '#top-nav', // 顶部导航栏
    sideMenu: '.side-menu', // 侧边菜单
    userProfile: '.user-profile', // 用户信息
    welcomeMessage: 'internal:has-text="欢迎"' // 欢迎消息
  }
}

步骤 6：退出脚本

按 Ctrl+C 终止脚本，浏览器会在 5 秒后自动关闭。

Playwright Inspector 使用技巧

开启 Inspector

在脚本暂停时，在浏览器控制台输入：

await page.pause()

会打开 Playwright Inspector，提供：

• 元素选择器
• 实时 locator 测试
• 代码生成

测试 Locator

在 Inspector 控制台测试 locator 是否有效：

// 测试 CSS 选择器
await page.locator('#top-nav').count()

// 测试 role-based 选择器
await page.getByRole('navigation').count()

// 测试文本选择器
await page.getByText('欢迎').count()

如果返回数量 > 0，说明选择器有效。

推荐的特征元素

选择登录成功判定元素时，优先选择：

1. 唯一性 - 只在登录后出现
2. 稳定性 - 不易随版本变更
3. 易定位 - 有明确的 id、class 或文本

推荐元素示例

元素类型	选择器示例	说明
顶部导航栏	#top-nav	登录后才会显示的主导航
用户菜单	.user-menu	显示当前用户名的菜单
欢迎消息	text=欢迎	包含用户名的欢迎语
工作台标题	h1:has-text("工作台")	主界面标题
功能模块网格	.module-grid	功能模块入口区域

常见问题

Q: 登录失败，提示找不到元素

A: 检查以下几点：

1. ERP URL 是否正确
2. 用户名密码是否正确
3. 网络连接是否正常
4. ERP 系统是否可访问
5. 是否需要验证码（如果 ERP 有验证码，需要手动输入）

Q: 登录后没有暂停

A: 检查控制台输出，可能登录流程中抛出了异常。查看错误信息并修复。

Q: 如何调试特定页面？

A: 修改脚本中的登录后逻辑，导航到特定页面：

// 登录后导航到特定页面
await page.goto(`${ERP_CONFIG.url}/yonbip/sc`)
await page.waitForTimeout(3000)

Q: 如何保存调试会话？

A: Playwright 支持录制 trace：

await context.tracing.start({ screenshots: true, snapshots: true })
// ... 操作 ...
await context.tracing.stop({ path: 'trace.zip' })

然后使用 npx playwright show-trace trace.zip 查看。

下一步

找到稳定的主界面元素后，修改以下文件优化登录判定：

1. 更新 locators.ts - 添加主界面元素定位器
2. 修改 erp-auth.ts - 在登录成功后等待主界面元素
3. 更新测试 - 验证新的登录判定逻辑