refactor(docs): reorganize documentation directory structure
- 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.
This commit is contained in:
Misaka_Company
236
docs/debugging/erp-login-debug-guide.md
Normal file
236
docs/debugging/erp-login-debug-guide.md
Normal file
@@ -0,0 +1,236 @@
|
||||
# ERP 登录调试工具使用说明
|
||||
|
||||
## 目的
|
||||
|
||||
用于人工调试 ERP 登录流程，定位主界面特征元素，以便优化登录成功的判定逻辑。
|
||||
|
||||
## 前置准备
|
||||
|
||||
### 1. 配置 ERP 登录信息
|
||||
|
||||
编辑 `src/main/tools/erp-login-debug.ts` 文件，修改以下配置：
|
||||
|
||||
```typescript
|
||||
const ERP_CONFIG = {
|
||||
url: 'https://your-erp-server.com', // ← 修改为你的 ERP 地址
|
||||
username: 'your_username', // ← 修改为你的用户名
|
||||
password: 'your_password' // ← 修改为你的密码
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 确保 tsx 已安装
|
||||
|
||||
如果运行时报错提示找不到 `tsx`，请安装：
|
||||
|
||||
```bash
|
||||
npm install -g tsx
|
||||
# 或作为项目依赖
|
||||
npm install --save-dev tsx
|
||||
```
|
||||
|
||||
## 使用方法
|
||||
|
||||
### 方式一：使用 npm 脚本（推荐）
|
||||
|
||||
```bash
|
||||
npm run debug:erp-login
|
||||
```
|
||||
|
||||
### 方式二：直接运行
|
||||
|
||||
```bash
|
||||
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`：
|
||||
|
||||
```typescript
|
||||
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
|
||||
|
||||
在脚本暂停时，在浏览器控制台输入：
|
||||
|
||||
```javascript
|
||||
await page.pause()
|
||||
```
|
||||
|
||||
会打开 Playwright Inspector，提供：
|
||||
|
||||
- 元素选择器
|
||||
- 实时 locator 测试
|
||||
- 代码生成
|
||||
|
||||
### 测试 Locator
|
||||
|
||||
在 Inspector 控制台测试 locator 是否有效：
|
||||
|
||||
```javascript
|
||||
// 测试 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**: 修改脚本中的登录后逻辑，导航到特定页面：
|
||||
|
||||
```typescript
|
||||
// 登录后导航到特定页面
|
||||
await page.goto(`${ERP_CONFIG.url}/yonbip/sc`)
|
||||
await page.waitForTimeout(3000)
|
||||
```
|
||||
|
||||
### Q: 如何保存调试会话？
|
||||
|
||||
**A**: Playwright 支持录制 trace：
|
||||
|
||||
```typescript
|
||||
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. **更新测试** - 验证新的登录判定逻辑
|
||||
241
docs/debugging/erp-login-debug-quickref.md
Normal file
241
docs/debugging/erp-login-debug-quickref.md
Normal file
@@ -0,0 +1,241 @@
|
||||
# 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` | 详细文档 |
|
||||
Reference in New Issue
Block a user