---
id: 021
title: `xq admin` CLI（审核 / 封号 / 退款；Claude 用）
status: closed
labels: [feature, p3, admin-cli, internal]
assignee: team-lead
closed_at: 2026-04-23
created_at: 2026-04-23
---

# #021 xq admin CLI（替代原 HTML 后台）

## 方案变更（2026-04-23 老板定）

~~原方案：轻量 FastAPI + HTML 后台 + basic auth~~

**新方案**：**没有 HTML 后台**。

- **管理操作** → `xq admin` **CLI 子命令树**（Claude 用，比点 UI 快）
- **只读指标** → M5 metrics 徽章 + 未来 `xq admin stats` 纯文本展示（老板偶尔看）
- 没 HTML 前端 / 没 basic auth / 没维护成本

**理由**：老板是唯一"管理员"，他不亲自操作管理（交给 Claude 代理）。Claude 跑 CLI 比操纵 UI 快 10 倍 + 可脚本化 + 可 audit（命令行历史）。

## CLI 树设计

```
xq admin
  user
    info <user_id>         # 详情：profile / 封号状态 / 余量 / 最近订单
    ban <user_id> [--reason]     # 软封（session 失效 + 无法 send）
    unban <user_id>        # 解封
    list --status banned   # 按状态筛
  review
    pending                # 列待审核举报
    pass <report_id>       # 通过（无动作，标处理了）
    reject <report_id>     # 驳回（标 spam 举报不 ban 被举报者）
    confirm <report_id> --ban-target    # 确认违规 + 顺手封号
  refund
    list --status pending  # 列待处理退款请求（未来 #020）
    approve <order_id>     # 调 alipay.trade.refund + 加回余量扣
    reject <order_id>      # 驳回退款
  stats                    # 业务指标（用户数 / 今日新增 / 付款额 / 举报数）
```

## 权限

**env 白名单模式**：`XIANGQIN_ADMIN_USER_IDS=01J...,01K...`（逗号分隔），session 的 user_id 在列表里才放行 admin 命令。不在 → 返 `403 not_admin`。

启动时从 env 读入 set；无 env → admin 命令全拒。

## 实施顺序（覆盖 #016 / #017 / #020）

1. **admin CLI 骨架** + auth（这个 issue 主体）
2. **封号机制** → issue #017 通过 `xq admin user ban/unban` 实现
3. **举报审核** → issue #016 通过 `xq admin review pending/pass/reject/confirm` 实现
4. **退款** → issue #020 通过 `xq admin refund` 实现（依赖 #013 真付先上线 ✓）

MVP 包含 1 + 2 + 3，#020 退款后续（需要支付宝 refund API 集成）。

## 工作量

MVP（1+2+3）: **3-5 天**。比 HTML admin 省一半时间 + 零前端维护。

## 相关

- 依赖 `FEAT-001/002` 登录（admin CLI 复用现有 session token）
- 被依赖 #016 / #017 / #020 的实施都走这个 CLI
- 老板日常看指标依赖 M5 metrics + M1-M4 chaos badges
