@newpeak/barista-cli 0.1.0

package/docs/INTEGRATION_NOTES.md

@@ -0,0 +1,270 @@
+# Liberica API Integration Notes
+
+This document captures the lessons learned from integrating with the Liberica backend API.
+
+## Authentication
+
+### Authorization Header
+
+The API expects the token directly without `Bearer` prefix:
+
+```typescript
+// WRONG
+this.client.defaults.headers.common['Authorization'] = `Bearer ${token}`;
+
+// CORRECT
+this.client.defaults.headers.common['Authorization'] = token;
+```
+
+### Tenant Header (X-TENANT-ID)
+
+**IMPORTANT**: The `X-TENANT-ID` header is NOT required. The tenant is embedded in the JWT token.
+
+```typescript
+// WRONG - Backend expects Long but we pass String
+{ headers: { 'X-TENANT-ID': tenant } }
+
+// CORRECT - Don't pass X-TENANT-ID at all
+// Tenant is extracted from JWT token by the backend
+```
+
+Adding `X-TENANT-ID` with string tenant name causes `NumberFormatException: For input string: "shanghai"` because the backend expects a numeric tenant ID.
+
+## BigInteger IDs
+
+**CRITICAL**: Backend returns BigInteger for ID fields, which exceeds JavaScript's `number` range (max safe integer: 9007199254740991).
+
+**Always use `string` type for ID fields in TypeScript**:
+
+```typescript
+// WRONG - Precision loss for IDs > 9007199254740991
+interface Employee {
+  employeeId: number;  // Will lose precision!
+}
+
+// CORRECT - Use string for IDs
+interface Employee {
+  employeeId: string;
+}
+```
+
+### Affected Fields
+- `Employee.employeeId` - always use string
+- `Employee.organizationId` - always use string  
+- `UpdateEmployeeRequest.employeeId` - always use string
+- Any ID field from backend that is BigInteger
+
+## API Endpoints
+
+### Base URL Pattern
+```
+https://{tenant}-{env}.newpeaksh.com/api/...
+```
+
+### Required Prefix
+All endpoints require the `/api` prefix:
+```
+/api/enterprise/employee/page
+/api/enterprise/employee/add
+/api/enterprise/employee/edit
+/api/enterprise/employee/delete
+/api/enterprise/employee/deActive
+/api/enterprise/employee/active
+```
+
+### HTTP Methods
+Different endpoints use different HTTP methods:
+
+| Endpoint | Method | Notes |
+|----------|--------|-------|
+| `/employee/page` | GET | List with pagination |
+| `/employee/detail` | GET | Single item lookup |
+| `/employee/add` | POST | Create |
+| `/employee/edit` | POST | Update |
+| `/employee/delete` | POST | Delete |
+| `/employee/active` | POST | Enable |
+| `/employee/deActive` | POST | Disable |
+| `/master/org/tree` | POST | Get org list (POST required, not GET) |
+| `/master/position/list` | GET | Get position list |
+
+## Pagination
+
+### 0-Based Pagination
+The backend uses 0-based pagination (page starts at 0, not 1):
+
+```typescript
+// CLI page 1 -> API page 0
+const page = parseInt(options.page as string, 10) - 1;
+```
+
+### Query Parameters
+Use `pageNo` and `pageSize` (not `page` and `size`):
+
+```
+/api/enterprise/employee/page?pageNo=0&pageSize=20
+```
+
+## Response Field Names
+
+The backend uses different field names than typical conventions:
+
+| Backend Field | Standard Field | Description |
+|-------------|---------------|-------------|
+| `rows` | `records` | Array of items |
+| `pageNo` | `current` | Current page number |
+| `pageSize` | `size` | Items per page |
+| `totalRows` | `total` | Total item count |
+
+### Example Response
+```json
+{
+  "success": true,
+  "data": {
+    "pageNo": 1,
+    "pageSize": 20,
+    "totalRows": 19,
+    "totalPage": 1,
+    "rows": [...]
+  }
+}
+```
+
+## Error Response Format
+
+**IMPORTANT**: Backend error format varies - may be at top level OR nested under `error`:
+
+```typescript
+// Backend returns ONE of these formats:
+
+// Format 1: Error at top level (common for delete, enable, disable)
+{
+  "success": false,
+  "code": "A150001",
+  "message": "A150001: 查询结果不存在"
+}
+
+// Format 2: Error nested under 'error' object
+{
+  "success": false,
+  "error": {
+    "code": "01001150001",
+    "message": "职员不存在"
+  }
+}
+```
+
+### Handle in handleApiError():
+```typescript
+function handleApiError(error: unknown): EmployeeApiResponse {
+  if (axios.isAxiosError(error)) {
+    const responseData = axiosError.response?.data;
+    if (responseData) {
+      const success = responseData.success as boolean | undefined;
+      if (success === false) {
+        const code = responseData.code as string | undefined;
+        const message = responseData.message as string | undefined;
+        const errorObj = responseData.error as { code?: string; message?: string } | undefined;
+        if (!errorObj && (code || message)) {
+          return {
+            success: false,
+            error: {
+              code: code || 'API_ERROR',
+              message: message || 'API error occurred',
+            },
+          };
+        }
+      }
+      return responseData as EmployeeApiResponse;
+    }
+  }
+  // ...
+}
+```
+
+## Null Data Handling
+
+When the API returns no data, the `data` field may be:
+- `null`
+- Not present in the response
+
+Always check for null before accessing data fields:
+
+```typescript
+const data = response.data as EmployeeListResponse | null;
+
+if (!data) {
+  console.log('No data found');
+  return;
+}
+```
+
+## Error Codes
+
+| Code | Message | Cause |
+|------|---------|-------|
+| B0301 | TOKEN解析失败 | Invalid or expired token |
+| B0001 | 系统执行出错 | Internal server error (check exceptionTip) |
+| A150001 | 查询结果不存在 | Resource not found |
+| A1504 | 当前接口不支持GET方式请求 | Wrong HTTP method (should be POST) |
+
+## Common Issues
+
+### 1. Token Parsing Failed
+**Error**: `B0301: TOKEN解析失败，请重新登录`
+
+**Cause**: Token format issue or secret mismatch.
+
+**Solution**: Re-authenticate and ensure the token is passed without `Bearer` prefix.
+
+### 2. X-TENANT-ID Causing NumberFormatException
+**Error**: `NumberFormatException: For input string: "shanghai"`
+
+**Cause**: Passing `X-TENANT-ID` header with string tenant name. Backend expects numeric tenant ID or no header at all.
+
+**Solution**: Do NOT pass `X-TENANT-ID` header. Tenant is embedded in JWT token.
+
+### 3. Wrong HTTP Method
+**Error**: `A1504: 当前接口不支持GET方式请求`
+
+**Cause**: Using GET when endpoint requires POST (or vice versa).
+
+**Solution**: Check endpoint documentation for correct HTTP method.
+
+### 4. BigInteger Precision Loss
+**Symptom**: Employee IDs display as truncated in CLI, API calls fail with "not found" for valid IDs.
+
+**Cause**: ID is BigInteger > 9007199254740991, losing precision in JavaScript number.
+
+**Solution**: Use string type for all ID fields.
+
+### 5. Empty Results Despite Data
+**Cause**: Field name mismatch between client and API.
+
+**Solution**: Verify you are using the correct field names from the response, not assumed names.
+
+## Testing
+
+### Verify API Connection
+```bash
+# Login first
+node ./bin/barista.js liberica auth login dev <tenant> <email> <password>
+
+# Test list
+node ./bin/barista.js liberica employees list
+
+# Test with JSON output
+node ./bin/barista.js liberica employees list --json
+```
+
+### Debug API Calls
+Add temporary logging to see raw responses:
+```typescript
+console.error('DEBUG response:', JSON.stringify(response, null, 2));
+```
+
+## File Locations
+
+- API Client: `src/core/api/client.ts`
+- Types: `src/types/employee.ts`
+- Commands: `src/commands/liberica/employees/*.ts`
+- Config: `~/.barista/config.yaml`

package/docs/commands/REFERENCE.md

@@ -0,0 +1,297 @@
+# Barista CLI 命令参考
+
+> 基于实际业务需求整理的所有功能清单，按 Arabica（销售前端）和 Liberica（生产管理）分类。
+
+## 📊 命令统计总览
+
+| 服务 | 模块 | 命令数量 | 状态 | 优先级 |
+|------|------|---------|------|--------|
+| **Arabica** | auth | 4 | ✅ 已实现 | P0 |
+| **Arabica** | members | 3 | 📋 待开发 | P0 |
+| **Arabica** | enterprises | 3 | 📋 待开发 | P0 |
+| **Arabica** | products | 2 | 📋 待开发 | P1 |
+| **Arabica** | subscriptions | 4 | 📋 待开发 | P0 |
+| **Arabica** | access | 1 | 📋 待开发 | P0 |
+| **Liberica** | auth | 2 | ✅ 已实现 | P0 |
+| **Liberica** | context | 3 | ✅ 已实现 | P0 |
+| **Liberica** | users | 3 | 📋 待开发 | P1 |
+| **Liberica** | employees | 3 | 📋 待开发 | P1 |
+| **Liberica** | clients | 4 | 📋 待开发 | P0 |
+| **Liberica** | suppliers | 4 | 📋 待开发 | P0 |
+| **Liberica** | materials | 5 | 📋 待开发 | P0 |
+| **Liberica** | sales-prices | 4 | 📋 待开发 | P1 |
+| **Liberica** | purchase-prices | 4 | 📋 待开发 | P1 |
+| **Liberica** | sales-orders | 5 | 📋 待开发 | P0 |
+| **总计** | 16模块 | **47命令** | | |
+
+**状态说明**:
+- ✅ 已实现 - 功能已完成，可在 `src/commands/` 目录查看实现
+- 📋 待开发 - 功能已设计但尚未实现，需按设计规范开发
+
+---
+
+## 🌐 Arabica 命令（销售前端）
+
+> **用户**: 最终客户（潜在租户企业的代表）
+> **访问**: www.newpeaksh.com / members.newpeakjp.com
+
+### 1. auth（认证）- ✅ 已实现
+
+| 功能 | 命令 | HTTP | 说明 | 设计文档 |
+|------|------|------|------|----------|
+| 会员登录 | `barista arabica auth login [env] [account] [password]` | POST | 获取访问Token | [docs](./arabica/auth/index.md) |
+| 注册会员 | `barista arabica auth register [env] [email] [password] [phone] [username]` | POST | 新用户注册 | [docs](./arabica/auth/index.md) |
+| 获取登录状态 | `barista arabica auth status` | GET | 查看当前登录状态 | [docs](./arabica/auth/index.md) |
+| 登出 | `barista arabica auth logout` | - | 清除登录Token | [docs](./arabica/auth/index.md) |
+
+### 2. members（会员管理）- 📋 待开发
+
+| 功能 | 命令 | HTTP | 说明 | 设计文档 |
+|------|------|------|------|----------|
+| 注册会员 | `barista arabica members register` | POST | 新用户注册 | 待创建 |
+| 会员登录 | `barista arabica members login` | POST | 获取访问Token | 待创建 |
+| 获取会员信息 | `barista arabica members get` | GET | 查看当前会员详情 | 待创建 |
+
+### 3. enterprises（企业管理）- 📋 待开发
+
+| 功能 | 命令 | HTTP | 说明 | 设计文档 |
+|------|------|------|------|----------|
+| 注册企业 | `barista arabica enterprises register` | POST | 会员创建新企业 | 待创建 |
+| 获取企业列表 | `barista arabica enterprises list` | GET | 查看会员关联的所有企业 | 待创建 |
+| 获取企业详情 | `barista arabica enterprises get <id>` | GET | 查看企业详细信息 | 待创建 |
+
+### 4. products（产品浏览）- 📋 待开发
+
+| 功能 | 命令 | HTTP | 说明 | 设计文档 |
+|------|------|------|------|----------|
+| 查询产品列表 | `barista arabica products list` | GET | 浏览可购买的SaaS产品 | 待创建 |
+| 获取产品详情 | `barista arabica products get <id>` | GET | 查看产品详细信息 | 待创建 |
+
+### 5. subscriptions（服务订阅）- 📋 待开发
+
+| 功能 | 命令 | HTTP | 说明 | 设计文档 |
+|------|------|------|------|----------|
+| 申请产品试用 | `barista arabica subscriptions trial` | POST | 申请免费试用 | 待创建 |
+| 购买服务 | `barista arabica subscriptions purchase` | POST | 购买正式服务 | 待创建 |
+| 获取已购买服务 | `barista arabica subscriptions list` | GET | 查看所有订阅（含试用） | 待创建 |
+| 获取服务详情 | `barista arabica subscriptions get <id>` | GET | 查看订阅详情 | 待创建 |
+
+### 6. access（系统访问）- 📋 待开发
+
+| 功能 | 命令 | HTTP | 说明 | 设计文档 |
+|------|------|------|------|----------|
+| 获取Liberica访问URL | `barista arabica access url` | GET | 获取租户系统访问地址 | 待创建 |
+
+---
+
+## 🏭 Liberica 命令（生产管理）
+
+> **用户**: 租户企业内部员工
+> **访问**: {tenant}.newpeaksh.com / {tenant}.newpeakjp.com
+
+### 1. auth（认证）- ✅ 已实现
+
+| 功能 | 命令 | HTTP | 说明 | 设计文档 |
+|------|------|------|------|----------|
+| 租户企业账号登录 | `barista liberica auth login` | POST | 使用租户账号登录 | [docs](./liberica/auth/index.md) |
+| 获取登录状态 | `barista liberica auth status` | GET | 查看当前登录状态 | [docs](./liberica/auth/index.md) |
+
+### 2. context（上下文管理）- ✅ 已实现
+
+| 功能 | 命令 | 说明 | 设计文档 |
+|------|------|------|----------|
+| 显示当前上下文 | `barista context show` | 查看当前环境、租户、Token状态 | [docs](./liberica/context/index.md) |
+| 切换环境 | `barista context use-env [env]` | 切换操作的环境 | [docs](./liberica/context/index.md) |
+| 切换租户 | `barista context use-tenant <tenant>` | 切换操作的企业 | [docs](./liberica/context/index.md) |
+
+### 3. users（用户管理）- 📋 待开发
+
+| 功能 | 命令 | HTTP | 说明 | 设计文档 |
+|------|------|------|------|----------|
+| 创建新用户 | `barista liberica users create` | POST | 创建系统用户账号 | 待创建 |
+| 获取用户列表 | `barista liberica users list` | GET | 查看所有用户 | 待创建 |
+| 获取用户详情 | `barista liberica users get <id>` | GET | 查看用户信息 | 待创建 |
+
+### 4. employees（职员管理）- 📋 待开发
+
+| 功能 | 命令 | HTTP | 说明 | 设计文档 |
+|------|------|------|------|----------|
+| 创建新职员 | `barista liberica employees create` | POST | 添加企业员工 | 待创建 |
+| 获取职员列表 | `barista liberica employees list` | GET | 查看所有职员 | 待创建 |
+| 获取职员详情 | `barista liberica employees get <id>` | GET | 查看职员信息 | 待创建 |
+
+### 5. clients（客户管理）- 📋 待开发
+
+| 功能 | 命令 | HTTP | 说明 | 设计文档 |
+|------|------|------|------|----------|
+| 创建客户 | `barista liberica clients create` | POST | 添加下游客户 | 待创建 |
+| 获取客户列表 | `barista liberica clients list` | GET | 查看所有客户 | 待创建 |
+| 获取客户详情 | `barista liberica clients get <id>` | GET | 查看客户信息 | 待创建 |
+| 更新客户 | `barista liberica clients update <id>` | POST | 修改客户信息 | 待创建 |
+
+### 6. suppliers（供应商管理）- 📋 待开发
+
+| 功能 | 命令 | HTTP | 说明 | 设计文档 |
+|------|------|------|------|----------|
+| 创建供应商 | `barista liberica suppliers create` | POST | 添加上游供应商 | 待创建 |
+| 获取供应商列表 | `barista liberica suppliers list` | GET | 查看所有供应商 | 待创建 |
+| 获取供应商详情 | `barista liberica suppliers get <id>` | GET | 查看供应商信息 | 待创建 |
+| 更新供应商 | `barista liberica suppliers update <id>` | POST | 修改供应商信息 | 待创建 |
+
+### 7. materials（物料管理）- 📋 待开发
+
+| 功能 | 命令 | HTTP | 说明 | 设计文档 |
+|------|------|------|------|----------|
+| 创建物料 | `barista liberica materials create` | POST | 创建产品/原材料/半成品 | 待创建 |
+| 获取物料列表 | `barista liberica materials list` | GET | 查看所有物料 | 待创建 |
+| 获取物料详情 | `barista liberica materials get <id>` | GET | 查看物料信息 | 待创建 |
+| 搜索物料 | `barista liberica materials search` | GET | 按条件搜索物料 | 待创建 |
+| 更新物料 | `barista liberica materials update <id>` | POST | 修改物料信息 | 待创建 |
+
+### 8. sales-prices（销售价格）- 📋 待开发
+
+| 功能 | 命令 | HTTP | 说明 | 设计文档 |
+|------|------|------|------|----------|
+| 添加销售价格 | `barista liberica sales-prices create` | POST | 设置物料的销售价格 | 待创建 |
+| 查询销售价格 | `barista liberica sales-prices list` | GET | 查看销售价格列表 | 待创建 |
+| 获取价格详情 | `barista liberica sales-prices get <id>` | GET | 查看价格详情 | 待创建 |
+| 更新销售价格 | `barista liberica sales-prices update <id>` | POST | 修改销售价格 | 待创建 |
+
+### 9. purchase-prices（采购价格）- 📋 待开发
+
+| 功能 | 命令 | HTTP | 说明 | 设计文档 |
+|------|------|------|------|----------|
+| 添加采购价格 | `barista liberica purchase-prices create` | POST | 设置物料的采购价格 | 待创建 |
+| 查询采购价格 | `barista liberica purchase-prices list` | GET | 查看采购价格列表 | 待创建 |
+| 获取价格详情 | `barista liberica purchase-prices get <id>` | GET | 查看价格详情 | 待创建 |
+| 更新采购价格 | `barista liberica purchase-prices update <id>` | POST | 修改采购价格 | 待创建 |
+
+### 10. sales-orders（销售订单）- 📋 待开发
+
+| 功能 | 命令 | HTTP | 说明 | 设计文档 |
+|------|------|------|------|----------|
+| 创建销售订单 | `barista liberica sales-orders create` | POST | 创建新的销售订单 | 待创建 |
+| 获取销售订单列表 | `barista liberica sales-orders list` | GET | 查看所有销售订单 | 待创建 |
+| 获取销售订单详情 | `barista liberica sales-orders get <id>` | GET | 查看订单详情 | 待创建 |
+| 更新销售订单 | `barista liberica sales-orders update <id>` | POST | 修改订单信息 | 待创建 |
+| 取消销售订单 | `barista liberica sales-orders cancel <id>` | POST | 取消订单 | 待创建 |
+
+---
+
+## 🎯 开发优先级
+
+### P0 - 核心功能（MVP必须）
+
+**Arabica（销售前端）**:
+1. `arabica members register/login` - 会员注册登录
+2. `arabica enterprises register/list` - 企业注册管理
+3. `arabica subscriptions trial/list` - 试用申请和服务查看
+4. `arabica access url` - 获取Liberica访问地址
+
+**Liberica（生产管理）**:
+5. `liberica auth login` - 租户登录 ✅ 已实现
+6. `liberica clients create/list` - 客户管理
+7. `liberica suppliers create/list` - 供应商管理
+8. `liberica materials create/list` - 物料管理
+9. `liberica sales-orders create/list` - 销售订单
+
+### P1 - 重要功能（第二阶段）
+
+- `arabica products list/get` - 产品浏览
+- `liberica users/employees` - 用户和职员管理
+- `liberica sales-prices/purchase-prices` - 价格管理
+- `liberica materials search/update` - 物料高级功能
+
+### P2 - 扩展功能（后续迭代）
+
+- 更新操作（所有 update/cancel 命令）
+- 高级搜索和筛选
+- 批量操作
+- 报表和统计
+
+---
+
+## 📝 设计文档目录结构
+
+```
+docs/commands/
+├── REFERENCE.md              # 本文件 - 命令总览
+│
+├── arabica/
+│   ├── auth/                 # ✅ 已实现
+│   │   └── index.md
+│   ├── members/             # 📋 待开发
+│   │   └── index.md         # 待创建
+│   ├── enterprises/         # 📋 待开发
+│   │   └── index.md         # 待创建
+│   ├── products/             # 📋 待开发
+│   │   └── index.md         # 待创建
+│   ├── subscriptions/       # 📋 待开发
+│   │   └── index.md         # 待创建
+│   └── access/               # 📋 待开发
+│       └── index.md         # 待创建
+│
+└── liberica/
+    ├── auth/                 # ✅ 已实现
+    │   └── index.md
+    ├── context/              # ✅ 已实现
+    │   └── index.md
+    ├── users/                # 📋 待开发
+    │   └── index.md         # 待创建
+    ├── employees/            # 📋 待开发
+    │   └── index.md         # 待创建
+    ├── clients/              # 📋 待开发
+    │   └── index.md         # 待创建
+    ├── suppliers/            # 📋 待开发
+    │   └── index.md         # 待创建
+    ├── materials/            # 📋 待开发
+    │   └── index.md         # 待创建
+    ├── sales-prices/         # 📋 待开发
+    │   └── index.md         # 待创建
+    ├── purchase-prices/      # 📋 待开发
+    │   └── index.md         # 待创建
+    └── sales-orders/         # 📋 待开发
+        └── index.md         # 待创建
+```
+
+---
+
+## ⚠️ 关键说明
+
+### 1. 用户角色区分
+
+**Arabica 用户**（会员）:
+- 可以是个人，也可以代表企业
+- 可以注册多个企业
+- 主要操作：浏览、购买、管理订阅
+
+**Liberica 用户**（租户内部）:
+- 必须是某个租户企业的员工
+- 拥有系统账号和权限
+- 主要操作：生产管理、订单处理
+
+### 2. 数据流
+
+```
+Arabica（会员）          Liberica（租户员工）
+     │                           │
+     ├─ 注册企业 ───────────────>├─ 企业成为租户
+     ├─ 购买服务 ───────────────>├─ 开通租户账号
+     └─ 获取访问URL ────────────>└─ 登录生产系统
+```
+
+### 3. 认证差异
+
+**Arabica 认证**:
+- 会员注册/登录
+- Token 关联会员ID
+- 权限：管理自己的企业和订阅
+
+**Liberica 认证**:
+- 租户员工登录
+- Token 关联租户ID + 用户ID
+- 权限：操作租户企业的生产数据
+
+---
+
+**最后更新**: 2025-04-12