verify-invoice-default/PLATFORM_USAGE.md

# 平台内使用RPA功能的完整指南

## 📋 概述

本指南详细说明如何将带RPA功能的verify-invoice-default技能发布到平台，并在平台内使用RPA功能。

## 🎯 平台内使用方式

### 1. **通过CLI命令使用**（推荐）

在平台内，用户可以通过以下CLI命令使用RPA功能：

#### **1.1 提取发票信息**
```bash
# 基本提取
python scripts/main.py extract-invoices \
  --username "用户名" \
  --password "密码" \
  --profile-dir "浏览器配置目录"

# 详细信息提取
python scripts/main.py extract-invoices \
  --username "用户名" \
  --password "密码" \
  --profile-dir "浏览器配置目录" \
  --detail-mode
```

#### **1.2 测试RPA连接**
```bash
python scripts/main.py test-rpa-connection \
  --username "用户名" \
  --password "密码" \
  --profile-dir "浏览器配置目录"
```

#### **1.3 查询提取的数据**
```bash
# 查询所有提取记录
python scripts/main.py list-rpa-invoices

# 按批次ID查询
python scripts/main.py list-rpa-invoices --batch-id "批次ID"

# 按状态查询
python scripts/main.py list-rpa-invoices --status "extracted"

# 查看详细记录
python scripts/main.py show-rpa-invoice --record-id 1

# 获取统计信息
python scripts/main.py rpa-invoice-stats
```

### 2. **通过Action调用**（平台集成）

在平台内，可以通过`run_skill_action`调用RPA功能：

```bash
# 提取发票信息（异步）
run_skill_action --action extract-invoices \
  --input '{"username": "用户名", "password": "密码", "profile_dir": "目录"}'

# 查询提取记录
run_skill_action --action list-rpa-invoices \
  --input '{"limit": 10, "batch_id": "批次ID"}'

# 获取统计信息
run_skill_action --action rpa-invoice-stats
```

### 3. **通过对话交互**（LLM集成）

用户可以通过自然语言与LLM交互来使用RPA功能：

**示例对话：**
```
用户：帮我从网站提取发票信息
LLM：好的，我需要一些信息来执行RPA操作：
1. 网站用户名
2. 网站密码
3. 浏览器配置目录（需要先通过account-manager获取）

请提供这些信息，我将为您提取发票信息。
```

## 🔧 平台内配置步骤

### 步骤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：配置环境变量

创建`.env`文件配置必要的环境变量：

```env
# RPA配置
OPENCLAW_BROWSER_HEADLESS=0
OPENCLAW_RECORD_VIDEO=1
HUMAN_WAIT_TIMEOUT=120

# 日志配置
LOG_LEVEL=INFO
```

### 步骤3：初始化数据库

```bash
python scripts/main.py init-db
```

## 📊 数据流架构

### 平台内数据流

```
用户请求 → LLM/CLI → RPA模块 → 浏览器自动化 → 网站数据提取
                ↓
            数据存储 → SQLite数据库
                ↓
            查询接口 → 数据管理界面
```

### 数据存储位置

1. **SQLite数据库**：`{JIANGCHANG_DATA_ROOT}/{JIANGCHANG_USER_ID}/verify-invoice-default/data.db`
   - `rpa_invoices`表：存储RPA提取的原始数据
   - `invoice_records`表：存储预审后的发票记录
   - `prereview_reports`表：存储预审报告

2. **录屏文件**：`{JIANGCHANG_DATA_ROOT}/{JIANGCHANG_USER_ID}/verify-invoice-default/videos/`

3. **日志文件**：`{JIANGCHANG_DATA_ROOT}/{JIANGCHANG_USER_ID}/verify-invoice-default/logs/`

## 🎮 平台内使用场景

### 场景1：批量发票提取

**用户需求**：从网站批量提取100张发票信息

**操作步骤**：
1. 用户通过CLI或对话发起请求
2. RPA模块自动登录网站
3. 提取发票列表信息
4. 保存到数据库
5. 返回提取结果

**命令示例**：
```bash
python scripts/main.py extract-invoices \
  --username "15527406659" \
  --password "qwer1234" \
  --profile-dir "/path/to/profile"
```

### 场景2：发票信息查询

**用户需求**：查看之前提取的发票信息

**操作步骤**：
1. 用户查询提取记录
2. 系统从数据库读取数据
3. 返回结构化结果

**命令示例**：
```bash
# 查询最近10条记录
python scripts/main.py list-rpa-invoices --limit 10

# 查看特定记录详情
python scripts/main.py show-rpa-invoice --record-id 5
```

### 场景3：统计分析

**用户需求**：查看RPA提取的统计信息

**操作步骤**：
1. 用户请求统计信息
2. 系统查询数据库统计
3. 返回统计结果

**命令示例**：
```bash
python scripts/main.py rpa-invoice-stats
```

## 🔐 安全考虑

### 1. 账号安全

- **密码加密**：建议在`.env`中配置密码，不要硬编码
- **权限控制**：通过account-manager管理账号权限
- **会话管理**：浏览器配置目录隔离不同用户

### 2. 数据安全

- **数据脱敏**：日志中自动脱敏敏感信息
- **访问控制**：通过平台权限系统控制数据访问
- **审计日志**：记录所有RPA操作

### 3. 操作安全

- **频率控制**：避免频繁请求，防止被网站限制
- **人工兜底**：验证码、人脸等必须等待人工完成
- **错误处理**：完善的异常捕获和错误报告

## 📈 平台集成优势

### 1. 统一管理

- **账号管理**：通过account-manager统一管理浏览器配置
- **权限控制**：平台级权限管理
- **日志聚合**：统一日志查看和分析

### 2. 数据共享

- **数据存储**：统一数据存储和备份
- **数据查询**：通过数据管理界面查询
- **数据导出**：支持多种格式导出

### 3. 监控运维

- **健康检查**：平台级健康检查
- **性能监控**：RPA操作性能监控
- **告警通知**：异常情况自动告警

## 🚀 发布到平台的步骤

### 步骤1：准备发布文件

确保以下文件已准备就绪：

```
verify-invoice-default/
├── SKILL.md                    # 技能说明
├── README.md                   # 用户说明
├── TUTORIAL.md                 # 使用教程
├── CHANGELOG.md                # 更新日志
├── scripts/                    # 脚本目录
│   ├── main.py                # CLI入口
│   └── service/               # 服务模块
├── development/                # 开发文档
└── examples/                   # 示例文件
```

### 步骤2：验证功能

```bash
# 测试CLI命令
python scripts/main.py health
python scripts/main.py version

# 测试RPA功能
python scripts/main.py test-rpa-connection \
  --username "测试用户" \
  --password "测试密码" \
  --profile-dir "测试目录"
```

### 步骤3：打包发布

```bash
# 使用release脚本
python tools/release.ps1

# 或者手动打包
tar -czf verify-invoice-default.tar.gz verify-invoice-default/
```

### 步骤4：上传到平台

1. 登录平台管理后台
2. 上传技能包
3. 配置技能元数据
4. 发布技能

## 📝 平台内使用示例

### 示例1：通过CLI提取发票

```bash
# 1. 获取浏览器配置
python account-manager/scripts/main.py ensure-web --platform sandbox-jc2009

# 2. 提取发票信息
python scripts/main.py extract-invoices \
  --username "15527406659" \
  --password "qwer1234" \
  --profile-dir "/path/to/profile"

# 3. 查看提取结果
python scripts/main.py list-rpa-invoices --limit 5
```

### 示例2：通过对话交互

```
用户：我想提取网站上的发票信息
LLM：好的，我来帮您提取发票信息。请提供：
1. 网站用户名：15527406659
2. 网站密码：qwer1234
3. 浏览器配置目录：/path/to/profile

LLM：正在执行RPA提取...
LLM：成功提取了10张发票信息，已保存到数据库。

用户：查看提取的发票详情
LLM：为您查询到最近5条提取记录：
1. 批次ID: abc123, 提取时间: 2026-09-14 10:30:00, 状态: 已提取
2. 批次ID: def456, 提取时间: 2026-09-14 11:00:00, 状态: 已提取
...
```

## 🔍 故障排除

### 问题1：浏览器启动失败

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

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

### 问题2：登录失败

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

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

### 问题3：数据保存失败

**错误**：数据库写入失败

**解决方案**：
1. 检查数据库文件权限
2. 确认数据库表是否已创建
3. 检查磁盘空间是否充足

## 📞 技术支持

### 常见问题

1. **如何获取浏览器配置目录？**
   - 使用`account-manager`工具：`python account-manager/scripts/main.py ensure-web --platform sandbox-jc2009`

2. **如何查看提取的发票数据？**
   - 使用命令：`python scripts/main.py list-rpa-invoices`

3. **如何导出提取的数据？**
   - 使用命令：`python scripts/main.py show-rpa-invoice --record-id 1`，然后复制JSON输出

### 联系方式

- 技术支持：support@jiangchang.com
- 文档地址：https://docs.jiangchang.com/verify-invoice-default
- 问题反馈：https://github.com/jiangchang/verify-invoice-default/issues