@newpeak/barista-cli 0.1.0

package/docs/commands/arabica/auth/index.md

@@ -0,0 +1,296 @@
+# arabica auth
+
+Manage Arabica authentication.
+
+## Overview
+
+The `arabica auth` command group provides authentication management for the Arabica sales platform. Arabica is a single-tenant SaaS platform, which means it does not require tenant context like Liberica. Authentication uses the standard `POST /api/login` endpoint for login and `POST /api/member/user/register` for user registration.
+
+Key differences from Liberica authentication:
+
+- **No tenant concept**: Arabica operates as a single-tenant platform
+- **Account-based login**: Uses account (username or email) instead of username/tenant pair
+- **Registration support**: Includes user registration functionality
+- **Remember me option**: Supports persistent login sessions
+
+## Commands
+
+### login
+
+Login to Arabica with account credentials.
+
+**Usage:**
+```
+barista arabica auth login [env] [account] [password] [options]
+```
+
+**Arguments:**
+
+| Argument | Type | Required | Description |
+|----------|------|----------|-------------|
+| env | string | No | Target environment (dev\|test\|prod-cn\|prod-jp) |
+| account | string | No | Account username or email |
+| password | string | No | Account password |
+
+**Options:**
+
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| --env | string | No | Current context | Target environment |
+| --account | string | No | Interactive input | Account username or email |
+| --password | string | No | Interactive input | Account password |
+| --remember | boolean | No | false | Remember login status |
+
+**Examples:**
+
+Interactive mode (all fields prompted):
+```bash
+barista arabica auth login
+```
+
+With positional arguments:
+```bash
+barista arabica auth login dev user@example.com mypassword
+```
+
+With options:
+```bash
+barista arabica auth login --env dev --account user@example.com --password mypassword --remember
+```
+
+Mixed (positional + options):
+```bash
+barista arabica auth login dev --account user@example.com --password mypassword
+```
+
+**API Endpoint:**
+- **Method**: `POST /api/login`
+- **Body**: `{ account: string, password: string, rememberMe: boolean }`
+- **Response**: `{ success: boolean, data: { token: string, expiresAt?: string } }`
+
+**Error Handling:**
+
+| Error Code | Description | Trigger Condition |
+|------------|-------------|-------------------|
+| INVALID_CREDENTIALS | Invalid account or password | Wrong account/password combination |
+| ACCOUNT_LOCKED | Account is locked | Multiple failed login attempts |
+| NETWORK_ERROR | Network connection failed | Cannot reach Arabica server |
+
+**Implementation Notes:**
+- Interactive prompts use `inquirer` for secure password input (masked)
+- Successful login stores token via `tokenManager.setToken()` in system keychain
+- Token format in keychain: `arabica:{environment}` (no tenant component)
+- The `--remember` flag extends token validity on the server side
+
+---
+
+### register
+
+Register a new Arabica account.
+
+**Usage:**
+```
+barista arabica auth register [options]
+```
+
+**Options:**
+
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| --env | string | No | Current context | Target environment |
+| --email | string | No | Interactive input | Email address |
+| --account | string | No | Interactive input | Account username |
+| --password | string | No | Interactive input | Account password |
+| --phone | string | No | Interactive input | Phone number (optional) |
+
+**Examples:**
+
+Interactive mode (all fields prompted):
+```bash
+barista arabica auth register
+```
+
+With all options:
+```bash
+barista arabica auth register \
+  --env dev \
+  --email newuser@example.com \
+  --account newuser \
+  --password mypassword \
+  --phone "+86 13800138000"
+```
+
+Minimal registration (prompts for missing fields):
+```bash
+barista arabica auth register --email newuser@example.com --account newuser
+```
+
+**API Endpoint:**
+- **Method**: `POST /api/member/user/register`
+- **Body**: `{ email: string, account: string, password: string, phone?: string }`
+- **Response**: `{ success: boolean, data: { userId?: string } }`
+
+**Error Handling:**
+
+| Error Code | Description | Trigger Condition |
+|------------|-------------|-------------------|
+| EMAIL_EXISTS | Email already registered | Duplicate email address |
+| ACCOUNT_EXISTS | Account username taken | Duplicate account name |
+| INVALID_EMAIL | Invalid email format | Email format validation failed |
+| WEAK_PASSWORD | Password too weak | Password does not meet requirements |
+
+**Implementation Notes:**
+- Email and account are both required and must be unique
+- Phone number is optional but recommended for account recovery
+- After successful registration, user must login separately to obtain token
+- Registration does not automatically authenticate the user
+
+---
+
+### status
+
+Check Arabica authentication status across all environments.
+
+**Usage:**
+```
+barista arabica auth status
+```
+
+**Output:**
+```
+🔐 Arabica Authentication Status
+
+  ✓ arabica (dev): Logged in
+  ✗ arabica (test): Not logged in
+  ✗ arabica (prod-cn): Not logged in
+  ✗ arabica (prod-jp): Not logged in
+```
+
+**Implementation Notes:**
+- Checks all four environments (dev, test, prod-cn, prod-jp)
+- Uses `tokenManager.getToken({ service: 'arabica', environment })` for each environment
+- No tenant component in token key since Arabica is single-tenant
+- Output uses chalk for colored status indicators (green checkmark for logged in, red X for not logged in)
+
+---
+
+### logout
+
+Logout from Arabica and clear stored tokens.
+
+**Usage:**
+```
+barista arabica auth logout [options]
+```
+
+**Options:**
+
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| --env | string | No | Current context | Target environment to logout from |
+| --all | boolean | No | false | Clear all Arabica tokens across environments |
+
+**Examples:**
+
+Logout from current environment:
+```bash
+barista arabica auth logout
+```
+
+Logout from specific environment:
+```bash
+barista arabica auth logout --env dev
+```
+
+Logout from all environments:
+```bash
+barista arabica auth logout --all
+```
+
+**Implementation Notes:**
+- Without `--all`, clears token for the specified (or current) environment only
+- With `--all`, iterates through all credentials in keychain and deletes those with `arabica:*` prefix
+- Uses `tokenManager.deleteToken()` for single environment logout
+- Uses `tokenManager.findAllTokens()` and filters by service name for `--all` logout
+
+---
+
+## Arabica vs Liberica Comparison Table
+
+| Feature | Arabica Auth | Liberica Auth |
+|---------|--------------|---------------|
+| **Platform Type** | Single-tenant SaaS | Multi-tenant SaaS |
+| **Tenant Required** | No | Yes (required) |
+| **Login Identifier** | Account (username/email) | Username + Tenant |
+| **Registration** | Supported | Not supported (admin only) |
+| **Remember Me** | Supported | Not supported |
+| **Token Key Format** | `arabica:{environment}` | `liberica:{environment}:{tenant}` |
+| **Login Endpoint** | `POST /api/login` | `POST /api/enterprise/loginApi` |
+| **Register Endpoint** | `POST /api/member/user/register` | N/A |
+
+## File Structure
+
+```
+src/commands/arabica/auth/
+├── index.ts      # Main auth command with login, register, status, logout implementations
+├── login.ts      # Login command factory (stub for future expansion)
+├── register.ts   # Register command factory (stub for future expansion)
+├── status.ts     # Status command factory (stub for future expansion)
+└── logout.ts     # Logout command factory (stub for future expansion)
+```
+
+**Implementation Pattern:**
+
+All four subcommands are implemented directly in `index.ts` using Commander.js `.command()` chaining. The individual files (`login.ts`, `register.ts`, `status.ts`, `logout.ts`) export factory functions that create empty Command instances for potential future refactoring.
+
+```typescript
+// index.ts pattern
+authCommand
+  .command('login')
+  .description('Login to Arabica')
+  .arguments('<env> [account] [password]')
+  .option('--env <environment>', 'Environment')
+  .option('--account <account>', 'Account')
+  .option('--password <password>', 'Password')
+  .option('--remember', 'Remember login status')
+  .action(async (env, account, password, options) => {
+    // Implementation
+  });
+```
+
+## Unit Tests
+
+Test file: `tests/unit/commands/arabica/auth.test.ts`
+
+**Test Coverage:**
+
+| Test Case | Description |
+|-----------|-------------|
+| Command creation | Verifies auth command is created with correct name and description |
+| Login subcommand | Tests login command existence, description, and all options (--env, --account, --password, --remember) |
+| Register subcommand | Tests register command existence, description, and all options (--env, --email, --account, --password, --phone) |
+| Status subcommand | Tests status command existence, description, and zero options |
+| Logout subcommand | Tests logout command existence, description, and options (--env, --all) |
+| No tenant option | Verifies Arabica login does NOT have --tenant option (unlike Liberica) |
+| Integration mocks | Verifies apiClient and tokenManager methods are called correctly |
+
+**Mock Strategy:**
+
+```typescript
+// Key modules are mocked for unit testing
+vi.mock('../../../../src/core/config/manager.js');
+vi.mock('../../../../src/core/auth/token-manager.js');
+vi.mock('../../../../src/core/api/client.js');
+vi.mock('chalk');
+vi.mock('inquirer');
+```
+
+**Running Tests:**
+
+```bash
+# Run all Arabica auth tests
+npm test -- tests/unit/commands/arabica/auth.test.ts
+
+# Run with coverage
+npm run test:coverage -- tests/unit/commands/arabica/auth.test.ts
+```

package/docs/commands/liberica/auth/index.md

@@ -0,0 +1,133 @@
+# liberica auth
+
+管理 Liberica 租户身份认证。
+
+## Commands
+
+### login
+
+登录 Liberica 租户账户。
+
+**Usage:**
+```
+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 | ⬜ | 交互输入 | 密码 |
+
+**Examples:**
+
+Interactive mode (all args prompted):
+```bash
+barista liberica auth login
+```
+
+With positional arguments:
+```bash
+barista liberica auth login dev shanghai admin@shanghai.newpeaksh.com 123456
+```
+
+With options:
+```bash
+barista liberica auth login --env dev --tenant shanghai --username admin@shanghai.newpeaksh.com --password 123456
+```
+
+Mixed (positional + options):
+```bash
+barista liberica auth login dev --tenant shanghai --username admin@shanghai.newpeaksh.com --password 123456
+```
+
+**API:**
+- Endpoint: `POST /api/v1/auth/login`
+- Body: `{ username, password, tenant, service, environment }`
+- Response: `{ success: true, data: { token, expiresAt } }`
+
+**Error Codes:**
+| 错误码 | 错误消息 | 触发条件 |
+|--------|----------|----------|
+| USER_NOT_EXIST | 用户不存在 | 用户名未注册 |
+| PASSWORD_ERROR | 密码错误 | 密码不匹配 |
+| NETWORK_ERROR | 网络错误 | 无法连接到服务器 |
+
+**Implementation Notes:**
+- 交互式补全：tenant/username/password 未提供时使用 inquirer 交互输入
+- Token存储：成功登录后调用 `tokenManager.setToken()` 存入系统密钥链
+- 上下文更新：调用 `configManager.setTenant()` 更新默认租户
+
+---
+
+### status
+
+检查 Liberica 认证状态。
+
+**Usage:**
+```
+barista liberica auth status
+```
+
+**Output:**
+```
+🔐 Liberica Authentication Status
+
+  ✓ liberica (electionjp) (dev): Logged in
+  ✗ liberica (electionjp) (test): Not logged in
+  ✗ liberica (electionjp) (prod-cn): Not logged in
+  ✗ liberica (electionjp) (prod-jp): Not logged in
+```
+
+**Implementation Notes:**
+- 遍历所有环境检查 Token 状态
+- 使用 `tokenManager.getToken()` 检查密钥链
+
+---
+
+### logout
+
+登出并清除 Token。
+
+**Usage:**
+```
+barista liberica auth logout [options]
+```
+
+**Options:**
+| 选项 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| --env | string | ⬜ | 当前上下文 | 目标环境 |
+| --all | boolean | ⬜ | false | 清除所有 Liberica Token |
+
+**Examples:**
+
+Logout current environment:
+```bash
+barista liberica auth logout --env dev
+```
+
+Logout all environments:
+```bash
+barista liberica auth logout --all
+```
+
+**Implementation Notes:**
+- 使用 `tokenManager.deleteToken()` 删除指定环境的 Token
+- 使用 `tokenManager.findAllTokens()` 遍历所有 Token
+
+---
+
+## Design Reference
+
+完整设计文档见：[命令设计规范](../../COMMAND_DESIGN_SPEC.md#61-示例liberica-auth-login-命令)

package/docs/commands/liberica/context/index.md

@@ -0,0 +1,60 @@
+# liberica context
+
+管理 Liberica 上下文（租户、环境）。
+
+## Commands
+
+### show
+
+显示当前 Liberica 上下文。
+
+**Usage:**
+```
+barista liberica context show
+```
+
+**Output:**
+```
+📋 Liberica Context
+
+  Environment: dev
+  Tenant: electionjp
+  Auth Status: ✓ Logged in
+```
+
+**Implementation Notes:**
+- 无 API 调用，仅读取本地配置
+- 使用 `configManager.getCurrentContext()` 获取当前上下文
+- 使用 `tokenManager.getToken()` 检查认证状态
+
+---
+
+### use-enterprise
+
+切换 Liberica 租户。
+
+**Usage:**
+```
+barista liberica context use-enterprise <tenant>
+```
+
+**Arguments:**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| tenant | string | ✅ | 租户名称 |
+
+**Examples:**
+```bash
+barista liberica context use-enterprise electionjp
+barista liberica context use-enterprise newtenant
+```
+
+**Implementation Notes:**
+- 使用 `configManager.setTenant()` 更新默认租户
+- 租户变更后不影响当前已存储的 Token
+
+---
+
+## Design Reference
+
+完整设计文档见：[命令设计规范](../../COMMAND_DESIGN_SPEC.md#62-示例liberica-context-show-命令)

package/docs/commands/liberica/employees/create.md

@@ -0,0 +1,185 @@
+# barista liberica employees create
+
+创建新员工。
+
+## 2.1 命令元数据
+
+| 字段 | 值 |
+|------|-----|
+| 完整命令 | `barista liberica employees create` |
+| 功能描述 | 创建新员工 |
+| HTTP方法 | POST |
+| 是否需要认证 | ✅ 是 |
+| 是否支持dry-run | ✅ 是 |
+
+## 2.2 后端接口引用
+
+### Controller位置
+```
+coffee-liberica-end/
+└── facade/liberica-facade-enterprise/
+    └── src/main/java/com/newpeak/liberica/facade/enterprise/controller/master/
+        └── EnterpriseEmployeeController.java
+            └── add(@PostResource(path = "/add", requiredPermission = true, requirePermissionCode = "ADD_EMPLOYEE"))
+                └── public ResponseData<MasterEmployeeResponse> add(
+                        @RequestHeader("X-TENANT-ID") Long tenantId,
+                        @RequestBody @Validated(BaseRequest.add.class) MasterEmployeeRequest request
+                    )
+```
+
+### Request DTO位置
+```
+coffee-liberica-end/
+└── business/liberica-business-master/master-api/
+    └── src/main/java/com/newpeak/liberica/master/api/pojo/request/
+        └── MasterEmployeeRequest.java
+            ├── employeeCode: String (@NotBlank on add)
+            ├── employeeName: String (@NotBlank on add)
+            ├── employeeNo: String (@NotBlank on add)
+            ├── employeePhone: String
+            ├── employeeEmail: String
+            ├── employeeSex: SexEnum (M/F)
+            ├── employeeIdType: String
+            ├── employeeIdNo: String
+            ├── employeeJoinedDate: Date
+            ├── employeeBirthday: Date
+            ├── organizationId: Long
+            ├── organizationManagerFlag: String
+            ├── positionId: String
+            ├── jobType: String
+            ├── jobLevelNo: Integer
+            ├── evaluator1: String
+            ├── evaluator2: String
+            ├── coach: String
+            ├── employeeBankAccount: String
+            └── employeeDepositBank: String
+```
+
+### Response DTO位置
+```
+coffee-liberica-end/
+└── business/liberica-business-master/master-api/
+    └── src/main/java/com/newpeak/liberica/master/api/pojo/response/
+        └── MasterEmployeeResponse.java
+            ├── employeeId: Long
+            ├── employeeCode: String
+            ├── employeeName: String
+            ├── employeeNo: String
+            ├── employeePhone: String
+            ├── employeeEmail: String
+            ├── employeeSex: SexEnum
+            ├── organizationId: Long
+            ├── orgName: String
+            ├── positionId: String
+            ├── positionName: String
+            ├── statusFlag: Integer (1=enable, 2=disable)
+            └── createTime: String
+```
+
+## 2.3 CLI参数设计
+
+### 命令结构
+```
+barista liberica employees create [options]
+```
+
+### 全局选项
+| 选项 | 类型 | 说明 |
+|------|------|------|
+| `--env` | string | 目标环境(dev\|test\|prod-cn\|prod-jp) |
+| `--tenant` | string | 租户代码 |
+| `--dry-run` | boolean | 预览模式（不实际调用API） |
+| `--json` | boolean | JSON输出 |
+
+### 命令选项
+| 选项 | 短选项 | 类型 | 必填 | 默认值 | 说明 | 对应DTO字段 |
+|------|--------|------|------|--------|------|-------------|
+| --name | -n | string | ✅ | - | 员工姓名 | employeeName |
+| --code | -c | string | ⬜ | 空（自动生成） | 员工编码 | employeeCode |
+| --phone | -p | string | ⬜ | - | 手机号码 | employeePhone |
+| --email | -e | string | ⬜ | - | 电子邮箱 | employeeEmail |
+| --sex | -s | string | ⬜ | - | 性别 (M/F) | employeeSex |
+| --org-id | — | number | ⬜ | - | 部门ID | organizationId |
+| --position-id | — | string | ⬜ | - | 岗位ID | positionId |
+| --joined-date | -d | string | ⬜ | - | 入职日期 (YYYY-MM-DD) | employeeJoinedDate |
+
+## 2.4 字段映射表
+
+| CLI参数 | DTO字段 | 类型转换 | 验证规则 |
+|---------|---------|----------|----------|
+| --name / -n | employeeName | 直接传递 | @NotBlank, max=255 |
+| --code / -c | employeeCode | 直接传递 | 可选，为空则自动生成 |
+| --phone / -p | employeePhone | 直接传递 | 手机号格式 |
+| --email / -e | employeeEmail | 直接传递 | 邮箱格式 |
+| --sex / -s | employeeSex | 直接传递 | M 或 F |
+| --org-id | organizationId | string→Long | - |
+| --position-id | positionId | 直接传递 | - |
+| --joined-date / -d | employeeJoinedDate | string→Date | yyyy-MM-dd |
+
+**自动填充字段（不通过CLI参数）：**
+| 字段 | 值 |
+|------|-----|
+| tenantId | 来自 X-TENANT-ID header |
+| statusFlag | 默认 1 (启用) |
+| employeeNo | 必填，从 --no 参数获取或交互输入 |
+
+## 2.5 错误码引用
+
+### ExceptionEnum位置
+```
+coffee-liberica-end/
+└── business/liberica-business-master/master-api/
+    └── src/main/java/com/newpeak/liberica/master/api/exception/enums/
+        └── EmployeeExceptionEnum.java
+            ├── MASTER_EMPLOYEE_CODE_FORMAT_CANNOT_EMPTY("01001150003", "职员编码规则不能为空")
+            ├── MASTER_EMPLOYEE_CODE_FORMAT_NOT_CORRECT("01001150004", "职员编码规则格式不正确")
+            ├── MASTER_EMPLOYEE_CODE_VALIDATE_EMPTY_ERROR("01001150006", "{}不能为空")
+            └── MASTER_EMPLOYEE_CODE_VALIDATE_NOT_EXIST_ERROR("01001150007", "指定{}不存在")
+```
+
+### 已知错误码
+| 错误码 | 错误消息 | 触发条件 |
+|--------|----------|----------|
+| 01001150003 | 职员编码规则不能为空 | employeeCode 为空且系统未配置自动生成规则 |
+| 01001150006 | xxx不能为空 | 必填字段缺失 |
+
+## 2.6 权限检查
+
+| 检查项 | 位置 | 说明 |
+|--------|------|------|
+| PermissionConstants | `LibericaPermissionCodeConstants.ADD_EMPLOYEE` | Controller层 `@PostResource(requirePermissionCode = "ADD_EMPLOYEE")` |
+
+## 2.7 实现要点
+
+1. **必填字段**：--name 必须提供；employeeNo 通过位置参数或交互输入获取
+2. **自动生成编码**：employeeCode 为空时后端自动生成
+3. **Dry-run支持**：使用 --dry-run 时构造请求体但不发送，显示预览信息
+4. **默认statusFlag**：新建员工默认为启用状态(statusFlag=1)
+5. **tenantId来源**：来自 X-TENANT-ID header，不通过请求体传递
+
+## 2.8 示例用法
+
+```bash
+# 交互式创建（引导输入必填字段）
+barista liberica employees create
+
+# 指定姓名和必填字段
+barista liberica employees create --name "张三" --no "EMP001"
+
+# 完整选项
+barista liberica employees create \
+  --name "张三" \
+  --code "EMP001" \
+  --phone "13800138000" \
+  --email "zhangsan@example.com" \
+  --sex M \
+  --org-id 1001 \
+  --position-id "MANAGER" \
+  --joined-date 2024-01-15
+
+# Dry-run 预览
+barista liberica employees create --name "张三" --no "EMP001" --dry-run
+
+# JSON 输出
+barista liberica employees create --name "张三" --no "EMP001" --json
+```