@newpeak/barista-cli 0.1.0

package/docs/COMMAND_DESIGN_SPEC.md

@@ -0,0 +1,811 @@
+# Barista CLI 命令设计规范
+
+## 1. 文档目的
+
+本规范定义 Barista CLI 每个命令的设计文档格式。每个命令在开发前必须按此模板编写设计文档，明确引用后端代码位置。
+
+---
+
+## 2. 命令设计文档模板
+
+每个命令设计文档必须包含以下章节：
+
+```markdown
+# 命令名称: barista <service> <resource> <action>
+
+## 2.1 命令元数据
+
+| 字段 | 值 |
+|------|-----|
+| 完整命令 | `barista liberica orders create` |
+| 功能描述 | 创建销售订单 |
+| HTTP方法 | POST |
+| 是否需要认证 | ✅ 是 / ⬜ 否 |
+| 是否支持dry-run | ✅ 是 / ⬜ 否 |
+
+## 2.2 后端接口引用
+
+### Controller位置
+```
+<coffee-liberica-end 或 coffee-arabica-end 相对路径>
+└── <Controller类全路径>
+    └── <方法名>(@<MethodResource>)
+        └── 方法签名
+```
+
+**实际示例：**
+```
+coffee-liberica-end/
+└── facade/liberica-facade-enterprise/
+    └── src/main/java/com/newpeak/liberica/facade/enterprise/controller/sales/
+        └── EnterpriseSalesOrderController.java
+            └── add(@PostResource(path = "/add"))
+                └── public ResponseData<SalesOrderResponse> add(
+                        @RequestHeader("X-TENANT-ID") Long tenantId,
+                        @RequestBody @Validated(BaseRequest.add.class) SalesOrderRequest request
+                    )
+```
+
+### Request DTO位置
+```
+<模块>/src/main/java/<包路径>/
+└── <Request类名>.java
+    └── 核心字段（列出CLI会用到的）
+```
+
+**实际示例：**
+```
+coffee-liberica-end/
+└── business/liberica-business-sales/sales-api/
+    └── src/main/java/com/newpeak/liberica/sales/api/pojo/request/
+        └── SalesOrderRequest.java
+            ├── clientCode: String (@NotBlank)
+            ├── clientName: String (@NotBlank)
+            ├── materialNo: String
+            ├── materialName: String
+            ├── purchaseNumber: BigDecimal
+            ├── deliveryDate: Date
+            └── salesOrderStatus: String
+```
+
+### Response DTO位置
+```
+<模块>/src/main/java/<包路径>/
+└── <Response类名>.java
+    └── 核心字段（列出CLI会返回的）
+```
+
+**实际示例：**
+```
+coffee-liberica-end/
+└── business/liberica-business-sales/sales-api/
+    └── src/main/java/com/newpeak/liberica/sales/api/pojo/response/
+        └── SalesOrderResponse.java
+            ├── salesOrderId: Long
+            ├── salesOrderCode: String
+            ├── clientName: String
+            ├── materialName: String
+            └── salesOrderStatus: String
+```
+
+## 2.3 CLI参数设计
+
+### 命令结构
+```bash
+barista <service> <resource> <action> [全局选项] [命令选项]
+```
+
+### 全局选项
+| 选项 | 类型 | 说明 |
+|------|------|------|
+| `--env` | string | 目标环境(dev/test/prod-cn/prod-jp) |
+| `--tenant` | string | 租户代码（仅Liberica） |
+| `--dry-run` | boolean | 预览模式 |
+| `--json` | boolean | JSON输出 |
+
+### 命令选项
+| 选项 | 短选项 | 类型 | 必填 | 默认值 | 说明 | 对应DTO字段 |
+|------|--------|------|------|--------|------|-------------|
+| --client-code | -c | string | ✅ | - | 客户编码 | clientCode |
+| --client-name | -n | string | ✅ | - | 客户名称 | clientName |
+| --product-id | -p | string | ✅ | - | 产品号码 | materialNo |
+| --quantity | -q | number | ✅ | - | 订购数量 | purchaseNumber |
+| --due-date | -d | string | ⬜ | - | 交货日期(YYYY-MM-DD) | deliveryDate |
+| --status | -s | string | ⬜ | pending | 订单状态 | salesOrderStatus |
+| --remark | -r | string | ⬜ | - | 备注 | remark |
+
+### 位置参数与选项参数混合支持
+
+CLI 命令应同时支持**位置参数**和**选项参数**，允许用户根据习惯灵活调用。
+
+**命令结构：**
+```bash
+barista <service> <resource> <action> [位置参数...] [选项]
+```
+
+**设计原则：**
+1. 位置参数使用 `Commander.arguments()` 定义
+2. 选项参数使用 `.option()` 定义
+3. Action handler 中位置参数在前，options 对象在后
+4. 解析优先级：**选项参数 > 位置参数 > 默认值**
+
+**实现示例：**
+```typescript
+// 定义命令，同时支持位置参数和选项
+program
+  .command('login')
+  .arguments('<env> [tenant] [username] [password]')
+  .option('--env <environment>', 'Environment')
+  .option('--tenant <tenant>', 'Tenant name')
+  .option('--username <username>', 'Username')
+  .option('--password <password>', 'Password')
+  .action(async (env, tenant, username, password, options) => {
+    // 解析：选项参数优先，其次位置参数，最后默认值
+    const resolvedEnv = options.env || env || defaultEnv;
+    const resolvedTenant = options.tenant || tenant || defaultTenant;
+    const resolvedUsername = options.username || username;
+    const resolvedPassword = options.password || password;
+  });
+```
+
+**调用方式：**
+```bash
+# 全位置参数
+barista liberica auth login dev shanghai admin pass
+
+# 全选项参数
+barista liberica auth login --env dev --tenant shanghai --username admin --password pass
+
+# 混合使用（常见）
+barista liberica auth login dev --username admin --password pass
+
+# 交互式（无参数）
+barista liberica auth login
+```
+
+## 2.4 字段映射表
+
+| CLI参数 | DTO字段 | 类型转换 | 验证规则 |
+|---------|---------|----------|----------|
+| --client-code | clientCode | 直接传递 | @NotBlank, max=255 |
+| --client-name | clientName | 直接传递 | @NotBlank, max=255 |
+| --product-id | materialNo | 直接传递 | - |
+| --quantity | purchaseNumber | string→BigDecimal | @NotNull, >0 |
+| --due-date | deliveryDate | string→Date | yyyy-MM-dd |
+| --status | salesOrderStatus | 直接传递 | enum验证 |
+| --remark | remark | 直接传递 | max=255 |
+
+## 2.5 错误码引用
+
+### ExceptionEnum位置
+```
+<模块>/src/main/java/<包路径>/exception/enums/
+└── <ExceptionEnum>.java
+```
+
+**实际示例：**
+```
+coffee-liberica-end/
+└── business/liberica-business-sales/sales-api/
+    └── src/main/java/com/newpeak/liberica/sales/api/exception/enums/
+        └── SalesOrderExceptionEnum.java
+            ├── SALES_ORDER_NOT_EXIST("xxx", "销售订单不存在")
+            ├── SALES_ORDER_CODE_DUPLICATE("xxx", "销售订单编码重复")
+            └── ...
+```
+
+### Service层业务校验
+```
+<模块>/src/main/java/<包路径>/business/
+└── <Business类>.java
+    └── <方法名>()
+        └── 抛出异常的具体位置（行号或代码片段）
+```
+
+**实际示例：**
+```
+coffee-liberica-end/
+└── business/liberica-business-sales/sales-business/
+    └── src/main/java/com/newpeak/liberica/sales/modular/business/
+        └── SalesOrderBusiness.java
+            └── add(SalesOrderRequest request)
+                ├── Line 85: 检查客户是否存在
+                │   └── throw new SalesException(ClientExceptionEnum.CLIENT_NOT_EXIST)
+                ├── Line 102: 检查产品是否存在
+                │   └── throw new MaterialException(MaterialExceptionEnum.MATERIAL_NOT_EXIST)
+                └── Line 128: 检查编码是否重复
+                    └── throw new SalesException(SalesOrderExceptionEnum.SALES_ORDER_CODE_DUPLICATE)
+```
+
+### 已知错误码示例
+| 错误码 | 错误消息 | 触发条件 |
+|--------|----------|----------|
+| xxx | 销售订单不存在 | 编辑/详情时ID不存在 |
+| xxx | 销售订单编码重复 | 编码已存在 |
+| xxx | 客户不存在 | clientCode无效 |
+| xxx | 产品不存在 | materialNo无效 |
+
+## 2.6 权限检查
+
+| 检查项 | 位置 | 说明 |
+|--------|------|------|
+| PermissionConstants | `.../constants/SalesOrderPermissionConstants.java` | ADD_SALES_ORDER |
+| 注解 | `@PostResource(requiredPermission = true, requirePermissionCode = ...)` | Controller方法上 |
+
+## 2.7 公开接口声明（如适用）
+
+如果此接口支持公开访问（无需认证）：
+
+```yaml
+public_endpoints:
+  - service: "liberica"
+    path: "/api/enterprise/sales/salesOrder/publicList"
+```
+
+---
+
+## 3. 命令分类规范
+
+### 3.1 服务(service)命名
+- `liberica` - Liberica生产管理
+- `arabica` - Arabica销售平台
+
+### 3.2 资源(resource)命名
+使用名词复数形式：
+- ✅ `orders` (订单)
+- ✅ `products` (产品)
+- ✅ `customers` (客户)
+- ❌ `order` (不规范)
+- ❌ `create-order` (动词不应出现在resource)
+
+### 3.3 动作(action)命名
+使用动词：
+| 动作 | 用途 | HTTP方法 |
+|------|------|----------|
+| list | 列表查询 | GET |
+| get | 详情查询 | GET |
+| create | 创建 | POST |
+| update | 更新 | POST/PUT |
+| delete | 删除 | POST/DELETE |
+| cancel | 取消 | POST |
+| search | 搜索 | GET |
+
+---
+
+## 4. 文档存放位置
+
+命令设计文档存放在：
+```
+coffee-barista-cli/
+└── docs/
+    └── commands/
+        ├── liberica/
+        │   ├── orders-create.md
+        │   ├── orders-list.md
+        │   ├── orders-get.md
+        │   └── ...
+        ├── arabica/
+        │   ├── products-list.md
+        │   └── ...
+        └── cross/
+            └── ...
+```
+
+---
+
+## 5. 命令开发流程规范
+
+### 5.1 流程概览
+
+每个命令的开发必须遵循以下流程：
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ Phase 1: 设计阶段 (必须完成)                                  │
+├─────────────────────────────────────────────────────────────┤
+│ 1. 编写设计文档 → 2. 技术评审 → 3. 设计文档归档               │
+└─────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────┐
+│ Phase 2: 开发阶段                                            │
+├─────────────────────────────────────────────────────────────┤
+│ 4. 接口契约确认 → 5. 类型定义 → 6. 核心实现 → 7. 错误处理     │
+└─────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────┐
+│ Phase 3: 验证阶段                                            │
+├─────────────────────────────────────────────────────────────┤
+│ 8. 单元测试 → 9. 集成测试 → 10. Code Review → 11. 合并      │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 5.2 详细流程
+
+#### Phase 1: 设计阶段
+
+**Step 1: 编写设计文档** (预估: 30-60分钟)
+- [ ] 按第2节模板编写设计文档
+- [ ] 确认后端接口位置（查看Controller代码）
+- [ ] 确认DTO字段（查看Request/Response类）
+- [ ] 确认错误码（查看ExceptionEnum）
+- [ ] 输出: `docs/commands/<service>/<resource>-<action>.md`
+
+**Step 2: 技术评审** (预估: 15-30分钟)
+- [ ] 自检清单：
+  - [ ] API路径正确性
+  - [ ] 字段映射完整性
+  - [ ] 必填/可选字段区分正确
+  - [ ] 错误场景覆盖
+- [ ] 如有疑问，联系后端开发人员确认
+
+**Step 3: 设计文档归档**
+- [ ] 将设计文档提交到 Git
+- [ ] 提交信息: `docs: add design doc for <service> <resource> <action>`
+
+#### Phase 2: 开发阶段
+
+**Step 4: 接口契约确认** (预估: 15分钟)
+```bash
+# 使用curl或Postman测试后端接口
+curl -X POST https://<env>/api/enterprise/sales/salesOrder/add \
+  -H "Authorization: <token>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "clientCode": "TEST001",
+    "clientName": "测试客户",
+    "materialNo": "MAT001",
+    "purchaseNumber": 100
+  }'
+```
+- [ ] 确认接口可达
+- [ ] 确认认证方式
+- [ ] 记录实际响应格式
+
+**Step 5: 类型定义** (预估: 20-30分钟)
+- [ ] 在 `src/types/api.ts` 添加 TypeScript 接口
+- [ ] 在 `src/core/api/<service>-client.ts` 添加方法签名
+- [ ] 输出示例:
+```typescript
+// src/types/api.ts
+export interface CreateSalesOrderRequest {
+  clientCode: string;
+  clientName: string;
+  materialNo: string;
+  purchaseNumber: number;
+  deliveryDate?: string;
+}
+
+export interface SalesOrderResponse {
+  salesOrderId: number;
+  salesOrderCode: string;
+  // ...
+}
+
+// src/core/api/liberica-client.ts
+async createOrder(data: CreateSalesOrderRequest): Promise<SalesOrderResponse>
+```
+
+**Step 6: 核心实现** (预估: 30-60分钟)
+- [ ] 创建命令文件: `src/commands/<service>/<resource>/<action>.ts`
+- [ ] 实现命令逻辑:
+  ```typescript
+  export async function createOrderAction(options: CreateOrderOptions): Promise<void> {
+    // 1. 获取API客户端
+    const api = await ContextAwareAPIFactory.getLibericaClient();
+    
+    // 2. 构建请求参数
+    const request: CreateSalesOrderRequest = {
+      clientCode: options.clientCode,
+      clientName: options.clientName,
+      // ...
+    };
+    
+    // 3. 执行API调用（支持dry-run）
+    const result = await api.createOrder(request, options.dryRun);
+    
+    // 4. 格式化输出
+    formatOutput(result, { command: 'liberica orders create' });
+  }
+  ```
+- [ ] 注册命令: 在 `src/commands/<service>/<resource>/index.ts` 注册
+
+**Step 7: 错误处理** (预估: 20-30分钟)
+- [ ] 实现错误捕获和转换
+- [ ] 映射后端错误码到友好提示
+- [ ] 添加错误修复建议
+- [ ] 示例:
+```typescript
+try {
+  await api.createOrder(request);
+} catch (error) {
+  if (error.code === 'SALES_ORDER_CODE_DUPLICATE') {
+    throw new CLIError(
+      '订单编码已存在',
+      'DUPLICATE_CODE',
+      { fix: '请使用不同的编码或使用 --code 参数指定' }
+    );
+  }
+  // ...
+}
+```
+
+#### Phase 3: 验证阶段
+
+**Step 8: 单元测试** (预估: 30-45分钟)
+- [ ] 创建测试文件: `tests/unit/commands/<service>/<resource>-<action>.test.ts`
+- [ ] 测试场景:
+  - [ ] 正常创建
+  - [ ] 缺少必填参数
+  - [ ] 无效参数值
+  - [ ] dry-run模式
+  - [ ] 错误响应处理
+
+**Step 9: 集成测试** (预估: 20-30分钟)
+```bash
+# 在dev环境测试
+barista context use-env dev
+barista auth login --service liberica --env dev --tenant companya
+
+# 测试命令
+barista liberica orders create \
+  --client-code TEST001 \
+  --client-name "测试客户" \
+  --product-id MAT001 \
+  --quantity 100 \
+  --dry-run
+
+# 确认dry-run输出正确后，实际执行
+barista liberica orders create \
+  --client-code TEST001 \
+  --client-name "测试客户" \
+  --product-id MAT001 \
+  --quantity 100
+```
+- [ ] 记录测试证据（截图或输出）
+- [ ] 保存到: `.sisyphus/evidence/<command>-test.md`
+
+**Step 10: Code Review** (预估: 15-30分钟)
+- [ ] 自检清单:
+  - [ ] 代码符合项目规范（ESLint通过）
+  - [ ] 类型定义完整
+  - [ ] 错误处理完善
+  - [ ] 文档注释清晰
+- [ ] 提交PR，指派Reviewer
+
+**Step 11: 合并与发布**
+- [ ] 通过CI/CD检查
+- [ ] 合并到main分支
+- [ ] 更新CHANGELOG
+
+### 5.3 开发检查清单
+
+#### 实现前检查
+- [ ] 设计文档已编写并评审通过
+- [ ] 后端接口已确认可用
+- [ ] DTO字段已与后端对齐
+
+#### 实现中检查
+- [ ] 使用设计文档中的字段映射
+- [ ] 参数验证与后端一致
+- [ ] 支持 `--dry-run`（如适用）
+- [ ] 错误处理覆盖已知场景
+
+#### 实现后检查
+- [ ] 单元测试通过率 100%
+- [ ] 集成测试通过
+- [ ] 文档已更新
+- [ ] CHANGELOG已更新
+
+### 5.4 时间估算参考
+
+| 步骤 | 预估时间 | 备注 |
+|------|---------|------|
+| 设计文档 | 30-60min | 复杂命令需要更长时间 |
+| 类型定义 | 20-30min | 依赖DTO复杂度 |
+| 核心实现 | 30-60min | 简单CRUD较快 |
+| 错误处理 | 20-30min | 需要查看Service代码 |
+| 单元测试 | 30-45min | TDD可合并到实现中 |
+| 集成测试 | 20-30min | 需要真实环境 |
+| Code Review | 15-30min | 包含修改时间 |
+| **总计** | **2.5-5h** | 简单命令约2.5h，复杂命令约5h |
+
+### 5.5 交付物清单
+
+每个命令开发完成后，必须包含：
+
+```
+deliverables/
+├── docs/commands/<service>/<resource>-<action>.md    # 设计文档
+├── src/
+│   ├── commands/<service>/<resource>/<action>.ts     # 命令实现
+│   ├── types/api.ts                                  # 类型定义（更新）
+│   └── core/api/<service>-client.ts                  # API客户端（更新）
+├── tests/
+│   └── unit/commands/<service>/<resource>-<action>.test.ts  # 单元测试
+└── .sisyphus/evidence/
+    └── <resource>-<action>-test.md                   # 集成测试证据
+```
+
+---
+
+## 6. 示例：完整设计文档
+
+### 6.1 示例：liberica auth login 命令
+
+#### 命令元数据
+
+| 字段 | 值 |
+|------|-----|
+| 完整命令 | `barista liberica auth login` |
+| 功能描述 | 登录 Liberica 租户账户 |
+| HTTP方法 | POST |
+| 是否需要认证 | ⬜ 否（登录接口无需认证） |
+| 是否支持dry-run | ⬜ 否（登录操作不适合dry-run） |
+
+#### 后端接口引用
+
+**Controller位置：**
+```
+coffee-liberica-end/
+└── facade/liberica-facade-auth/
+    └── src/main/java/com/newpeak/liberica/facade/auth/
+        └── controller/AuthController.java
+            └── login(@PostResource(path = "/login"))
+                └── public ResponseData<LoginResponse> login(
+                        @RequestBody AuthLoginRequest request
+                    )
+```
+
+**Request DTO：**
+```
+coffee-liberica-end/
+└── business/liberica-business-auth/auth-api/
+    └── src/main/java/com/newpeak/liberica/auth/api/pojo/request/
+        └── AuthLoginRequest.java
+            ├── username: String (@NotBlank)
+            ├── password: String (@NotBlank)
+            └── tenant: String
+```
+
+**Response DTO：**
+```
+coffee-liberica-end/
+└── business/liberica-business-auth/auth-api/
+    └── src/main/java/com/newpeak/liberica/auth/api/pojo/response/
+        └── LoginResponse.java
+            ├── token: String
+            └── expiresAt: String (optional)
+```
+
+#### CLI参数设计
+
+**命令结构：**
+```
+barista liberica auth login [env] [tenant] [username] [password] [options]
+```
+
+**Arguments (位置参数)：**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| env | string | ⬜ | 目标环境 (dev\|test\|prod-cn\|prod-jp) |
+| tenant | string | ⬜ | 租户名称 |
+| username | string | ⬜ | 用户名 |
+| password | string | ⬜ | 密码 |
+
+**Options (选项参数)：**
+| 选项 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| --env | string | ⬜ | 当前上下文 | 目标环境 |
+| --tenant | string | ⬜ | 当前上下文 | 租户名称 |
+| --username | string | ⬜ | 交互输入 | 用户名 |
+| --password | string | ⬜ | 交互输入 | 密码 |
+
+#### 字段映射表
+
+| CLI参数 | DTO字段 | 类型转换 | 验证规则 |
+|---------|---------|----------|----------|
+| --tenant | tenant | 直接传递 | 可选 |
+| --username | username | 直接传递 | @NotBlank |
+| --password | password | 直接传递 | @NotBlank |
+
+#### 错误码引用
+
+**Service层业务校验：**
+```
+coffee-liberica-end/
+└── business/liberica-business-auth/auth-business/
+    └── src/main/java/com/newpeak/liberica/auth/modular/business/
+        └── AuthBusiness.java
+            └── login(AuthLoginRequest request)
+                ├── Line 45: 验证用户是否存在
+                │   └── throw new AuthException(AuthExceptionEnum.USER_NOT_EXIST)
+                └── Line 62: 验证密码是否正确
+                    └── throw new AuthException(AuthExceptionEnum.PASSWORD_ERROR)
+```
+
+**已知错误码：**
+| 错误码 | 错误消息 | 触发条件 |
+|--------|----------|----------|
+| USER_NOT_EXIST | 用户不存在 | 用户名未注册 |
+| PASSWORD_ERROR | 密码错误 | 密码不匹配 |
+
+#### 公开接口声明
+
+```yaml
+public_endpoints:
+  - service: "liberica"
+    path: "/api/v1/auth/login"
+```
+
+#### 实现要点
+
+1. **交互式补全**：tenant/username/password 未提供时，使用 inquirer 交互输入
+2. **Token存储**：登录成功后调用 `tokenManager.setToken()` 存入系统密钥链
+3. **上下文更新**：调用 `configManager.setTenant()` 更新默认租户
+4. **错误处理**：区分网络错误和业务错误，业务错误显示友好提示
+
+#### 实现代码
+
+```typescript
+// src/commands/liberica/auth/index.ts
+export function createLibericaAuthCommand(): Command {
+  const authCommand = new Command('auth');
+  authCommand.description('Manage Liberica authentication');
+
+  authCommand
+    .command('login')
+    .description('Login to Liberica')
+    .arguments('<env> [tenant] [username] [password]')
+    .option('--env <environment>', 'Environment (dev|test|prod-cn|prod-jp)')
+    .option('--tenant <tenant>', 'Tenant name')
+    .option('--username <username>', 'Username')
+    .option('--password <password>', 'Password')
+    .action(async (env, tenant, username, password, options) => {
+      const context = configManager.getCurrentContext();
+      const environment = (options.env as Environment) || env || context.environment;
+      let resolvedTenant = options.tenant || tenant || context.tenant;
+
+      if (!resolvedTenant) {
+        const { tenant: inputTenant } = await inquirer.prompt([
+          { type: 'input', name: 'tenant', message: 'Enter tenant name:' }
+        ]);
+        resolvedTenant = inputTenant;
+      }
+
+      let resolvedUsername = options.username || username;
+      let resolvedPassword = options.password || password;
+
+      if (!resolvedUsername) {
+        const { username: inputUsername } = await inquirer.prompt([
+          { type: 'input', name: 'username', message: 'Enter username:' }
+        ]);
+        resolvedUsername = inputUsername;
+      }
+
+      if (!resolvedPassword) {
+        const { password: inputPassword } = await inquirer.prompt([
+          { type: 'password', name: 'password', message: 'Enter password:' }
+        ]);
+        resolvedPassword = inputPassword;
+      }
+
+      const response = await apiClient.login('liberica', environment, resolvedTenant, resolvedUsername, resolvedPassword);
+
+      if (response.success && response.data) {
+        await tokenManager.setToken(
+          { service: 'liberica', environment, tenant: resolvedTenant },
+          response.data.token
+        );
+        await configManager.setTenant(resolvedTenant);
+        console.log(chalk.green('\n✓ Login successful'));
+      } else {
+        console.error(chalk.red(`\n✗ Login failed: ${response.error?.message}\n`));
+        process.exit(1);
+      }
+    });
+
+  return authCommand;
+}
+```
+
+**调用方式：**
+```bash
+# 全位置参数
+barista liberica auth login dev shanghai admin pass
+
+# 全选项参数
+barista liberica auth login --env dev --tenant shanghai --username admin --password pass
+
+# 混合
+barista liberica auth login dev --username admin --password pass
+
+# 交互式
+barista liberica auth login
+```
+
+---
+
+### 6.2 示例：liberica context show 命令
+
+#### 命令元数据
+
+| 字段 | 值 |
+|------|-----|
+| 完整命令 | `barista liberica context show` |
+| 功能描述 | 显示当前 Liberica 上下文 |
+| HTTP方法 | 无（仅读取本地配置） |
+| 是否需要认证 | ⬜ 否 |
+| 是否支持dry-run | ⬜ 否 |
+
+#### 实现要点
+
+1. **无API调用**：仅读取 `configManager.getCurrentContext()` 和 `tokenManager.getToken()`
+2. **Token状态检查**：检查密钥链中是否存在有效Token
+3. **格式化输出**：使用 chalk 彩色输出当前环境、租户、认证状态
+
+#### 实现代码
+
+```typescript
+// src/commands/liberica/context/index.ts
+export function createLibericaContextCommand(): Command {
+  const contextCommand = new Command('context');
+  contextCommand.description('Manage Liberica context (tenant, environment)');
+
+  contextCommand
+    .command('show')
+    .description('Show current Liberica context')
+    .action(async () => {
+      const context = configManager.getCurrentContext();
+      const token = await tokenManager.getToken({
+        service: 'liberica',
+        environment: context.environment,
+        tenant: context.tenant,
+      });
+
+      console.log(chalk.bold('\n📋 Liberica Context\n'));
+      console.log(`  ${chalk.gray('Environment:')} ${chalk.green(context.environment)}`);
+      console.log(`  ${chalk.gray('Tenant:')} ${chalk.green(context.tenant)}`);
+      console.log(
+        `  ${chalk.gray('Auth Status:')} ${token ? chalk.green('✓ Logged in') : chalk.red('✗ Not logged in')}`
+      );
+    });
+
+  return contextCommand;
+}
+```
+
+---
+
+### 6.3 模式总结
+
+| 命令类型 | 特征 | 实现模式 |
+|----------|------|----------|
+| **认证类** (login, logout) | 调用API、存储Token | 使用 `apiClient.login()` + `tokenManager.setToken()` |
+| **状态类** (status, show) | 读取配置/密钥链 | 使用 `configManager` + `tokenManager.getToken()` |
+| **列表类** (list) | 调用API、表格输出 | 使用 `axios.get()` + `cli-table3` |
+| **写入类** (create, update, delete) | 调用API、支持dry-run | API调用 + dry-run预览 + 确认提示 |
+
+#### 核心模块依赖
+
+```
+src/
+├── core/
+│   ├── config/manager.ts      # 配置管理 (getCurrentContext, setTenant, getEnvironmentUrl)
+│   ├── auth/token-manager.ts  # Token存储 (getToken, setToken, deleteToken, findAllTokens)
+│   └── api/client.ts          # API客户端 (login, createAPIClient)
+│   └── types/index.ts         # 类型定义 (Environment, Service, Context, Config)
+└── commands/
+    └── {service}/
+        └── {resource}.ts      # 命令实现
+```
+
+#### 导入路径规范
+
+```typescript
+import { configManager } from '../../../core/config/manager.js';
+import { tokenManager } from '../../../core/auth/token-manager.js';
+import { apiClient } from '../../../core/api/client.js';
+import { Environment } from '../../../types/index.js';
+```
+
+**注意**：必须使用 `.js` 扩展名，即使源文件是 `.ts`