# 发票RPA功能使用说明

## 概述

本功能为verify-invoice-default技能添加了RPA（机器人流程自动化）能力，可以自动从`https://sandbox.jc2009.com/industries/campus/smartcampus/app/finance/invoice-precheck`网站提取发票信息。

## 功能特性

1. **自动登录**：支持用户名密码自动登录
2. **页面导航**：自动导航到发票预检页面
3. **信息提取**：提取发票列表和详细信息
4. **拟人操作**：模拟真实用户操作，避免被检测
5. **错误处理**：处理登录超时、验证码等异常情况

## 前置条件

1. **浏览器配置目录**：需要通过account-manager获取`profile_dir`
2. **Python环境**：需要Python 3.10+环境
3. **依赖包**：需要`jiangchang-platform-kit>=1.2.11`

## 使用方法

### 1. 获取浏览器配置目录

首先，需要通过account-manager获取浏览器配置目录：

```bash
# 登录account-manager
python account-manager/scripts/main.py ensure-web --platform sandbox-jc2009

# 或者使用简化的命令
python account-manager/scripts/main.py pick-web --platform sandbox-jc2009 --ensure
```

### 2. 测试RPA连接

在使用前，建议先测试连接和登录功能：

```bash
cd verify-invoice-default/verify-invoice-default
python scripts/main.py test-rpa-connection \
  --username "15527406659" \
  --password "qwer1234" \
  --profile-dir "从account-manager获取的profile_dir"
```

### 3. 提取发票信息

#### 基本提取（列表模式）

```bash
python scripts/main.py extract-invoices \
  --username "15527406659" \
  --password "qwer1234" \
  --profile-dir "从account-manager获取的profile_dir"
```

#### 详细信息提取

```bash
python scripts/main.py extract-invoices \
  --username "15527406659" \
  --password "qwer1234" \
  --profile-dir "从account-manager获取的profile_dir" \
  --detail-mode
```

#### 无头模式（不推荐生产使用）

```bash
python scripts/main.py extract-invoices \
  --username "15527406659" \
  --password "qwer1234" \
  --profile-dir "从account-manager获取的profile_dir" \
  --headless
```

## 命令参数说明

### extract-invoices 命令

| 参数 | 必填 | 说明 |
|------|------|------|
| `--username` | 是 | 网站用户名 |
| `--password` | 是 | 网站密码 |
| `--profile-dir` | 是 | 浏览器配置目录 |
| `--headless` | 否 | 无头模式（生产不建议） |
| `--detail-mode` | 否 | 提取详细信息 |

### test-rpa-connection 命令

| 参数 | 必填 | 说明 |
|------|------|------|
| `--username` | 是 | 网站用户名 |
| `--password` | 是 | 网站密码 |
| `--profile-dir` | 是 | 浏览器配置目录 |

## 输出格式

### 成功输出

```json
{
  "total_count": 10,
  "invoices": [
    {
      "row_index": 0,
      "row_text": "发票信息...",
      "invoice_number": "12345678",
      "amount": "100.00"
    }
  ],
  "extraction_complete": true
}
```

### 失败输出

```json
{
  "success": false,
  "error": "错误信息",
  "stage": "错误发生阶段"
}
```

## 常见问题

### 1. 浏览器启动失败

**错误信息**：`ERROR:MISSING_BROWSER 浏览器启动失败`

**解决方案**：
- 确保已安装Chrome或Edge浏览器
- 检查`profile_dir`是否有效
- 确保没有其他浏览器进程占用配置目录

### 2. 登录失败

**错误信息**：`ERROR:LOGIN_TIMEOUT 登录失败或超时`

**解决方案**：
- 检查用户名和密码是否正确
- 确保网络连接正常
- 检查是否有验证码需要人工处理

### 3. 页面加载失败

**错误信息**：`导航到发票页面失败`

**解决方案**：
- 检查网络连接
- 确保已登录
- 检查目标URL是否正确

## 技术实现

### 架构设计

```
invoice_rpa.py          # RPA主流程协调
├── browser_session.py  # 浏览器会话管理
├── login_handler.py    # 登录处理
└── invoice_extractor.py # 发票信息提取
```

### 核心流程

1. **启动浏览器**：使用Playwright启动持久化浏览器上下文
2. **登录网站**：自动输入用户名密码，处理验证码
3. **导航页面**：跳转到发票预检页面
4. **提取信息**：解析页面DOM，提取发票数据
5. **返回结果**：格式化输出提取的发票信息

### 安全特性

1. **拟人操作**：模拟真实用户操作节奏
2. **错误处理**：完善的异常捕获和错误报告
3. **资源清理**：确保浏览器正确关闭
4. **日志记录**：详细的操作日志

## 开发说明

### 添加新的提取字段

1. 在`invoice_extractor.py`的`INVOICE_SELECTORS`中添加选择器
2. 在`_extract_invoice_from_row`函数中添加提取逻辑
3. 更新`format_invoice_data`函数的输出格式

### 修改登录流程

1. 在`login_handler.py`的`LOGIN_SELECTORS`中更新选择器
2. 修改`_try_auto_login`函数的登录逻辑
3. 更新`_is_logged_in`函数的检测逻辑

### 添加新的RPA功能

1. 在`service/rpa/`目录下创建新模块
2. 在`__init__.py`中导出新功能
3. 在`task_service.py`中添加对应的命令函数
4. 在`cli/app.py`中添加命令行参数

## 注意事项

1. **合规性**：仅用于授权范围内的正常界面操作
2. **频率控制**：避免频繁请求，防止被网站限制
3. **人工兜底**：验证码、人脸等必须等待人工完成
4. **数据安全**：不要在日志中暴露敏感信息
5. **资源管理**：确保浏览器会话正确关闭

## 更新日志

### v1.0.0 (2026-09-14)
- 初始版本
- 实现基本登录和页面导航
- 实现发票信息提取
- 集成到现有CLI系统