@newpeak/barista-cli 0.1.15 → 0.1.17

package/README.vi.md

@@ -1,498 +1,268 @@
 # ☕ 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>Công cụ CLI AI-Native</strong> - Kết nối liền mạch giữa Liberica SaaS Quản lý Sản xuất và Nền tảng Bán hàng Arabica
-</p>
+> **Để 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
 
----
-
-## 📋 Mục lục
-
-- [Giới thiệu Dự án](#giới-thiệu-dự-án)
-- [Bắt đầu Nhanh](#bắt-đầu-nhanh)
-- [Thiết kế Kiến trúc](#thiết-kế-kiến-trúc)
-- [Tài liệu Lệnh](#tài-liệu-lệnh)
-- [Tính năng Nâng cao](#tính-năng-nâng-cao)
-- [Cấu hình](#cấu-hình)
-- [Tích hợp AI](#tích-hợp-ai)
-- [Hướng dẫn Phát triển](#hướng-dẫn-phát-triển)
-- [Hướng dẫn Đóng góp](#hướng-dẫn-đóng-góp)
-
----
-
-## Giới thiệu Dự án
-
-Barista CLI là công cụ dòng lệnh AI-Native được thiết kế đặc biệt cho hệ sinh thái Newpeak. Nó cung cấp giao diện thống nhất để quản lý Liberica SaaS Quản lý Sản xuất và Nền tảng Bán hàng Arabica.
-
-### Tính năng Cốt lõi
-
-| Tính năng | Mô tả |
-|-----------|-------|
-| 🌍 **Hỗ trợ Đa Môi trường** | Chuyển đổi liền mạch giữa 4 môi trường dev, test, prod-cn, và prod-jp |
-| 🏢 **Kiến trúc Đa Ngưới thuê** | Hỗ trợ cấu hình và cách ly môi trường đa ngưới thuê |
-| 🔐 **Xác thực Token** | Lưu trữ an toàn trong chuỗi khóa hệ thống, cách ly môi trường |
-| 🧪 **Chế độ Dry-Run** | Tất cả thao tác ghi đều hỗ trợ xem trước để tránh lỗi |
-| 🤖 **Tích hợp AI** | Định dạng đầu ra JSON được tối ưu hóa cho Claude Code |
-| 🔄 **Thao tác Liên dịch vụ** | Đồng bộ dữ liệu giữa Liberica và Arabica |
-
-### Các trường hợp Sử dụng
-
-- **Quản lý Kế hoạch Sản xuất**: Tạo, truy vấn và hủy đơn hàng sản xuất
-- **Quản lý Dữ liệu Sản phẩm**: Tìm kiếm sản phẩm đa nền tảng, đồng bộ thông tin
-- **Thao tác Khách hàng**: Truy vấn thông tin khách hàng và tạo báo giá
-- **Tự động hóa AI**: Tự động hóa quy trình kinh doanh thông qua Claude Code
+[![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/)
 
 ---
 
-## Bắt đầu Nhanh
+## ⚡ Khởi Đầu Nhanh
 
-### Cài đặt
+### 1. Cài Đặt
 
 ```bash
-# Cài đặt qua npm
 npm install -g @newpeak/barista-cli
-
-# Hoặc qua yarn
-yarn global add @newpeak/barista-cli
-
-# Xác minh cài đặt
-barista --version
 ```
 
-### Cấu hình Ban đầu
+### 2. Xác Thực
 
 ```bash
-# 1. Khởi tạo thư mục cấu hình
-barista init
-
-# 2. Đăng nhập bằng thông tin đăng nhập (phương pháp khuyến nghị, tự động đặt môi trường và người thuê)
-barista liberica auth login dev your-tenant your-username your-password
+# 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
 
-# Hoặc đăng nhập tương tác (hệ thống sẽ nhắc thông tin thiếu)
+# Đăng nhập tương tác (nhắc nhập thông tin còn thiếu)
 barista liberica auth login
-
-# 3. Xác minh trạng thái đăng nhập
-barista auth status
-
-# 4. Xem ngữ cảnh hiện tại (xác nhận môi trường đã được đặt tự động)
-barista context show
-```
-
-**Lưu ý**: Sau khi sử dụng `barista liberica auth login`, hệ thống tự động đặt ngữ cảnh môi trường hiện tại, vì vậy các lệnh tiếp theo không cần chỉ định tham số `--env` và `--tenant`.
-
-### Ví dụ Sử dụng Cơ bản
-
-```bash
-# Xem ngữ cảnh hiện tại
-barista context show
-
-# Liệt kê tất cả đơn hàng (Liberica)
-barista liberica orders list
-
-# Tìm kiếm sản phẩm (hỗ trợ tìm kiếm mờ)
-barista liberica products search --keyword "máy cà phê"
-
-# Xem danh mục sản phẩm Arabica
-barista arabica products public-catalog
-
-# Tạo đơn hàng sản xuất (chế độ xem trước dry-run)
-barista liberica orders create --product-id 123 --quantity 100 --dry-run
 ```
 
----
-
-## Thiết kế Kiến trúc
-
-### Ánh xạ Môi trường
-
-#### Liberica (SaaS Quản lý Sản xuất)
-
-| Môi trường | Định dạng Tên miền | Mô tả |
-|------------|-------------------|-------|
-| dev | `{tenant}-dev.newpeaksh.com` | Môi trường Phát triển |
-| test | `{tenant}-test.newpeaksh.com` | Môi trường Kiểm thử |
-| prod-cn | `{tenant}.newpeaksh.com` | Môi trường Sản xuất Trung Quốc |
-| prod-jp | `{tenant}.newpeakjp.com` | Môi trường Sản xuất Nhật Bản |
-
-#### Arabica (Nền tảng Bán hàng)
-
-| Môi trường | Tên miền | Mô tả |
-|------------|----------|-------|
-| dev | `arabica-dev.newpeaksh.com` | Môi trường Phát triển |
-| test | `arabica-test.newpeaksh.com` | Môi trường Kiểm thử |
-| prod-cn | `www.newpeaksh.com` | Môi trường Sản xuất Trung Quốc |
-| prod-jp | `members.newpeakjp.com` | Môi trường Sản xuất Nhật Bản |
-
-### Cơ chế Xác thực
+### 3. Tích Hợp AI
 
-Barista CLI sử dụng cơ chế xác thực dựa trên Token:
+```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)
 
-```
-┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
-│   Barista CLI   │────▶│   Auth Server    │────▶│   API Servers   │
-│                 │     │                  │     │                 │
-│ • Yêu cầu ĐN    │     │ • Xác minh TT    │     │ • Xác minh Token│
-│ • Lưu Token     │◀────│ • Cấp JWT        │◀────│ • Trả dữ liệu   │
-│   (Chuỗi khóa)  │     │                  │     │                 │
-└─────────────────┘     └──────────────────┘     └─────────────────┘
+// AI phân tích và xử lý dữ liệu
+if (data.items.length > 0) {
+  console.log(`Found ${data.pagination.total} orders`)
+}
 ```
 
-**Tính năng Bảo mật:**
-
-- **Lưu trữ Chuỗi khóa**: Token được lưu trữ an toàn trong chuỗi khóa hệ thống (macOS Keychain, Windows Credential, Linux Secret Service)
-- **Tự động Bỏ qua Xác thực**: Các giao diện công khai (như truy vấn danh mục sản phẩm) không cần xác thực
-- **Cách ly Môi trường**: Mỗi môi trường và ngưới thuê sử dụng Token độc lập
-- **Làm mới Token**: Hỗ trợ tự động làm mới Token sắp hết hạn
+**[Xem ví dụ tích hợp AI →](#ai-integration)**
 
 ---
 
-## Tài liệu Lệnh
-
-> **Tham chiếu Lệnh Đầy đủ**: Để xem tham chiếu đầy đủ về tất cả các lệnh (bao gồm đã triển khai và đang phát triển), vui lòng xem [Tham chiếu Lệnh](./docs/commands/REFERENCE.md).
-
-### Cấu trúc Lệnh
+## 🤖 Tích Hợp AI
 
-```
-barista <service> <resource> <action> [options]
-```
+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ý.
 
-**Ví dụ:**
-
-```bash
-barista liberica orders list --page 1 --size 20
-barista arabica quotes calculate --product-id 123 --quantity 10
-```
+### Các AI Tools Được Hỗ Trợ
 
-### Tùy chọn Toàn cục
+| 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 |
 
-| Tùy chọn | Mô tả | Ví dụ |
-|----------|-------|-------|
-| `--env` | Chỉ định môi trường | `--env prod-cn` |
-| `--tenant` | Chỉ định ngưới thuê | `--tenant electionjp` |
-| `--service` | Chỉ định dịch vụ | `--service liberica` |
-| `--dry-run` | Chế độ xem trước | `--dry-run` |
-| `--json` | Đầu ra JSON | `--json` |
-| `--help` | Hiển thị trợ giúp | `--help` |
+### Mẫu Tích Hợp
 
-### Quản lý Ngữ cảnh
+```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}`)
+}
 
-Quản lý ngữ cảnh được sử dụng để chuyển đổi nhanh môi trường làm việc, tránh phải chỉ định tham số môi trường cho mỗi lệnh.
+// 3. Xử lý dữ liệu
+const pendingOrders = data.items
+console.log(`Found ${data.pagination.total} pending orders`)
 
-```bash
-# Xem ngữ cảnh hiện tại
-barista context show
+// 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`
 
-# Ví dụ đầu ra:
-# ┌─────────────┬─────────────────┐
-# │ Thuộc tính  │ Giá trị         │
-# ├─────────────┼─────────────────┤
-# │ Môi trường  │ dev             │
-# │ Ngưới thuê  │ electionjp      │
-# │ Dịch vụ     │ liberica        │
-# │ Trạng thái  │ Đã đăng nhập    │
-# │ Hết hạn     │ 2024-12-31      │
-# └─────────────┴─────────────────┘
-
-# Chuyển đổi môi trường
-barista context use-env [dev|test|prod-cn|prod-jp]
-
-# Chuyển đổi ngưới thuê
-barista context use-tenant <tenant-name>
-
-# Chuyển đổi dịch vụ mặc định
-barista context use-service [liberica|arabica]
+  // Phân tích preview, xác minh, rồi thực thi với --force
+  // ...
+}
 ```
 
-### Quản lý Xác thực
-
-Barista CLI cung cấp hai phương pháp đăng nhập:
+### Response Envelope
 
-#### 1. Đăng nhập bằng Thông tin đăng nhập (Khuyến nghị)
-Sử dụng tên người dùng và mật khẩu cho quy trình xác thực hoàn chỉnh, tự động lấy và lưu Token:
+Tất cả phản hồi JSON đều theo cấu trúc này:
 
-```bash
-# Đăng nhập Liberica bằng thông tin đăng nhập
-barista liberica auth login <env> [tenant] [username] [password]
-
-# Ví dụ: Đăng nhập môi trường kiểm thử Liberica
-barista liberica auth login test electionjp admin@shanghai.newpeaksh.com 123456
-
-# Đăng nhập tương tác (hệ thống sẽ nhắc thông tin thiếu)
-barista liberica auth login
-
-# Sau khi đăng nhập, ngữ cảnh môi trường hiện tại được đặt tự động
+```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"
+  }
+}
 ```
 
-#### 2. Lưu trữ Token trực tiếp
-Phù hợp cho các trường hợp đã có JWT Token (ví dụ: lấy từ nguồn khác):
-
-```bash
-# Lưu trữ Token trực tiếp
-barista auth login --service <service> --env <env> [--tenant <tenant>]
-
-# Ví dụ: Lưu trữ Token môi trường phát triển Liberica
-barista auth login --service liberica --env dev --tenant electionjp
-# Lời nhắc: Nhập token của bạn: [nhập Token hiện có]
-
-# Kiểm tra trạng thái đăng nhập
-barista auth status
-
-# Ví dụ đầu ra:
-# ✓ Liberica (dev) - Đã đăng nhập (Hết hạn: 2024-12-31)
-# ✗ Liberica (test) - Chưa đăng nhập
-# ✓ Arabica (prod-cn) - Đã đăng nhập (Hết hạn: 2024-12-30)
-
-# Đăng xuất (xóa Token)
-barista auth logout --service <service> --env <env>
+**Định dạng lỗi:**
 
-# Đăng xuất tất cả môi trường
-barista auth logout --all
+```json
+{
+  "success": false,
+  "error": {
+    "code": "A150001",
+    "message": "Order not found"
+  },
+  "meta": {
+    "requestId": "req-xyz789",
+    "timestamp": "2024-01-15T10:30:00Z"
+  }
+}
 ```
 
-**Quan trọng**: Sau khi sử dụng `barista liberica auth login`, hệ thống tự động đặt ngữ cảnh môi trường hiện tại, vì vậy các lệnh tiếp theo không cần chỉ định tham số `--env`.
+### Skills cho Claude Code
 
-### Lệnh Liberica
-
-#### Quản lý Đơn hàng
+Cài đặt các file skill có thể tái sử dụng:
 
 ```bash
-# Liệt kê đơn hàng (phân trang)
-barista liberica orders list [--page <n>] [--size <n>] [--status <status>]
-
-# Lấy chi tiết đơn hàng
-barista liberica orders get <order-id>
-
-# Tạo đơn hàng
-barista liberica orders create \
-  --product-id <id> \
-  --quantity <n> \
-  [--delivery-date <date>] \
-  [--note <text>]
-
-# Hủy đơn hàng
-barista liberica orders cancel <order-id> [--reason <text>]
+# Skills nằm tại ~/.barista/claude/skills/
+barista skills install
 ```
 
-#### Quản lý Sản phẩm
+**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
 
-```bash
-# Tìm kiếm sản phẩm
-barista liberica products search --keyword <keyword> [--category <id>]
+---
 
-# Lấy chi tiết sản phẩm
-barista liberica products get <product-id>
+## 🚀 Tính Năng
 
-# Lấy danh sách sản phẩm công khai (không cần xác thực)
-barista liberica products public-list [--category <id>] [--page <n>]
-```
+### Thiết Kế AI-First
 
-#### Kế hoạch Sản xuất
+| 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 |
 
-```bash
-# Xem lịch sản xuất
-barista liberica production schedule [--start-date <date>] [--end-date <date>]
+### Kết Nối Doanh Nghiệp
 
-# Lên lịch lại
-barista liberica production reschedule <order-id> --new-date <date> [--dry-run]
+| 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 |
 
-# Truy vấn công suất
-barista liberica production capacity [--date <date>] [--line <line-id>]
-```
+### An Toàn Vận Hành
 
-### Lệnh Arabica
+- 📊 **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
 
-#### Quản lý Sản phẩm
+---
 
-```bash
-# Liệt kê sản phẩm
-barista arabica products list [--page <n>] [--size <n>] [--category <id>]
+## 🔧 Tham Khảo Lệnh
 
-# Tìm kiếm sản phẩm
-barista arabica products search --keyword <keyword>
+### Mẫu Cơ Bản
 
-# Lấy danh mục sản phẩm (giao diện công khai)
-barista arabica products public-catalog [--lang <zh|jp|en>]
 ```
-
-#### Quản lý Báo giá
-
-```bash
-# Tính báo giá
-barista arabica quotes calculate \
-  --product-id <id> \
-  --quantity <n> \
-  [--options <json>]
-
-# Tạo báo giá
-barista arabica quotes create \
-  --customer-id <id> \
-  --items <json> \
-  [--valid-days <n>]
+barista <service> <resource> <action> [options]
 ```
 
-#### Quản lý Khách hàng
+### Các Tùy Chọn Toàn Cục
 
-```bash
-# Tìm kiếm khách hàng
-barista arabica customers search --keyword <keyword> [--type <type>]
-
-# Lấy chi tiết khách hàng
-barista arabica customers get <customer-id>
-```
+| 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` |
 
-### Lệnh Liên dịch vụ
+### Tham Khảo Nhanh
 
-Các lệnh liên dịch vụ cho phép đồng bộ dữ liệu và kết nối quy trình kinh doanh giữa Liberica và Arabica.
+| 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 |
 
-```bash
-# Tạo báo giá từ đơn hàng
-barista cross quote-from-order <order-id> [--target-service arabica]
-
-# Ví dụ đầu ra:
-# ✓ Đã tạo báo giá
-# ┌──────────┬────────────┐
-# │ Thuộc tính│ Giá trị   │
-# ├──────────┼────────────┤
-# │ ID ĐH    │ 12345      │
-# │ ID Báo giá│ QT-2024-001│
-# │ Số tiền  │ ¥50,000    │
-# │ Hiệu lực │ 30 ngày    │
-# └──────────┴────────────┘
-
-# Đồng bộ trạng thái đơn hàng sang Arabica
-barista cross sync-order <order-id> [--direction liberica-to-arabica]
-```
+**[→ Tham Khảo Lệnh Chi Tiết](./docs/commands/REFERENCE.md)**
 
 ---
 
-## Tính năng Nâng cao
+## 🛡️ Hướng Dẫn An Toàn AI
 
-### Chế độ Dry-Run
+### 1. Luôn Chạy Dry-Run Trước
 
-Chế độ Dry-Run cho phép bạn xem trước tác động của thao tác ghi trước khi thực hiện, tránh lỗi.
+```typescript
+// ❌ Sai — Thực thi mù quáng
+await $`barista liberica orders cancel 12345`
 
-```bash
-# Tất cả thao tác ghi đều hỗ trợ tùy chọn --dry-run
-barista liberica orders create --product-id 123 --quantity 100 --dry-run
-
-# Ví dụ đầu ra:
-# 🔍 Chế độ Dry-Run: Thao tác sẽ không được thực thi
-# ┌─────────────────┬──────────────────────┐
-# │ Thao tác        │ Tạo đơn hàng         │
-# ├─────────────────┼──────────────────────┤
-# │ Sản phẩm        │ Máy cà phê Pro (ID: 123) │
-# │ Số lượng        │ 100                  │
-# │ Số tiền dự kiến │ ¥50,000              │
-# │ Ngày giao dự kiến│ 2024-12-31          │
-# │ Tác động        │ Thêm 1 bản ghi đơn hàng │
-# └─────────────────┴──────────────────────┘
-# 
-# ⚠️  Xác nhận thực hiện? Thêm tùy chọn --confirm hoặc xóa --dry-run
+// ✅ Đú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`
 ```
 
-**Thao tác Dry-Run Mặc định:**
-
-Các thao tác phá hủy sau có chế độ Dry-Run được bật mặc định và yêu cầu xác nhận rõ ràng:
-
-- Hủy đơn hàng
-- Xóa sản phẩm
-- Cập nhật hàng loạt
-
-### Định dạng Đầu ra JSON
-
-Barista CLI hỗ trợ đầu ra JSON để xử lý script và tích hợp AI:
-
-```bash
-barista liberica orders list --json
+### 2. Kiểm Tra Success Trước Khi Tiếp Tục
 
-# Ví dụ đầu ra:
-{
-  "success": true,
-  "data": {
-    "items": [
-      {
-        "id": "12345",
-        "productName": "Máy cà phê Pro",
-        "quantity": 100,
-        "status": "in_production",
-        "createdAt": "2024-01-15T10:30:00Z"
-      }
-    ],
-    "pagination": {
-      "page": 1,
-      "size": 20,
-      "total": 150
-    }
-  }
+```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)
 }
 ```
 
-### Định dạng Xuất CSV
-
-Barista CLI hỗ trợ xuất định dạng CSV, phù hợp cho phân tích dữ liệu và xử lý Excel:
+### 3. Sử Dụng Request ID Để Debug
 
-```bash
-# Xuất dữ liệu loại từ điển dưới dạng CSV
-barista liberica dict-types tenant-items --lang ja --all --csv --output ./dict-data.csv
-
-# Tính năng đầu ra:
-# • Mã hóa UTF-8 with BOM đảm bảo nhận dạng chữ Trung Quốc chính xác trong Excel
-# • Tự động thoát ký tự đặc biệt (dấu phẩy, dấu ngoặc kép, ngắt dòng)
-# • Hỗ trợ đường dẫn tệp đầu ra tùy chỉnh
-# • Có thể kết hợp với --json để có cả hai định dạng đầu ra
+```typescript
+const { meta } = JSON.parse(stdout)
+console.log(`Request ID: ${meta.requestId}`)
 ```
 
-Tệp CSV sử dụng mã hóa UTF-8 with BOM để đảm bảo hiển thị chính xác các ký tự Unicode như tiếng Trung, tiếng Nhật, tiếng Việt trong Microsoft Excel và các công cụ khác.
+### 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
+## ⚙️ Cấu Hình
 
-### Tệp Cấu hình
+### Vị Trí File
 
-Tệp cấu hình nằm tại `~/.barista/config.yaml`:
+`~/.barista/config.yaml`
 
-```yaml
-# Tệp cấu hình Barista CLI
+### Cấu Hình Nhanh
 
-# Cài đặt ngữ cảnh mặc định
+```yaml
 defaults:
-  env: dev
-  tenant: electionjp
+  env: prod-cn
+  tenant: your-tenant
   service: liberica
 
-# Cấu hình môi trường
 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"
@@ -500,258 +270,71 @@ environments:
     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
-
-# Cấu hình đầu ra
-output:
-  format: table  # table | json
-  color: true
-  timestamp: true
 ```
 
-### Cấu hình Đa ngưới thuê
-
-Hỗ trợ cấu hình nhiều ngưới thuê để chuyển đổi nhanh:
+### Xác Thực
 
 ```bash
-# Thêm cấu hình ngưới thuê
-barista config add-tenant \
-  --name customer-a \
-  --liberica-id customer-a-id \
-  --arabica-id customer-a-arabica-id
+# Đăng nhập bằng credentials (khuyến nghị)
+barista liberica auth login <env> <tenant> <username> <password>
 
-# Liệt kê ngưới thuê đã cấu hình
-barista config list-tenants
+# Kiểm tra trạng thái đăng nhập
+barista auth status
 
-# Chuyển đổi ngưới thuê nhanh
-barista context use-tenant customer-a
+# Đăng xuất
+barista auth logout --service liberica --env prod-cn
 ```
 
 ---
 
-## Tích hợp AI
-
-Barista CLI được tối ưu hóa cho trợ lý lập trình AI, đặc biệt là Claude Code.
-
-### Ví dụ Sử dụng Claude Code
-
-```typescript
-// Sử dụng Barista CLI trong Claude Code
-// Ví dụ: Lấy danh sách đơn hàng và phân tích
-
-const result = await $`barista liberica orders list --json --page 1 --size 10`;
-const orders = JSON.parse(result.stdout);
-
-// Phân tích dữ liệu đơn hàng
-const analysis = orders.data.items.map(order => ({
-  id: order.id,
-  status: order.status,
-  amount: order.amount
-}));
-```
-
-### Tệp Skills
-
-Barista CLI cung cấp các tệp Claude Code Skills, nằm tại:
-
-```
-~/.barista/claude/skills/
-├── orders.md       # Kỹ năng quản lý đơn hàng
-├── products.md     # Kỹ năng quản lý sản phẩm
-├── quotes.md       # Kỹ năng quản lý báo giá
-└── customers.md    # Kỹ năng quản lý khách hàng
-```
-
-**Ví dụ Tệp Skills:**
+## ❓ Xử Lý Sự Cố
 
-```markdown
-# Kỹ năng Quản lý Đơn hàng
-
-## Liệt kê Đơn hàng Chờ xử lý
-
-Khi ngưới dùng hỏi về đơn hàng chờ xử lý:
-
-1. Thực thi lệnh: barista liberica orders list --status pending --json
-2. Phân tích JSON trả về
-3. Tóm tắt số lượng đơn hàng và tổng số tiền
-4. Liệt kê thông tin quan trọng của 5 đơn hàng đầu tiên
-
-## Tạo Đơn hàng Mới
-
-Khi ngưới dùng cần tạo đơn hàng:
-
-1. Xác nhận ID sản phẩm và số lượng
-2. Sử dụng dry-run để xem trước: barista liberica orders create --dry-run ...
-3. Thực thi lệnh thực sau khi ngưới dùng xác nhận
-```
-
-### Đầu ra Thân thiện với AI
-
-Tất cả lệnh đều hỗ trợ tùy chọn `--json`, trả về dữ liệu JSON có cấu trúc:
+### Lỗi Xác Thực
 
 ```bash
-# Truy vấn với đầu ra có cấu trúc
-barista liberica orders get 12345 --json
-
-{
-  "success": true,
-  "data": {
-    "id": "12345",
-    "status": "in_production",
-    "product": {
-      "id": "100",
-      "name": "Máy cà phê 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"
-  }
-}
-```
-
----
-
-## Hướng dẫn Phát triển
+# Kiểm tra trạng thái hiện tại
+barista auth status
 
-### Cấu trúc Dự án
+# Đăng nhập lại
+barista liberica auth login prod-cn your-tenant your-username your-password
 
-```
-coffee-barista-cli/
-├── bin/
-│   └── barista.js              # Tệp khởi đầu
-├── src/
-│   ├── commands/               # Triển khai lệnh
-│   │   ├── context/            # Lệnh quản lý ngữ cảnh
-│   │   ├── auth/               # Lệnh xác thực
-│   │   ├── liberica/           # Lệnh dịch vụ Liberica
-│   │   │   ├── orders.js
-│   │   │   ├── products.js
-│   │   │   └── production.js
-│   │   ├── arabica/            # Lệnh dịch vụ Arabica
-│   │   │   ├── products.js
-│   │   │   ├── quotes.js
-│   │   │   └── customers.js
-│   │   └── cross/              # Lệnh liên dịch vụ
-│   ├── core/                   # Mô-đun cốt lõi
-│   │   ├── auth.js             # Quản lý xác thực
-│   │   ├── config.js           # Quản lý cấu hình
-│   │   ├── context.js          # Quản lý ngữ cảnh
-│   │   └── api-client.js       # Client API
-│   ├── utils/                  # Hàm tiện ích
-│   │   ├── formatter.js        # Định dạng đầu ra
-│   │   ├── validator.js        # Xác thực tham số
-│   │   └── keychain.js         # Thao tác chuỗi khóa
-│   └── templates/              # Tệp mẫu
-├── skills/                     # Claude Code Skills
-├── tests/                      # Tệp kiểm thử
-├── package.json
-└── README.md
+# Kiểm tra context
+barista context show
 ```
 
-### Phát triển Local
+### Lỗi API
 
 ```bash
-# 1. Clone kho lưu trữ
-git clone https://gitlab.newpeaksh.com/coffee/coffee-barista-cli.git
-cd coffee-barista-cli
-
-# 2. Cài đặt phụ thuộc
-npm install
-
-# 3. Liên kết toàn cục (chế độ phát triển)
-npm link
-
-# 4. Xác minh liên kết
-barista --version
-
-# 5. Chạy kiểm thử
-npm test
+# Luôn sử dụng --json để nhận mã lỗi
+barista liberica orders list --json
 
-# 6. Kiểm tra mã
-npm run lint
+# Phản hồi lỗi bao gồm requestId để debug
+# "requestId": "req-abc123"
 ```
 
-### Thêm Lệnh Mới
-
-**Quan trọng**: Lệnh mới phải tuân theo [Đặc tả Thiết kế Lệnh](./docs/COMMAND_DESIGN_SPEC.md), bao gồm viết tài liệu thiết kế, đánh giá kỹ thuật và các quy trình hoàn chỉnh khác.
-
-Tham khảo chi tiết tại:
-- [Tham chiếu Lệnh Đầy đủ](./docs/commands/REFERENCE.md) - Danh sách tất cả lệnh và ưu tiên phát triển
-- [Tài liệu Đặc tả Thiết kế Lệnh](./docs/COMMAND_DESIGN_SPEC.md#5-quy-trình-phát-triển-lệnh)
-- [Hướng dẫn Phát triển Lệnh](./docs/COMMANDS.md)
-
----
-
-## Hướng dẫn Đóng góp
-
-Chúng tôi hoan nghênh mọi hình thức đóng góp, bao gồm nhưng không giới hạn ở:
-
-- 🐛 Báo cáo lỗi
-- 💡 Đề xuất tính năng mới
-- 📝 Cải thiện tài liệu
-- 🔧 Gửi bản sửa lỗi
-- ✨ Thêm tính năng mới
-
-### Quy ước Commit
-
-Vui lòng tuân theo quy chuẩn [Conventional Commits](https://www.conventionalcommits.org/):
+### Vấn Đề Timeout
 
 ```bash
-# Sửa lỗi
-fix: sửa lỗi phân trang danh sách đơn hàng
-
-# Thêm tính năng
-feat: thêm lệnh truy vấn tồn kho
-
-# Cập nhật tài liệu
-docs: cập nhật ánh xạ môi trường trong README
+# Chuyển sang môi trường gần hơn
+barista context use-env dev
 
-# Tái cấu trúc mã
-refactor: tái cấu trúc xử lý lỗi client API
+# Hoặc điều chỉnh timeout trong config.yaml
 ```
 
-### Quy trình Phát triển
-
-1. Fork kho lưu trữ này
-2. Tạo nhánh tính năng: `git checkout -b feature/my-feature`
-3. Commit thay đổi: `git commit -m 'feat: add some feature'`
-4. Push nhánh: `git push origin feature/my-feature`
-5. Tạo Pull Request
-
 ---
 
-## Dự án Liên quan
+## 📚 Các Dự Án Liên Quan
 
-| Dự án | Mô tả | Liên kết |
-|-------|-------|----------|
-| ☕ Liberica Backend | Backend SaaS Quản lý Sản xuất | [coffee-liberica-end](https://gitlab.newpeaksh.com/coffee/coffee-liberica-end) |
-| 🖥️ Liberica Frontend | Frontend Web Quản lý Sản xuất | [coffee-liberica-front](https://gitlab.newpeaksh.com/coffee/coffee-liberica-front) |
-| 📱 Liberica Mobile | Di động Quản lý Sản xuất | [coffee-liberica-mobile-front](https://gitlab.newpeaksh.com/coffee/coffee-liberica-mobile-front) |
-| 🛒 Arabica Backend | Backend Nền tảng Bán hàng | [coffee-arabica-end](https://gitlab.newpeaksh.com/coffee/coffee-arabica-end) |
-| 🌐 Arabica Frontend | Frontend Nền tảng Bán hàng | [coffee-arabica-front](https://gitlab.newpeaksh.com/coffee/coffee-arabica-front) |
+| 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
+## 📄 Giấy Phép
 
 [MIT](LICENSE) © Newpeak Technology
-
----
-
-<p align="center">
-  Được cung cấp bởi ☕
-</p>