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

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 行：

const ERP_CONFIG = {
  url: 'https://your-erp-server.com', // ← 修改
  username: 'your_username', // ← 修改
  password: 'your_password' // ← 修改
}

步骤 2：运行调试

npm run debug:erp-login

步骤 3：定位元素

登录成功后：

1. 按 F12 打开开发者工具
2. 按 Ctrl+Shift+C 启用元素选择器
3. 点击主界面特征元素
4. 右键 → Copy → Copy selector

步骤 4：更新定位器

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

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

  // 新增：主界面特征元素
  mainPage: {
    // 在此添加找到的元素
    topNav: '#top-nav',
    userMenu: '.user-menu'
  }
}

脚本功能

自动执行

• ✅ 启动浏览器（可见窗口，非无头模式）
• ✅ 导航到登录页面
• ✅ 输入用户名和密码
• ✅ 点击登录按钮
• ✅ 处理强制登录确认对话框

调试支持

• ✅ 登录成功后自动暂停
• ✅ 保持浏览器打开
• ✅ 支持 F12 开发者工具
• ✅ 支持 Playwright Inspector

安全特性

• ✅ 密码显示为星号
• ✅ 需要按 Enter 确认后才开始
• ✅ 退出前 5 秒缓冲时间

常用命令

# 运行调试脚本
npm run debug:erp-login

# 或使用 npx 直接运行
npx tsx src/main/tools/erp-login-debug.ts

# 查看帮助
npx tsx --help

调试技巧

测试 Locator 有效性

在浏览器控制台（登录后暂停时）：

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

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

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

返回值 > 0 或 true 表示选择器有效。

查看元素详细信息

// 获取元素 HTML
const element = await page.$('#top-nav')
console.log(await element.innerHTML())

// 获取元素属性
console.log(await element.getAttributes())

截图保存

// 全屏截图
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 未安装

解决:

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	详细文档