@newpeak/barista-cli 0.1.19 → 0.1.21

package/README.vi.md

@@ -1,340 +1,340 @@
-# ☕ Barista CLI
-
-> **Để AI assistants điều khiển hệ thống quản lý sản xuất** — Kết nối AI tools (Claude Code, OpenCode, OpenClaw) với SaaS doanh nghiệp
-
-[![npm version](https://img.shields.io/npm/v/@newpeak/barista-cli.svg?style=flat-square)](https://www.npmjs.com/package/@newpeak/barista-cli)
-[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg?style=flat-square)](LICENSE)
-[![Weekly Downloads](https://img.shields.io/npm/dw/@newpeak/barista-cli?style=flat-square)](https://www.npmjs.com/package/@newpeak/barista-cli)
-[![Node.js](https://img.shields.io/badge/Node.js-18%2B-brightgreen?style=flat-square)](https://nodejs.org/)
-
----
-
-## ⚡ Khởi Đầu Nhanh
-
-### 1. Cài Đặt
-
-```bash
-npm install -g @newpeak/barista-cli
-```
-
-### 2. Xác Thực
-
-```bash
-# AI cần credentials để hoạt động thay mặt người dùng
-barista liberica auth login prod-cn your-tenant your-username your-password
-
-# Đăng nhập tương tác (nhắc nhập thông tin còn thiếu)
-barista liberica auth login
-```
-
-### 3. Tích Hợp AI
-
-```typescript
-// Trong Claude Code / OpenCode / OpenClaw:
-const orders = await $`barista liberica orders list --env prod-cn --tenant your-tenant --json`
-const { success, data } = JSON.parse(orders.stdout)
-
-// AI phân tích và xử lý dữ liệu
-if (data.items.length > 0) {
-  console.log(`Found ${data.pagination.total} orders`)
-}
-```
-
-**[Xem ví dụ tích hợp AI →](#ai-integration)**
-
----
-
-## 🤖 Tích Hợp AI
-
-Barista CLI được thiết kế cho AI coding assistants. Mọi đầu ra đều có cấu trúc, mọi lỗi đều có thể xử lý.
-
-### Các AI Tools Được Hỗ Trợ
-
-| AI Tool | Phương Thức Tích Hợp | Trạng Thái |
-|---------|----------------------|------------|
-| **Claude Code** | `$` backticks + `--json` | ✅ Đã xác minh |
-| **OpenCode** | Shell command + JSON parse | ✅ Đã xác minh |
-| **OpenClaw** | Shell command + JSON parse | ✅ Đã xác minh |
-| **Cursor** | Terminal integration | ✅ Tương thích |
-| **Continue** | CLI subprocess | ✅ Tương thích |
-
-### Mẫu Tích Hợp
-
-```typescript
-// 1. Thực thi lệnh với đầu ra JSON
-const result = await $`barista liberica orders list \
-  --env prod-cn \
-  --tenant your-tenant \
-  --status pending \
-  --json \
-  --page 1 \
-  --size 50`
-
-// 2. Phân tích phản hồi có cấu trúc
-const { success, data, meta } = JSON.parse(result.stdout)
-
-if (!success) {
-  throw new Error(`API Error: ${meta.code || meta.error?.code} - ${meta.message || meta.error?.message}`)
-}
-
-// 3. Xử lý dữ liệu
-const pendingOrders = data.items
-console.log(`Found ${data.pagination.total} pending orders`)
-
-// 4. Thực thi thao tác an toàn
-for (const order of pendingOrders) {
-  // Luôn chạy dry-run trước (an toàn cho AI)
-  const preview = await $`barista liberica orders cancel ${order.id} --dry-run`
-
-  // Phân tích preview, xác minh, rồi thực thi với --force
-  // ...
-}
-```
-
-### Response Envelope
-
-Tất cả phản hồi JSON đều theo cấu trúc này:
-
-```json
-{
-  "success": true,
-  "data": {
-    "items": [...],
-    "pagination": { "page": 1, "size": 20, "total": 150 }
-  },
-  "meta": {
-    "requestId": "req-abc123",
-    "timestamp": "2024-01-15T10:30:00Z",
-    "environment": "prod-cn",
-    "tenant": "your-tenant"
-  }
-}
-```
-
-**Định dạng lỗi:**
-
-```json
-{
-  "success": false,
-  "error": {
-    "code": "A150001",
-    "message": "Order not found"
-  },
-  "meta": {
-    "requestId": "req-xyz789",
-    "timestamp": "2024-01-15T10:30:00Z"
-  }
-}
-```
-
-### Skills cho Claude Code
-
-Cài đặt các file skill có thể tái sử dụng:
-
-```bash
-# Skills nằm tại ~/.barista/claude/skills/
-barista skills install
-```
-
-**Các skills có sẵn:**
-- `orders.md` — Quy trình quản lý đơn hàng
-- `products.md` — Tìm kiếm và đồng bộ sản phẩm
-- `warehouses.md` — Thao tác kho hàng
-- `subscriptions.md` — Quản lý đăng ký Arabica
-
----
-
-## 🚀 Tính Năng
-
-### Thiết Kế AI-First
-
-| Tính Năng | Mô Tả |
-|-----------|--------|
-| 🤖 **JSON-First Output** | Tất cả lệnh hỗ trợ `--json` để AI phân tích |
-| 📦 **Structured Responses** | Cấu trúc nhất quán `{success, data, meta}` |
-| 🔄 **Idempotent Operations** | An toàn cho AI retry loops |
-| 🛡️ **Dry-Run by Default** | Xem trước các thao tác nguy hiểm trước khi thực thi |
-| 🔐 **Secure Storage** | Credentials lưu trong system keychain, không phải env vars |
-
-### Kết Nối Doanh Nghiệp
-
-| Dịch Vụ | Khả Năng |
-|---------|----------|
-| ☕ **Liberica** | Đơn hàng, sản phẩm, tồn kho, kho hàng, lập kế hoạch sản xuất |
-| 🛒 **Arabica** | Gói đăng ký, thanh toán, hóa đơn, quản lý doanh nghiệp |
-| 🔗 **Cross-Service** | Báo giá từ đơn hàng, đồng bộ giữa các hệ thống |
-
-### An Toàn Vận Hành
-
-- 📊 **Audit Trail** — Mỗi thao tác được ghi log với request ID
-- ⚠️ **Confirmation Guards** — `--dry-run` / `--force` cho các thao tác ghi
-- 🏢 **Multi-Tenant Isolation** — Credentials được cô lập theo từng tenant
-
----
-
-## 🔧 Tham Khảo Lệnh
-
-### Mẫu Cơ Bản
-
-```
-barista <service> <resource> <action> [options]
-```
-
-### Các Tùy Chọn Toàn Cục
-
-| Tùy Chọn | Mô Tả | Mặc Định |
-|----------|--------|----------|
-| `--env` | Môi trường (dev\|test\|prod-cn\|prod-jp) | `dev` |
-| `--tenant` | Tên tenant | - |
-| `--json` | Đầu ra JSON | `false` |
-| `--dry-run` | Chế độ xem trước (khuyến nghị cho AI) | `false` |
-| `--force` | Bỏ qua xác nhận | `false` |
-| `--page` | Số trang | `1` |
-| `--size` | Kích thước trang (tối đa) | `20` |
-
-### Tham Khảo Nhanh
-
-| Lệnh | Mô Tả |
-|------|--------|
-| `barista context show` | Hiển thị context env/tenant hiện tại |
-| `barista context use-env <env>` | Chuyển đổi môi trường |
-| `barista liberica orders list --json` | Liệt kê đơn hàng (định dạng AI) |
-| `barista liberica orders get <id> --json` | Xem chi tiết đơn hàng |
-| `barista liberica orders create --dry-run ...` | Xem trước tạo mới |
-| `barista liberica products search --keyword <kw> --json` | Tìm kiếm sản phẩm |
-| `barista arabica plans list --json` | Liệt kê gói đăng ký |
-| `barista arabica invoices list --json` | Liệt kê hóa đơn |
-
-**[→ Tham Khảo Lệnh Chi Tiết](./docs/commands/REFERENCE.md)**
-
----
-
-## 🛡️ Hướng Dẫn An Toàn AI
-
-### 1. Luôn Chạy Dry-Run Trước
-
-```typescript
-// ❌ Sai — Thực thi mù quáng
-await $`barista liberica orders cancel 12345`
-
-// ✅ Đúng — Xem trước trước
-const preview = await $`barista liberica orders cancel 12345 --dry-run`
-// Phân tích preview, xác minh, rồi:
-await $`barista liberica orders cancel 12345 --force`
-```
-
-### 2. Kiểm Tra Success Trước Khi Tiếp Tục
-
-```typescript
-const result = JSON.parse(stdout)
-if (!result.success) {
-  // Xử lý lỗi, không tiếp tục
-  throw new Error(result.error?.message || result.meta?.message)
-}
-```
-
-### 3. Sử Dụng Request ID Để Debug
-
-```typescript
-const { meta } = JSON.parse(stdout)
-console.log(`Request ID: ${meta.requestId}`)
-```
-
-### 4. Tuân Thủ Rate Limits
-
-- Thêm độ trễ giữa các thao tác hàng loạt
-- Sử dụng `--size 100` cho fetch hàng loạt
-- Cache responses khi phù hợp
-
----
-
-## ⚙️ Cấu Hình
-
-### Vị Trí File
-
-`~/.barista/config.yaml`
-
-### Cấu Hình Nhanh
-
-```yaml
-defaults:
-  env: prod-cn
-  tenant: your-tenant
-  service: liberica
-
-environments:
-  prod-cn:
-    liberica:
-      baseUrl: "https://{tenant}.newpeaksh.com"
-      timeout: 60000
-    arabica:
-      baseUrl: "https://www.newpeaksh.com"
-      timeout: 60000
-```
-
-### Xác Thực
-
-```bash
-# Đăng nhập bằng credentials (khuyến nghị)
-barista liberica auth login <env> <tenant> <username> <password>
-
-# Kiểm tra trạng thái đăng nhập
-barista auth status
-
-# Đăng xuất
-barista auth logout --service liberica --env prod-cn
-```
-
----
-
-## ❓ Xử Lý Sự Cố
-
-### Lỗi Xác Thực
-
-```bash
-# Kiểm tra trạng thái hiện tại
-barista auth status
-
-# Đăng nhập lại
-barista liberica auth login prod-cn your-tenant your-username your-password
-
-# Kiểm tra context
-barista context show
-```
-
-### Lỗi API
-
-```bash
-# Luôn sử dụng --json để nhận mã lỗi
-barista liberica orders list --json
-
-# Phản hồi lỗi bao gồm requestId để debug
-# "requestId": "req-abc123"
-```
-
-### Vấn Đề Timeout
-
-```bash
-# Chuyển sang môi trường gần hơn
-barista context use-env dev
-
-# Hoặc điều chỉnh timeout trong config.yaml
-```
-
----
-
-## 📚 Các Dự Án Liên Quan
-
-| Dự Án | Mô Tả |
-|--------|--------|
-| ☕ Liberica Backend | SaaS backend quản lý sản xuất |
-| 🖥️ Liberica Frontend | Web UI quản lý sản xuất |
-| 📱 Liberica Mobile | Ứng dụng di động quản lý sản xuất |
-| 🛒 Arabica Backend | SaaS backend đăng ký trực tuyến |
-| 🌐 Arabica Frontend | Web UI đăng ký trực tuyến |
-
----
-
-## 📄 Giấy Phép
-
-[MIT](LICENSE) © Newpeak Technology
+# ☕ Barista CLI
+
+> **Để AI assistants điều khiển hệ thống quản lý sản xuất** — Kết nối AI tools (Claude Code, OpenCode, OpenClaw) với SaaS doanh nghiệp
+
+[![npm version](https://img.shields.io/npm/v/@newpeak/barista-cli.svg?style=flat-square)](https://www.npmjs.com/package/@newpeak/barista-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg?style=flat-square)](LICENSE)
+[![Weekly Downloads](https://img.shields.io/npm/dw/@newpeak/barista-cli?style=flat-square)](https://www.npmjs.com/package/@newpeak/barista-cli)
+[![Node.js](https://img.shields.io/badge/Node.js-18%2B-brightgreen?style=flat-square)](https://nodejs.org/)
+
+---
+
+## ⚡ Khởi Đầu Nhanh
+
+### 1. Cài Đặt
+
+```bash
+npm install -g @newpeak/barista-cli
+```
+
+### 2. Xác Thực
+
+```bash
+# AI cần credentials để hoạt động thay mặt người dùng
+barista liberica auth login prod-cn your-tenant your-username your-password
+
+# Đăng nhập tương tác (nhắc nhập thông tin còn thiếu)
+barista liberica auth login
+```
+
+### 3. Tích Hợp AI
+
+```typescript
+// Trong Claude Code / OpenCode / OpenClaw:
+const orders = await $`barista liberica orders list --env prod-cn --tenant your-tenant --json`
+const { success, data } = JSON.parse(orders.stdout)
+
+// AI phân tích và xử lý dữ liệu
+if (data.items.length > 0) {
+  console.log(`Found ${data.pagination.total} orders`)
+}
+```
+
+**[Xem ví dụ tích hợp AI →](#ai-integration)**
+
+---
+
+## 🤖 Tích Hợp AI
+
+Barista CLI được thiết kế cho AI coding assistants. Mọi đầu ra đều có cấu trúc, mọi lỗi đều có thể xử lý.
+
+### Các AI Tools Được Hỗ Trợ
+
+| AI Tool | Phương Thức Tích Hợp | Trạng Thái |
+|---------|----------------------|------------|
+| **Claude Code** | `$` backticks + `--json` | ✅ Đã xác minh |
+| **OpenCode** | Shell command + JSON parse | ✅ Đã xác minh |
+| **OpenClaw** | Shell command + JSON parse | ✅ Đã xác minh |
+| **Cursor** | Terminal integration | ✅ Tương thích |
+| **Continue** | CLI subprocess | ✅ Tương thích |
+
+### Mẫu Tích Hợp
+
+```typescript
+// 1. Thực thi lệnh với đầu ra JSON
+const result = await $`barista liberica orders list \
+  --env prod-cn \
+  --tenant your-tenant \
+  --status pending \
+  --json \
+  --page 1 \
+  --size 50`
+
+// 2. Phân tích phản hồi có cấu trúc
+const { success, data, meta } = JSON.parse(result.stdout)
+
+if (!success) {
+  throw new Error(`API Error: ${meta.code || meta.error?.code} - ${meta.message || meta.error?.message}`)
+}
+
+// 3. Xử lý dữ liệu
+const pendingOrders = data.items
+console.log(`Found ${data.pagination.total} pending orders`)
+
+// 4. Thực thi thao tác an toàn
+for (const order of pendingOrders) {
+  // Luôn chạy dry-run trước (an toàn cho AI)
+  const preview = await $`barista liberica orders cancel ${order.id} --dry-run`
+
+  // Phân tích preview, xác minh, rồi thực thi với --force
+  // ...
+}
+```
+
+### Response Envelope
+
+Tất cả phản hồi JSON đều theo cấu trúc này:
+
+```json
+{
+  "success": true,
+  "data": {
+    "items": [...],
+    "pagination": { "page": 1, "size": 20, "total": 150 }
+  },
+  "meta": {
+    "requestId": "req-abc123",
+    "timestamp": "2024-01-15T10:30:00Z",
+    "environment": "prod-cn",
+    "tenant": "your-tenant"
+  }
+}
+```
+
+**Định dạng lỗi:**
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "A150001",
+    "message": "Order not found"
+  },
+  "meta": {
+    "requestId": "req-xyz789",
+    "timestamp": "2024-01-15T10:30:00Z"
+  }
+}
+```
+
+### Skills cho Claude Code
+
+Cài đặt các file skill có thể tái sử dụng:
+
+```bash
+# Skills nằm tại ~/.barista/claude/skills/
+barista skills install
+```
+
+**Các skills có sẵn:**
+- `orders.md` — Quy trình quản lý đơn hàng
+- `products.md` — Tìm kiếm và đồng bộ sản phẩm
+- `warehouses.md` — Thao tác kho hàng
+- `subscriptions.md` — Quản lý đăng ký Arabica
+
+---
+
+## 🚀 Tính Năng
+
+### Thiết Kế AI-First
+
+| Tính Năng | Mô Tả |
+|-----------|--------|
+| 🤖 **JSON-First Output** | Tất cả lệnh hỗ trợ `--json` để AI phân tích |
+| 📦 **Structured Responses** | Cấu trúc nhất quán `{success, data, meta}` |
+| 🔄 **Idempotent Operations** | An toàn cho AI retry loops |
+| 🛡️ **Dry-Run by Default** | Xem trước các thao tác nguy hiểm trước khi thực thi |
+| 🔐 **Secure Storage** | Credentials lưu trong system keychain, không phải env vars |
+
+### Kết Nối Doanh Nghiệp
+
+| Dịch Vụ | Khả Năng |
+|---------|----------|
+| ☕ **Liberica** | Đơn hàng, sản phẩm, tồn kho, kho hàng, lập kế hoạch sản xuất |
+| 🛒 **Arabica** | Gói đăng ký, thanh toán, hóa đơn, quản lý doanh nghiệp |
+| 🔗 **Cross-Service** | Báo giá từ đơn hàng, đồng bộ giữa các hệ thống |
+
+### An Toàn Vận Hành
+
+- 📊 **Audit Trail** — Mỗi thao tác được ghi log với request ID
+- ⚠️ **Confirmation Guards** — `--dry-run` / `--force` cho các thao tác ghi
+- 🏢 **Multi-Tenant Isolation** — Credentials được cô lập theo từng tenant
+
+---
+
+## 🔧 Tham Khảo Lệnh
+
+### Mẫu Cơ Bản
+
+```
+barista <service> <resource> <action> [options]
+```
+
+### Các Tùy Chọn Toàn Cục
+
+| Tùy Chọn | Mô Tả | Mặc Định |
+|----------|--------|----------|
+| `--env` | Môi trường (dev\|test\|prod-cn\|prod-jp) | `dev` |
+| `--tenant` | Tên tenant | - |
+| `--json` | Đầu ra JSON | `false` |
+| `--dry-run` | Chế độ xem trước (khuyến nghị cho AI) | `false` |
+| `--force` | Bỏ qua xác nhận | `false` |
+| `--page` | Số trang | `1` |
+| `--size` | Kích thước trang (tối đa) | `20` |
+
+### Tham Khảo Nhanh
+
+| Lệnh | Mô Tả |
+|------|--------|
+| `barista context show` | Hiển thị context env/tenant hiện tại |
+| `barista context use-env <env>` | Chuyển đổi môi trường |
+| `barista liberica orders list --json` | Liệt kê đơn hàng (định dạng AI) |
+| `barista liberica orders get <id> --json` | Xem chi tiết đơn hàng |
+| `barista liberica orders create --dry-run ...` | Xem trước tạo mới |
+| `barista liberica products search --keyword <kw> --json` | Tìm kiếm sản phẩm |
+| `barista arabica plans list --json` | Liệt kê gói đăng ký |
+| `barista arabica invoices list --json` | Liệt kê hóa đơn |
+
+**[→ Tham Khảo Lệnh Chi Tiết](./docs/commands/REFERENCE.md)**
+
+---
+
+## 🛡️ Hướng Dẫn An Toàn AI
+
+### 1. Luôn Chạy Dry-Run Trước
+
+```typescript
+// ❌ Sai — Thực thi mù quáng
+await $`barista liberica orders cancel 12345`
+
+// ✅ Đúng — Xem trước trước
+const preview = await $`barista liberica orders cancel 12345 --dry-run`
+// Phân tích preview, xác minh, rồi:
+await $`barista liberica orders cancel 12345 --force`
+```
+
+### 2. Kiểm Tra Success Trước Khi Tiếp Tục
+
+```typescript
+const result = JSON.parse(stdout)
+if (!result.success) {
+  // Xử lý lỗi, không tiếp tục
+  throw new Error(result.error?.message || result.meta?.message)
+}
+```
+
+### 3. Sử Dụng Request ID Để Debug
+
+```typescript
+const { meta } = JSON.parse(stdout)
+console.log(`Request ID: ${meta.requestId}`)
+```
+
+### 4. Tuân Thủ Rate Limits
+
+- Thêm độ trễ giữa các thao tác hàng loạt
+- Sử dụng `--size 100` cho fetch hàng loạt
+- Cache responses khi phù hợp
+
+---
+
+## ⚙️ Cấu Hình
+
+### Vị Trí File
+
+`~/.barista/config.yaml`
+
+### Cấu Hình Nhanh
+
+```yaml
+defaults:
+  env: prod-cn
+  tenant: your-tenant
+  service: liberica
+
+environments:
+  prod-cn:
+    liberica:
+      baseUrl: "https://{tenant}.newpeaksh.com"
+      timeout: 60000
+    arabica:
+      baseUrl: "https://www.newpeaksh.com"
+      timeout: 60000
+```
+
+### Xác Thực
+
+```bash
+# Đăng nhập bằng credentials (khuyến nghị)
+barista liberica auth login <env> <tenant> <username> <password>
+
+# Kiểm tra trạng thái đăng nhập
+barista auth status
+
+# Đăng xuất
+barista auth logout --service liberica --env prod-cn
+```
+
+---
+
+## ❓ Xử Lý Sự Cố
+
+### Lỗi Xác Thực
+
+```bash
+# Kiểm tra trạng thái hiện tại
+barista auth status
+
+# Đăng nhập lại
+barista liberica auth login prod-cn your-tenant your-username your-password
+
+# Kiểm tra context
+barista context show
+```
+
+### Lỗi API
+
+```bash
+# Luôn sử dụng --json để nhận mã lỗi
+barista liberica orders list --json
+
+# Phản hồi lỗi bao gồm requestId để debug
+# "requestId": "req-abc123"
+```
+
+### Vấn Đề Timeout
+
+```bash
+# Chuyển sang môi trường gần hơn
+barista context use-env dev
+
+# Hoặc điều chỉnh timeout trong config.yaml
+```
+
+---
+
+## 📚 Các Dự Án Liên Quan
+
+| Dự Án | Mô Tả |
+|--------|--------|
+| ☕ Liberica Backend | SaaS backend quản lý sản xuất |
+| 🖥️ Liberica Frontend | Web UI quản lý sản xuất |
+| 📱 Liberica Mobile | Ứng dụng di động quản lý sản xuất |
+| 🛒 Arabica Backend | SaaS backend đăng ký trực tuyến |
+| 🌐 Arabica Frontend | Web UI đăng ký trực tuyến |
+
+---
+
+## 📄 Giấy Phép
+
+[MIT](LICENSE) © Newpeak Technology