Metadata-Version: 2.4
Name: drinkzen-admin-cli
Version: 0.2.4
Summary: Standalone CLI client for DrinkZen Admin operations
Author: DrinkZen Team
License: MIT
Project-URL: Homepage, https://drinkzen.cn
Project-URL: Source, https://github.com/xiaolinstar/drinkzen
Project-URL: Issues, https://github.com/xiaolinstar/drinkzen/issues
Keywords: drinkzen,admin,beverage,operations,cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# drinkzen-admin-cli

`drinkzen-admin-cli` 是奶茶仙人（DrinkZen）运营管理后台的轻量级、零外部依赖 Python 命令行工具。
可由管理员直接在终端使用，也可挂载至用户自己的 AI Agent（如 Antigravity / Claude / Cursor 等）进行安全的辅助审核与菜单数据治理。

> 💡 **命令定位说明**：
>
> - `drinkzen-admin`：管理员与数据运营专属 CLI，用于配置管理、品牌管理、菜单模板配置、Logo 上传与用户贡献审核。
> - `drinkzen`：（规划中）普通用户专属 CLI，用于查询饮品热量、记录饮用与管理每日预算。

---

## 快速安装与分发方式

### 方式 1：通过 PyPI 安装（正式发布后推荐）

```bash
pipx install drinkzen-admin-cli
```

### 方式 2：通过 Git URL 一键直接安装（预发布或源码验证）

```bash
pip install "git+https://github.com/xiaolinstar/drinkzen.git#subdirectory=packages/admin-cli"
```

### 方式 3：通过 pipx 隔离环境运行 Git 源码（免污染系统 Python）

```bash
pipx run --spec "git+https://github.com/xiaolinstar/drinkzen.git#subdirectory=packages/admin-cli" drinkzen-admin config show
```

### 方式 4：在 Monorepo 本地源码开发运行

```bash
# 可编辑安装
pip install -e packages/admin-cli

# 或直接通过 Python 模块运行
PYTHONPATH=packages/admin-cli python3 -m drinkzen_admin.cli config show
```

---

## 密钥与持久化配置管理 (`config`)

`drinkzen-admin` 提供了内置的密钥持久化管理，避免每次在终端手动输入敏感 Token 或将其留在 Bash 历史记录中。

### 1. 一键保存服务端地址与 Secret

```bash
# 保存远程生产 API 与 Admin Token
drinkzen-admin config set --set-url "https://api.drinkzen.cn" --set-token "your-secret-admin-token"

# 保存本地开发 API
drinkzen-admin config set --set-url "http://api.drinkzen.localhost:8000" --set-token "local-admin-token"
```

配置文件将保存在 `~/.drinkzen/admin.json`，且在 Unix/macOS 系统上自动设置 **`chmod 600`** 权限（仅当前系统用户可读写）。

### 2. 查看当前生效的配置与 Secret 脱敏展示

```bash
drinkzen-admin config show --json
```

输出示例：

```json
{
  "config_file": "/Users/admin/.drinkzen/admin.json",
  "file_exists": true,
  "active_url": "https://api.drinkzen.cn",
  "url_source": "file",
  "active_token": "secr****1234",
  "token_source": "file"
}
```

### 3. 配置加载优先级

当执行命令时，配置按如下优先级依次生效：

1. **显式命令行参数**：`--url "..."` / `--token "..."`
2. **系统环境变量**：`DRINKZEN_API_BASE_URL` / `DRINKZEN_ADMIN_TOKEN`
3. **用户配置文件**：`~/.drinkzen/admin.json`
4. **内置默认值**：`http://localhost:8000` / `local-admin-token`

---

## 常用业务命令速查

配置好 Secret 后，日常执行命令无需再附带 URL 和 Token：

### 1. 品牌管理 (`brand`)

```bash
# 查看品牌列表（支持 --search 与 --active-only）
drinkzen-admin brand list --search "霸王" --json

# 查看具体品牌详情
drinkzen-admin brand show 霸王茶姬 --json

# 更新品牌名称/别名/启用状态（--dry-run 仅预览变更，不真正写库）
drinkzen-admin brand update 霸王茶姬 --name "霸王茶姬 CHAGEE" --alias "CHAGEE" --dry-run --json

# 上传品牌 Logo 并标注数据置信度
drinkzen-admin brand set-logo 霸王茶姬 ./logo.png --confidence verified --source-name "官方小程序"
```

### 2. 菜单模板管理 (`menu-template`)

```bash
# 导出品牌菜单模板到本地文件
drinkzen-admin menu-template export 霸王茶姬 --out chagee.json

# 本地离线校验 JSON 模板合法性
drinkzen-admin menu-template validate chagee.json --json

# 预览应用新模板到指定品牌
drinkzen-admin menu-template apply 霸王茶姬 chagee.json --dry-run --json
```

### 3. 审核任务管理 (`review`)

```bash
# 列出待审核任务
drinkzen-admin review list --status pending --limit 10 --json

# 查看某个审核任务上下文与用户提交数据
drinkzen-admin review show 102 --json

# 审核处理（动作支持 create / merge / supplement / reject）
drinkzen-admin review resolve 102 create --reason "官方菜单确认无误，同意入库" --dry-run --json
```

---

## 安全设计原则

1. **零外部第三方依赖**：仅使用 Python 标准库，保证极致的安全与跨平台兼容性。
2. **不直连数据库**：所有写操作通过带有权限校验与审计追踪的 RESTful API 完成。
3. **Secret 安全隔离**：配置文件自动进行 0600 文件权限保护，`show` 输出自动脱敏，防止日志/录屏泄露。
4. **全命令支持 `--dry-run` 与 `--json`**：便于 AI Agent 输出结构化建议并在人工确认后再执行真正变更。

---

## 发布维护说明

发布由 GitHub Actions 的 **Publish Admin CLI** workflow 完成，使用 PyPI Trusted Publishing（OIDC），不使用长期 PyPI Token。

首次发布前，项目维护者需要在 PyPI 和 TestPyPI 分别配置对应的 Trusted Publisher：

- Owner：`xiaolinstar`
- Repository：`drinkzen`
- Workflow：`publish-admin-cli.yml`
- Environment：TestPyPI 使用 `testpypi`，正式 PyPI 使用 `pypi`

先通过 workflow 选择 `testpypi` 并填写当前包版本完成安装验证，再选择 `pypi` 发布正式版本。版本不可覆盖；每次发布前必须先提升 `packages/admin-cli/pyproject.toml` 中的版本号。
