drinkzen-admin-cli 0.2.4__tar.gz

drinkzen_admin_cli-0.2.4/PKG-INFO

@@ -0,0 +1,181 @@
+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` 中的版本号。

drinkzen_admin_cli-0.2.4/README.md

@@ -0,0 +1,159 @@
+# 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` 中的版本号。

drinkzen_admin_cli-0.2.4/drinkzen_admin/__init__.py

@@ -0,0 +1,3 @@
+"""DrinkZen Admin CLI package."""
+
+__version__ = "0.2.4"