# popcorn-op-cli

Popcorn 官方经营命令行客户端。通过本地配置的后管 CLI API Key 调用经营报表接口，用于查询平台总览、组织目录、租户与模型汇总，以及单租户下钻明细。所有报表命令均为只读。

## 安装

需要 Node.js 18 或更高版本。

首次安装请按 [爆米花运营 CLI 安装与使用指南](docs/installation-guide.md) 操作；该指南包含环境准备、API Key 配置、首个报表和故障排查。

```bash
npm install -g @baomihuatop/popcorn-op-cli
```

安装后确认命令可用：

```bash
popcorn-op-cli --version
popcorn-op-cli --help
```

## 配置

安装后需先配置后端地址和 CLI API Key（由运维提供）：

```bash
popcorn-op-cli config set-url <YOUR_ADMIN_BACKEND_URL>
popcorn-op-cli config set-api-key <YOUR_CLI_API_KEY>
```

`baseUrl` 是后端根地址，不要加 `/admin` 或 `/api` 后缀。

```bash
# 查看当前环境
popcorn-op-cli config show
```

配置会保存在本机：`~/.popcorn-op-cli/config.json`。

## 经营报表

报表固定按北京时间（`Asia/Shanghai`）统计，不提供 `--timezone` 参数。日期使用 `YYYY-MM-DD`；传入时 `--start-date` 和 `--end-date` 必须同时提供。不传日期时由后端默认本月 1 日至当前日。

平台总览：

```bash
popcorn-op-cli report overview \
  --start-date 2026-08-01 \
  --end-date 2026-08-31
```

组织目录及配置模型（平台运营权限）：

```bash
popcorn-op-cli report organizations
```

租户与模型列表：

```bash
popcorn-op-cli report tenants
popcorn-op-cli report models
```

单租户汇总，以及按账户或模型下钻：

```bash
popcorn-op-cli report tenant 1001
popcorn-op-cli report tenant 1001 --breakdown accounts
popcorn-op-cli report tenant 1001 --breakdown models
```

当前命令输出后端原始 `{ data, meta }` JSON，便于脚本和二次处理。

## 积分流水明细导出

`detail` 用于导出租户在指定时间范围内的积分流水，会自动请求全部分页并写入文件。日期按北京时间解释。

```bash
# 仅导出积分分配流水（credit_type=allocate）
popcorn-op-cli detail allocation \
  --tenant-id 123 \
  --start-date 2026-08-01 \
  --end-date 2026-08-10 \
  --output ./tenant-123-allocation.csv

# 导出该租户的全部积分变更明细
popcorn-op-cli detail changes \
  --tenant-id 123 \
  --start-date 2026-08-01 \
  --end-date 2026-08-10 \
  --output ./tenant-123-changes.json
```

默认按输出文件扩展名选择格式：`.csv` 为 CSV，`.json` 为 JSON；也可以显式传入 `--format csv` 或 `--format json`。

| 指标 | 说明 |
|------|------|
| `pool_consumed_credits` | 租户积分池下发/扣减；用于余额经营 |
| `task_consumed_credits` | 任务净消耗：预扣减去失败和结算返还 |
| `closing_balance_credits` | 查询截止日的可用积分余额 |
| `task_count` | 任务主记录数量，不重复计算重试 |

## 常用命令

| 命令 | 说明 |
|------|------|
| `popcorn-op-cli config set-url <url>` | 设置后管地址 |
| `popcorn-op-cli config set-api-key <key>` | 设置 CLI API Key |
| `popcorn-op-cli config show` | 查看当前配置 |
| `popcorn-op-cli report overview` | 查看全局经营总览 |
| `popcorn-op-cli report organizations` | 查看组织目录和配置模型 |
| `popcorn-op-cli report tenants` | 查看租户汇总列表 |
| `popcorn-op-cli report models` | 查看模型汇总列表 |
| `popcorn-op-cli report tenant <id>` | 查看单租户汇总或下钻明细 |
| `popcorn-op-cli detail allocation ...` | 导出指定租户的积分分配流水 |
| `popcorn-op-cli detail changes ...` | 导出指定租户的全部积分变更明细 |

所有命令都支持 `--help`：

```bash
popcorn-op-cli --help
popcorn-op-cli report --help
popcorn-op-cli report overview --help
popcorn-op-cli detail --help
popcorn-op-cli config --help
```

## 升级

```bash
npm install -g @baomihuatop/popcorn-op-cli@latest
```

## 卸载

```bash
npm uninstall -g @baomihuatop/popcorn-op-cli
```

## 常见问题

`popcorn-op-cli: command not found`

确认 npm 全局安装目录已加入 `PATH`，或重新打开终端后再试。

`未配置 API Key`

先执行：

```bash
popcorn-op-cli config set-api-key <YOUR_CLI_API_KEY>
```

`401 / 403`

API Key 缺失、过期、错误，或没有报表权限 / 请求范围越权。请重新配置有效的后管 CLI API Key。

`--start-date 和 --end-date 必须同时提供`

日期参数必须成对传入，例如：

```bash
popcorn-op-cli report overview --start-date 2026-08-01 --end-date 2026-08-31
```