Metadata-Version: 2.4
Name: arrivalcli
Version: 0.1.2
Summary: CLI for Arrival Card partner API integration
Author: OpenAI Codex
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.31.0

# arrivalcli_cmd

面向合作方技术接入的命令行工具样例。

当前封装 3 个最小 API：

- `GET /v1/requirements`
- `POST /v1/orders`
- `GET /v1/orders/{order_id}/status`

并提供一个常用增强命令：

- `status-watch`
  持续轮询订单状态，直到进入结束状态
- `batch`
  通过 CSV 批量创建订单
- `ocr`
  对护照、机票、酒店资料执行本地 OCR
- `build-profile`
  根据 OCR 结果生成结构化 profile
- `validate`
  调用服务端核验结构化 profile
- `update-profile`
  更新已有订单的 profile 字段并重新核验
- `queue`
  将订单加入执行队列
- `execute`
  `queue` 的兼容别名
- `ocr-and-validate`
  一次完成 OCR、生成 profile、核验，可选直接建单
- `download-result`
  下载订单结果文件到本地目录
- `setup-claude`
  安装 Claude Code skill

## 1. 命令分层

面向 Claude Code / 普通用户时，建议优先只使用远程订单操作命令：

- `setup-claude`
- `requirements`
- `create`
- `status`
- `status-watch`
- `queue`
- `execute`
- `download-result`
- `update-profile`
- `validate`

以下命令当前仍保留在 CLI 中，但更适合内部调试 / 开发，不属于普通用户主路径：

- `ocr`
- `build-profile`
- `ocr-and-validate`
- `batch`

## 2. 配置

推荐优先使用用户级配置目录，而不是项目目录配置。

先执行：

```bash
arrivalcli init
```

这会自动在用户目录生成：

```text
~/.arrivalcli/config.json
```

然后可用下面命令查看当前实际使用的配置：

```bash
arrivalcli config show
```

如果要把 Claude Code skill 安装到本机：

```bash
arrivalcli setup-claude
```

如需覆盖已存在的 skill：

```bash
arrivalcli setup-claude --force
```

如果你的 Claude Code 使用的是默认目录，这条命令会自动把 `arrival-card-api` 安装到：

```text
~/.claude/skills/arrival-card-api
```

如果你这台机器不是这个目录，先在 Claude Code 中输入：

```text
/skills
```

查看这一行：

```text
User skills (实际目录)
```

然后用显式目录安装：

```bash
arrivalcli setup-claude --skills-dir "实际目录"
```

如果你希望显式指定 skill 中使用的 `arrivalcli` 命令路径，也可以：

```bash
ARRIVALCLI_BIN="$(python3 -m site --user-base)/bin/arrivalcli"
arrivalcli setup-claude --skills-dir "实际目录" --cli-command "$ARRIVALCLI_BIN"
```

安装完成后，在 Claude Code 中输入：

```text
/skills
```

确认出现：

- `arrival-card-api`

说明：

- `setup-claude` 会自动探测当前可用的 `arrivalcli` 路径，并写入 skill 模板
- 这样 Claude Code 执行 skill 时，不必依赖 shell PATH 恰好正确

默认配置结构如下：

```json
{
  "base_url": "http://43.108.15.8:9527",
  "timeout_sec": 20,
  "api_key": "replace-with-your-skill-api-key"
}
```

## 3. 用法

### 查看材料要求

```bash
arrivalcli requirements -c singapore
arrivalcli requirements -c 韩国
arrivalcli requirements -c KR
arrivalcli requirements -c 马尔代夫
```

当前已内置常见别名映射，例如：

- `韩国` / `KR` / `KOR` -> `korea`
- `新加坡` / `SG` / `SGP` -> `singapore`
- `马尔代夫` / `MV` / `MDV` -> `maldives`

### 创建订单

```bash
arrivalcli create \
  -c singapore \
  -a 2026-05-20 \
  -n 张三 \
  -m 13800138000 \
  -e test@example.com \
  -p /path/to/passport.jpg \
  -i /path/to/inbound_ticket.jpg \
  -H /path/to/hotel.jpg
```

补充说明：

- 在 Claude Code 用户路径里，用户提交资料后，应由服务端自动完成 OCR、生成 profile、返回核验结果
- 不应把本地 `ocr / build-profile / ocr-and-validate` 当成普通用户默认主路径

### 对资料图片执行 OCR

单文件模式，支持用户一张一张识别：

```bash
arrivalcli ocr -c singapore --type passport --file /path/to/passport.jpg --output ./passport_ocr.json
arrivalcli ocr -c singapore --type inbound_ticket --file /path/to/inbound_ticket.jpg --output ./inbound_ocr.json
arrivalcli ocr -c singapore --type hotel --file /path/to/hotel.jpg --output ./hotel_ocr.json
```

如需整笔资料一起识别，也仍然支持：

```bash
arrivalcli ocr \
  -c singapore \
  -a 2026-05-20 \
  -p /path/to/passport.jpg \
  -i /path/to/inbound_ticket.jpg \
  -H /path/to/hotel.jpg \
  --output ./ocr_result.json
```

说明：

- `ocr` 支持单文件模式和整笔模式
- 单文件模式适合 Claude Code 对话里“一张一张上传、一张一张识别”
- 输出包含 `raw_results` 和 `normalized_results`

### 根据 OCR 结果生成 profile

```bash
arrivalcli build-profile \
  -c singapore \
  --ocr-results-file ./ocr_result.json \
  --output ./profile.json
```

如需补充用户已知字段：

```bash
arrivalcli build-profile \
  -c singapore \
  --ocr-results-file ./ocr_result.json \
  --user-input-json '{"email":"test@example.com","mobile":"13800138000"}' \
  --output ./profile.json
```

### 核验结构化 profile

```bash
arrivalcli validate \
  -c singapore \
  --profile-file ./profile.json \
  --output ./validate_result.json
```

说明：

- `validate` 只适用于已有结构化 profile
- 如果用户手里只有图片，正确流程是 `ocr -> build-profile -> validate -> create`

### 更新订单字段并重新核验

```bash
arrivalcli update-profile \
  -o 10 \
  --field contact_in_korea=02112345678 \
  --field departure_date=2026-06-08
```

也可以用 JSON：

```bash
arrivalcli update-profile \
  -o 10 \
  --fields-json '{"contact_in_korea":"02112345678","departure_date":"2026-06-08"}'
```

### 将订单加入执行队列

```bash
arrivalcli queue 10
arrivalcli queue -o 10
```

兼容别名：

```bash
arrivalcli execute 10
```

### 一步完成 OCR、生成 profile、核验

```bash
arrivalcli ocr-and-validate \
  -c singapore \
  -a 2026-05-20 \
  -p /path/to/passport.jpg \
  -i /path/to/inbound_ticket.jpg \
  -H /path/to/hotel.jpg \
  --output ./ocr_validate_result.json
```

如果核验通过后希望继续直接建单：

```bash
arrivalcli ocr-and-validate \
  -c singapore \
  -a 2026-05-20 \
  -p /path/to/passport.jpg \
  -i /path/to/inbound_ticket.jpg \
  -H /path/to/hotel.jpg \
  -m 13800138000 \
  -e test@example.com \
  --create-if-valid \
  --output ./ocr_validate_result.json
```

说明：

- 这条命令适合“用户手里只有图片，想先判断资料是否合理”
- 返回里会包含 `ocr`、`profile`、`validate`
- 只有当 `can_create=true` 时，才建议继续建单

### 查询订单状态

```bash
arrivalcli status -o 123
```

### 持续轮询订单状态

```bash
arrivalcli status-watch -o 123 -s 10
```

### 通过 CSV 批量创建订单

```bash
arrivalcli batch \
  -c singapore \
  -f ./team.csv \
  --output ./batch_result.json
```

如需创建后自动轮询每笔订单：

```bash
arrivalcli batch \
  -c singapore \
  -f ./team.csv \
  --watch \
  -s 10 \
  -r 60 \
  --output ./batch_result.json
```

### 下载订单结果文件

```bash
arrivalcli download-result \
  -o 123 \
  --output ./results/
```

如需只下载部分类型：

```bash
arrivalcli download-result \
  -o 123 \
  --output ./results/ \
  --include pdf,success,error
```

支持类型：

- `pdf`
- `review`
- `success`
- `error`
- `captcha`
- `all`

说明：

- 命令会先查询订单状态，再根据状态返回的 URL 下载文件
- 下载走 API Key 鉴权，不依赖后台管理员登录态
- 如果某类文件当前不存在，不会报错退出，而会记入 `skipped`
- 对于像马尔代夫这类可能没有 PDF 的国家，建议优先下载 `success` 或 `error`

CSV 首版支持以下列：

- `arrival_date`
- `contact_name`
- `mobile`
- `email`
- `notes`
- `passport_file`
- `inbound_ticket_file`
- `hotel_file`
- `outbound_ticket_file`

其中首版必填列：

- `arrival_date`
- `passport_file`
- `inbound_ticket_file`
- `hotel_file`

示例：

```csv
arrival_date,contact_name,mobile,email,notes,passport_file,inbound_ticket_file,hotel_file,outbound_ticket_file
2026-05-20,张三,13800138000,test1@example.com,团队A,/data/p1.jpg,/data/i1.jpg,/data/h1.jpg,/data/o1.jpg
2026-05-20,李四,13800138001,test2@example.com,团队A,/data/p2.jpg,/data/i2.jpg,/data/h2.jpg,
```

说明：

- `-s` 表示轮询间隔秒数
- 当状态进入 `completed`、`manual_followup`、`verification_required`、`failed` 等结束状态时自动停止
- `batch --watch` 会在每笔订单创建成功后继续轮询状态
- `batch` 返回里会包含：
  - `create_response`
  - `watch_response`

### OCR 预留命令

```bash
arrivalcli ocr -o 123
```

当前会直接返回提示：

- 后端暂未开放 OCR API
- 需要先通过后台页面执行 OCR

## 3. 可选参数

- `--config /path/to/config.json`
  显式指定配置文件。优先级最高

- `--host http://127.0.0.1:9527`
  临时覆盖 `base_url`

- `--api-key your-key`
  临时覆盖 `api_key`

- `ARRIVALCLI_CONFIG=/path/to/config.json`
  通过环境变量指定配置文件路径

- `batch --output /path/to/result.json`
  将批量执行结果写入本地 JSON 文件

## 4. 打包安装

本项目已支持做成可安装的命令行工具。

在项目根目录执行：

```bash
pip install .
```

安装后可直接使用：

```bash
arrivalcli --help
arrivalcli init
arrivalcli config show
arrivalcli requirements -c singapore
arrivalcli batch -c singapore -f ./team.csv --output ./batch_result.json
arrivalcli batch -c singapore -f ./team.csv --watch -s 10 -r 60 --output ./batch_result.json
arrivalcli download-result -o 123 --output ./results/
arrivalcli status -o 123
arrivalcli status-watch -o 123 -s 10
```

配置查找优先级：

1. `--config /path/to/config.json`
2. 环境变量 `ARRIVALCLI_CONFIG`
3. 用户目录 `~/.arrivalcli/config.json`
4. 项目目录 `arrivalcli_cmd/config.json`
