@newpeak/barista-cli 0.1.5 → 0.1.7

package/README.ja.md

@@ -0,0 +1,708 @@
+# ☕ Barista CLI
+
+<p align="center">
+  <a href="./README.md"><img src="https://img.shields.io/badge/-简体中文-green?style=flat-square" alt="简体中文"></a>
+  <a href="./README.en.md"><img src="https://img.shields.io/badge/-English-blue?style=flat-square" alt="English"></a>
+  <a href="./README.ja.md"><img src="https://img.shields.io/badge/-日本語-red?style=flat-square" alt="日本語"></a>
+  <a href="./README.vi.md"><img src="https://img.shields.io/badge/-Tiếng%20Việt-green?style=flat-square" alt="Tiếng Việt"></a>
+</p>
+
+<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 の4環境をシームレスに切り替え |
+| 🏢 **マルチテナントアーキテクチャ** | マルチテナント環境設定と分離をサポート |
+| 🔐 **トークン認証** | システムキーチェーンに安全に保存、環境分離 |
+| 🧪 **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. ログインしてトークンを取得
+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 はトークンベースの認証メカニズムを採用しています：
+
+```
+┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
+│   Barista CLI   │────▶│   Auth Server    │────▶│   API Servers   │
+│                 │     │                  │     │                 │
+│ • ログイン要求  │     │ • 認証情報確認   │     │ • トークン確認  │
+│ • トークン保存  │◀────│ • JWT 発行       │◀────│ • データ返却    │
+│   (キーチェーン)│     │                  │     │                 │
+└─────────────────┘     └──────────────────┘     └─────────────────┘
+```
+
+**セキュリティ機能：**
+
+- **キーチェーン保存**: トークンはシステムキーチェーン（macOS Keychain、Windows Credential、Linux Secret Service）に安全に保存
+- **自動認証スキップ**: 公開インターフェース（製品カタログ照会など）は認証不要
+- **環境分離**: 各環境とテナントは独立したトークンを使用、相互に影響なし
+- **トークン更新**: 有効期限が近づいたトークンの自動更新をサポート
+
+---
+
+## コマンドドキュメント
+
+> **完全なコマンドリファレンス**: すべてのコマンド（実装済みおよび開発予定）の完全なリファレンスは [コマンドリファレンス](./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      │
+# │ トークン状態│ ログイン済み    │
+# │ トークン有効期限│ 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
+# ログインしてトークンを取得
+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)
+
+# ログアウト（トークンをクリア）
+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           │
+# │ 影響            │ オーダーレコードを1件追加 │
+# └─────────────────┴──────────────────────┘
+# 
+# ⚠️  実行を確認？--confirm オプションを追加するか --dry-run を削除してください
+```
+
+**デフォルトで Dry-Run の操作：**
+
+以下の破壊的な操作はデフォルトで Dry-Run モードが有効で、明示的な確認が必要です：
+
+- オーダーキャンセル
+- 製品削除
+- バッチ更新
+
+### JSON 出力形式
+
+Barista CLI はスクリプト処理と AI 統合のために JSON 出力をサポートしています：
+
+```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)
+
+---
+
+## 貢献ガイド
+
+バグ報告、新機能の提案、ドキュメントの改善、コード修正、新機能の追加など、あらゆる形態の貢献を歓迎します。
+
+### コミット規約
+
+[Conventional Commits](https://www.conventionalcommits.org/) 仕様に従ってください：
+
+```bash
+# バグ修正
+fix: オーダーリストのページング問題を修正
+
+# 機能追加
+feat: 在庫照会コマンドを追加
+
+# ドキュメント更新
+docs: README の環境マッピングを更新
+
+# コードリファクタリング
+refactor: API クライアントのエラー処理をリファクタリング
+```
+
+### 開発フロー
+
+1. このリポジトリをフォーク
+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>