verify-invoice-default/RPA_USAGE.md

发票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获取浏览器配置目录：

# 登录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连接

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

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. 提取发票信息

基本提取（列表模式）

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

详细信息提取

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

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

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	是	浏览器配置目录

输出格式

成功输出

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

失败输出

{
  "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系统