@newpeak/barista-cli 0.1.0

package/README.md

@@ -0,0 +1,707 @@
+# ☕ Barista CLI
+
+<p align="center">
+  <img src="https://img.shields.io/badge/AI--Native-CLI-blue?style=flat-square" alt="AI-Native">
+  <img src="https://img.shields.io/badge/Liberica-Production%20SaaS-green?style=flat-square" alt="Liberica">
+  <img src="https://img.shields.io/badge/Arabica-Sales%20Platform-orange?style=flat-square" alt="Arabica">
+  <img src="https://img.shields.io/badge/Node.js-18%2B-brightgreen?style=flat-square" alt="Node.js 18+">
+</p>
+
+<p align="center">
+  <strong>AI-Native CLI 工具</strong>，无缝桥接 Liberica 生产管理 SaaS 与 Arabica 销售平台
+</p>
+
+---
+
+## 📋 目录
+
+- [项目简介](#项目简介)
+- [快速开始](#快速开始)
+- [架构设计](#架构设计)
+- [命令文档](#命令文档)
+- [高级特性](#高级特性)
+- [配置说明](#配置说明)
+- [AI 集成](#AI-集成)
+- [开发指南](#开发指南)
+- [贡献指南](#贡献指南)
+
+---
+
+## 项目简介
+
+Barista CLI 是专为 Newpeak 生态系统设计的 AI-Native 命令行工具。它提供统一的接口来管理 Liberica 生产管理 SaaS 和 Arabica 销售平台。
+
+### 核心特性
+
+| 特性 | 说明 |
+|------|------|
+| 🌍 **多环境支持** | dev、test、prod-cn、prod-jp 四环境无缝切换 |
+| 🏢 **多租户架构** | 支持多租户环境配置与隔离 |
+| 🔐 **Token 认证** | 安全存储于系统密钥链，环境隔离 |
+| 🧪 **Dry-Run 模式** | 所有写入操作支持预览，避免误操作 |
+| 🤖 **AI 集成** | 为 Claude Code 优化的 JSON 输出格式 |
+| 🔄 **跨服务操作** | Liberica 与 Arabica 之间的数据同步 |
+
+### 适用场景
+
+- **生产计划管理**：创建、查询、取消生产订单
+- **产品数据管理**：跨平台搜索、同步产品信息
+- **客户操作**：查询客户信息、生成报价单
+- **AI 自动化**：通过 Claude Code 实现业务流程自动化
+
+---
+
+## 快速开始
+
+### 安装
+
+```bash
+# 通过 npm 安装
+npm install -g @newpeak/barista-cli
+
+# 或通过 yarn
+yarn global add @newpeak/barista-cli
+
+# 验证安装
+barista --version
+```
+
+### 初始化配置
+
+```bash
+# 1. 初始化配置目录
+barista init
+
+# 2. 配置环境（选择默认环境）
+barista context use-env dev
+
+# 3. 配置租户
+barista context use-tenant your-tenant
+
+# 4. 登录获取 Token
+barista auth login --service liberica --env dev
+
+# 5. 验证登录状态
+barista auth status
+```
+
+### 基本使用示例
+
+```bash
+# 查看当前上下文
+barista context show
+
+# 列出所有订单（Liberica）
+barista liberica orders list
+
+# 搜索产品（支持模糊查询）
+barista liberica products search --keyword "咖啡机"
+
+# 查看 Arabica 产品目录
+barista arabica products public-catalog
+
+# 创建生产订单（dry-run 模式预览）
+barista liberica orders create --product-id 123 --quantity 100 --dry-run
+```
+
+---
+
+## 架构设计
+
+### 环境映射
+
+#### Liberica（生产管理 SaaS）
+
+| 环境 | 域名格式 | 说明 |
+|------|----------|------|
+| dev | `{tenant}-dev.newpeaksh.com` | 开发环境 |
+| test | `{tenant}-test.newpeaksh.com` | 测试环境 |
+| prod-cn | `{tenant}.newpeaksh.com` | 中国生产环境 |
+| prod-jp | `{tenant}.newpeakjp.com` | 日本生产环境 |
+
+#### Arabica（销售平台）
+
+| 环境 | 域名 | 说明 |
+|------|------|------|
+| dev | `arabica-dev.newpeaksh.com` | 开发环境 |
+| test | `arabica-test.newpeaksh.com` | 测试环境 |
+| prod-cn | `www.newpeaksh.com` | 中国生产环境 |
+| prod-jp | `members.newpeakjp.com` | 日本生产环境 |
+
+### 认证机制
+
+Barista CLI 采用 Token-based 认证机制：
+
+```
+┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
+│   Barista CLI   │────▶│   Auth Server    │────▶│   API Servers   │
+│                 │     │                  │     │                 │
+│ • 登录请求      │     │ • 验证凭证       │     │ • 验证 Token    │
+│ • 存储 Token    │◀────│ • 签发 JWT       │◀────│ • 返回数据      │
+│   (系统密钥链)  │     │                  │     │                 │
+└─────────────────┘     └──────────────────┘     └─────────────────┘
+```
+
+**安全特性：**
+
+- **密钥链存储**：Token 安全存储于系统密钥链（macOS Keychain、Windows Credential、Linux Secret Service）
+- **自动跳过认证**：公开接口（如产品目录查询）无需认证
+- **环境隔离**：每个环境和租户使用独立的 Token，互不影响
+- **Token 刷新**：支持自动刷新即将过期的 Token
+
+---
+
+## 命令文档
+
+> **完整命令清单**: 所有命令的完整参考（包括已实现和待开发状态）请查看 [命令参考](./docs/commands/REFERENCE.md)。
+
+### 命令结构
+
+```
+barista <service> <resource> <action> [options]
+```
+
+**示例：**
+
+```bash
+barista liberica orders list --page 1 --size 20
+barista arabica quotes calculate --product-id 123 --quantity 10
+```
+
+### 全局选项
+
+| 选项 | 说明 | 示例 |
+|------|------|------|
+| `--env` | 指定环境 | `--env prod-cn` |
+| `--tenant` | 指定租户 | `--tenant electionjp` |
+| `--service` | 指定服务 | `--service liberica` |
+| `--dry-run` | 预览模式 | `--dry-run` |
+| `--json` | JSON 输出 | `--json` |
+| `--help` | 显示帮助 | `--help` |
+
+### 上下文管理
+
+上下文管理用于快速切换工作环境，避免每个命令都指定环境参数。
+
+```bash
+# 查看当前上下文
+barista context show
+
+# 输出示例：
+# ┌─────────────┬─────────────────┐
+# │ 属性        │ 值              │
+# ├─────────────┼─────────────────┤
+# │ 当前环境    │ dev             │
+# │ 当前租户    │ electionjp      │
+# │ 当前服务    │ liberica        │
+# │ Token 状态  │ 已登录          │
+# │ Token 过期  │ 2024-12-31      │
+# └─────────────┴─────────────────┘
+
+# 切换环境
+barista context use-env [dev|test|prod-cn|prod-jp]
+
+# 切换租户
+barista context use-tenant <tenant-name>
+
+# 切换默认服务
+barista context use-service [liberica|arabica]
+```
+
+### 认证管理
+
+```bash
+# 登录获取 Token
+barista auth login --service <service> --env <env> [--tenant <tenant>]
+
+# 示例：登录 Liberica 开发环境
+barista auth login --service liberica --env dev --tenant electionjp
+
+# 检查登录状态
+barista auth status
+
+# 输出示例：
+# ✓ Liberica (dev) - 已登录 (过期: 2024-12-31)
+# ✗ Liberica (test) - 未登录
+# ✓ Arabica (prod-cn) - 已登录 (过期: 2024-12-30)
+
+# 登出（清除 Token）
+barista auth logout --service <service> --env <env>
+
+# 登出所有环境
+barista auth logout --all
+```
+
+### Liberica 命令
+
+#### 订单管理
+
+```bash
+# 列出订单（分页）
+barista liberica orders list [--page <n>] [--size <n>] [--status <status>]
+
+# 获取单个订单详情
+barista liberica orders get <order-id>
+
+# 创建订单
+barista liberica orders create \
+  --product-id <id> \
+  --quantity <n> \
+  [--delivery-date <date>] \
+  [--note <text>]
+
+# 取消订单
+barista liberica orders cancel <order-id> [--reason <text>]
+```
+
+#### 产品管理
+
+```bash
+# 搜索产品
+barista liberica products search --keyword <keyword> [--category <id>]
+
+# 获取产品详情
+barista liberica products get <product-id>
+
+# 获取公开产品列表（无需认证）
+barista liberica products public-list [--category <id>] [--page <n>]
+```
+
+#### 生产计划
+
+```bash
+# 查看生产排期
+barista liberica production schedule [--start-date <date>] [--end-date <date>]
+
+# 重新排产
+barista liberica production reschedule <order-id> --new-date <date> [--dry-run]
+
+# 查询产能
+barista liberica production capacity [--date <date>] [--line <line-id>]
+```
+
+### Arabica 命令
+
+#### 产品管理
+
+```bash
+# 列出产品
+barista arabica products list [--page <n>] [--size <n>] [--category <id>]
+
+# 搜索产品
+barista arabica products search --keyword <keyword>
+
+# 获取产品目录（公开接口）
+barista arabica products public-catalog [--lang <zh|jp|en>]
+```
+
+#### 报价管理
+
+```bash
+# 计算报价
+barista arabica quotes calculate \
+  --product-id <id> \
+  --quantity <n> \
+  [--options <json>]
+
+# 创建报价单
+barista arabica quotes create \
+  --customer-id <id> \
+  --items <json> \
+  [--valid-days <n>]
+```
+
+#### 客户管理
+
+```bash
+# 搜索客户
+barista arabica customers search --keyword <keyword> [--type <type>]
+
+# 获取客户详情
+barista arabica customers get <customer-id>
+```
+
+### 跨服务命令
+
+跨服务命令实现 Liberica 与 Arabica 之间的数据同步和业务流程衔接。
+
+```bash
+# 从订单生成报价单
+barista cross quote-from-order <order-id> [--target-service arabica]
+
+# 输出示例：
+# ✓ 已生成报价单
+# ┌──────────┬────────────┐
+# │ 属性     │ 值         │
+# ├──────────┼────────────┤
+# │ 订单ID   │ 12345      │
+# │ 报价单ID │ QT-2024-001│
+# │ 金额     │ ¥50,000    │
+# │ 有效期   │ 30天       │
+# └──────────┴────────────┘
+
+# 同步订单状态到 Arabica
+barista cross sync-order <order-id> [--direction liberica-to-arabica]
+```
+
+---
+
+## 高级特性
+
+### Dry-Run 模式
+
+Dry-Run 模式允许你在执行写入操作前预览其影响，避免误操作。
+
+```bash
+# 所有写入操作都支持 --dry-run 选项
+barista liberica orders create --product-id 123 --quantity 100 --dry-run
+
+# 输出示例：
+# 🔍 Dry-Run 模式：操作不会被实际执行
+# ┌─────────────────┬──────────────────────┐
+# │ 操作            │ 创建订单             │
+# ├─────────────────┼──────────────────────┤
+# │ 产品            │ 咖啡机 Pro (ID: 123) │
+# │ 数量            │ 100                  │
+# │ 预计金额        │ ¥50,000              │
+# │ 预计交期        │ 2024-12-31           │
+# │ 影响            │ 新增一条订单记录     │
+# └─────────────────┴──────────────────────┘
+# 
+# ⚠️  确认执行？添加 --confirm 选项或移除 --dry-run
+```
+
+**默认 Dry-Run 的操作：**
+
+以下破坏性操作默认启用 Dry-Run 模式，需显式确认：
+
+- 取消订单
+- 删除产品
+- 批量更新
+
+### JSON 输出格式
+
+Barista CLI 支持 JSON 输出，便于脚本处理和 AI 集成：
+
+```bash
+barista liberica orders list --json
+
+# 输出示例：
+{
+  "success": true,
+  "data": {
+    "items": [
+      {
+        "id": "12345",
+        "productName": "咖啡机 Pro",
+        "quantity": 100,
+        "status": "in_production",
+        "createdAt": "2024-01-15T10:30:00Z"
+      }
+    ],
+    "pagination": {
+      "page": 1,
+      "size": 20,
+      "total": 150
+    }
+  }
+}
+```
+
+---
+
+## 配置说明
+
+### 配置文件
+
+配置文件位于 `~/.barista/config.yaml`：
+
+```yaml
+# Barista CLI 配置文件
+
+# 默认上下文设置
+defaults:
+  env: dev
+  tenant: electionjp
+  service: liberica
+
+# 环境配置
+environments:
+  dev:
+    liberica:
+      baseUrl: "https://{tenant}-dev.newpeaksh.com"
+      timeout: 30000
+    arabica:
+      baseUrl: "https://arabica-dev.newpeaksh.com"
+      timeout: 30000
+  
+  test:
+    liberica:
+      baseUrl: "https://{tenant}-test.newpeaksh.com"
+      timeout: 30000
+    arabica:
+      baseUrl: "https://arabica-test.newpeaksh.com"
+      timeout: 30000
+  
+  prod-cn:
+    liberica:
+      baseUrl: "https://{tenant}.newpeaksh.com"
+      timeout: 60000
+    arabica:
+      baseUrl: "https://www.newpeaksh.com"
+      timeout: 60000
+  
+  prod-jp:
+    liberica:
+      baseUrl: "https://{tenant}.newpeakjp.com"
+      timeout: 60000
+    arabica:
+      baseUrl: "https://members.newpeakjp.com"
+      timeout: 60000
+
+# 输出配置
+output:
+  format: table  # table | json
+  color: true
+  timestamp: true
+```
+
+### 多租户配置
+
+支持配置多个租户，快速切换：
+
+```bash
+# 添加租户配置
+barista config add-tenant \
+  --name customer-a \
+  --liberica-id customer-a-id \
+  --arabica-id customer-a-arabica-id
+
+# 列出已配置租户
+barista config list-tenants
+
+# 快速切换租户
+barista context use-tenant customer-a
+```
+
+---
+
+## AI 集成
+
+Barista CLI 专为 AI 编程助手优化，特别是 Claude Code。
+
+### Claude Code 使用示例
+
+```typescript
+// 在 Claude Code 中使用 Barista CLI
+// 示例：获取订单列表并分析
+
+const result = await $`barista liberica orders list --json --page 1 --size 10`;
+const orders = JSON.parse(result.stdout);
+
+// 分析订单数据
+const analysis = orders.data.items.map(order => ({
+  id: order.id,
+  status: order.status,
+  amount: order.amount
+}));
+```
+
+### Skills 文件
+
+Barista CLI 提供 Claude Code Skills 文件，位于：
+
+```
+~/.barista/claude/skills/
+├── orders.md       # 订单管理技能
+├── products.md     # 产品管理技能
+├── quotes.md       # 报价管理技能
+└── customers.md    # 客户管理技能
+```
+
+**示例 Skills 文件：**
+
+```markdown
+# 订单管理技能
+
+## 列出待处理订单
+
+当用户询问待处理订单时：
+
+1. 执行命令：barista liberica orders list --status pending --json
+2. 解析返回的 JSON
+3. 总结订单数量和总金额
+4. 列出前 5 个订单的关键信息
+
+## 创建新订单
+
+当用户需要创建订单时：
+
+1. 确认产品 ID 和数量
+2. 使用 dry-run 预览：barista liberica orders create --dry-run ...
+3. 用户确认后执行实际命令
+```
+
+### AI 友好的输出
+
+所有命令都支持 `--json` 选项，返回结构化的 JSON 数据：
+
+```bash
+# 查询带结构化输出
+barista liberica orders get 12345 --json
+
+{
+  "success": true,
+  "data": {
+    "id": "12345",
+    "status": "in_production",
+    "product": {
+      "id": "100",
+      "name": "咖啡机 Pro"
+    },
+    "quantity": 100,
+    "amount": 50000,
+    "timeline": {
+      "created": "2024-01-15T10:30:00Z",
+      "delivery": "2024-02-15"
+    }
+  },
+  "meta": {
+    "requestId": "req-abc123",
+    "timestamp": "2024-01-15T10:30:00Z"
+  }
+}
+```
+
+---
+
+## 开发指南
+
+### 项目结构
+
+```
+coffee-barista-cli/
+├── bin/
+│   └── barista.js              # 入口文件
+├── src/
+│   ├── commands/               # 命令实现
+│   │   ├── context/            # 上下文管理命令
+│   │   ├── auth/               # 认证命令
+│   │   ├── liberica/           # Liberica 服务命令
+│   │   │   ├── orders.js
+│   │   │   ├── products.js
+│   │   │   └── production.js
+│   │   ├── arabica/            # Arabica 服务命令
+│   │   │   ├── products.js
+│   │   │   ├── quotes.js
+│   │   │   └── customers.js
+│   │   └── cross/              # 跨服务命令
+│   ├── core/                   # 核心模块
+│   │   ├── auth.js             # 认证管理
+│   │   ├── config.js           # 配置管理
+│   │   ├── context.js          # 上下文管理
+│   │   └── api-client.js       # API 客户端
+│   ├── utils/                  # 工具函数
+│   │   ├── formatter.js        # 输出格式化
+│   │   ├── validator.js        # 参数验证
+│   │   └── keychain.js         # 密钥链操作
+│   └── templates/              # 模板文件
+├── skills/                     # Claude Code Skills
+├── tests/                      # 测试文件
+├── package.json
+└── README.md
+```
+
+### 本地开发
+
+```bash
+# 1. 克隆仓库
+git clone https://gitlab.newpeaksh.com/coffee/coffee-barista-cli.git
+cd coffee-barista-cli
+
+# 2. 安装依赖
+npm install
+
+# 3. 链接到全局（开发模式）
+npm link
+
+# 4. 验证链接
+barista --version
+
+# 5. 运行测试
+npm test
+
+# 6. 代码检查
+npm run lint
+```
+
+### 添加新命令
+
+**重要**：新增命令必须遵循 [命令设计规范](./docs/COMMAND_DESIGN_SPEC.md)，包含设计文档编写、技术评审等完整流程。
+
+详细步骤请参考：
+- [完整命令参考](./docs/commands/REFERENCE.md) - 所有命令清单和开发优先级
+- [命令设计规范文档](./docs/COMMAND_DESIGN_SPEC.md#5-命令开发流程规范)
+- [命令开发指南](./docs/COMMANDS.md)
+
+---
+
+## 贡献指南
+
+我们欢迎所有形式的贡献，包括但不限于：
+
+- 🐛 报告 Bug
+- 💡 提出新功能建议
+- 📝 改进文档
+- 🔧 提交代码修复
+- ✨ 添加新功能
+
+### 提交规范
+
+请遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范：
+
+```bash
+# 修复 Bug
+fix: 修复订单列表分页问题
+
+# 添加功能
+feat: 添加库存查询命令
+
+# 文档更新
+docs: 更新 README 中的环境映射
+
+# 代码重构
+refactor: 重构 API 客户端错误处理
+```
+
+### 开发流程
+
+1. Fork 本仓库
+2. 创建功能分支：`git checkout -b feature/my-feature`
+3. 提交更改：`git commit -m 'feat: add some feature'`
+4. 推送分支：`git push origin feature/my-feature`
+5. 创建 Pull Request
+
+---
+
+## 相关项目
+
+| 项目 | 描述 | 链接 |
+|------|------|------|
+| ☕ Liberica Backend | 生产管理 SaaS 后端 | [coffee-liberica-end](https://gitlab.newpeaksh.com/coffee/coffee-liberica-end) |
+| 🖥️ Liberica Frontend | 生产管理 Web 前端 | [coffee-liberica-front](https://gitlab.newpeaksh.com/coffee/coffee-liberica-front) |
+| 📱 Liberica Mobile | 生产管理移动端 | [coffee-liberica-mobile-front](https://gitlab.newpeaksh.com/coffee/coffee-liberica-mobile-front) |
+| 🛒 Arabica Backend | 销售平台后端 | [coffee-arabica-end](https://gitlab.newpeaksh.com/coffee/coffee-arabica-end) |
+| 🌐 Arabica Frontend | 销售平台前端 | [coffee-arabica-front](https://gitlab.newpeaksh.com/coffee/coffee-arabica-front) |
+
+---
+
+## 许可证
+
+[MIT](LICENSE) © Newpeak Technology
+
+---
+
+<p align="center">
+  用 ☕ 驱动生产力
+</p>

package/bin/barista

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+import('../dist/index.js').catch((err) => {
+  console.error('Failed to start CLI:', err);
+  process.exit(1);
+});

package/bin/barista.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import '../dist/index.js';