@newpeak/barista-cli 0.1.6 → 0.1.8

package/docs/commands/liberica/supplier-contacts/update.md

@@ -0,0 +1,158 @@
+# barista liberica supplier-contacts update
+
+更新供应商联系人信息。
+
+## 2.1 命令元数据
+
+| 字段 | 值 |
+|------|-----|
+| 完整命令 | `barista liberica supplier-contacts update <contact-id>` |
+| 功能描述 | 修改供应商联系人信息 |
+| HTTP方法 | POST |
+| 是否需要认证 | ✅ 是 |
+| 是否支持dry-run | ✅ 是 |
+
+## 2.2 后端接口引用
+
+### Controller位置
+```
+coffee-liberica-end/
+└── facade/liberica-facade-enterprise/
+    └── src/main/java/com/newpeak/liberica/facade/enterprise/controller/purchases/
+        └── EnterpriseSupplierContactController.java
+            └── edit(@PostResource(path = "/edit", requiredPermission = true, requirePermissionCode = "EDIT_MASTER_SUPPLIER_CONTACT"))
+                └── public ResponseData<?> edit(
+                        @RequestHeader("X-TENANT-ID") Long tenantId,
+                        @RequestBody @Validated(BaseRequest.edit.class) MasterSupplierContactRequest masterSupplierContactRequest
+                    )
+```
+
+### Request DTO位置
+```
+coffee-liberica-end/
+└── business/liberica-business-master/master-api/
+    └── src/main/java/com/newpeak/liberica/master/api/pojo/request/
+        └── MasterSupplierContactRequest.java
+            ├── supplierContactId: Long (@NotNull on edit)
+            ├── supplierContactName: String (@NotBlank, max=255)
+            ├── supplierContactPhone: String (max=256)
+            ├── supplierContactTelephone: String (max=256)
+            ├── supplierContactEmail: String (max=512)
+            ├── supplierContactSex: String (max=255)
+            ├── supplierContactBirthday: Date
+            ├── supplierContactQq: String (max=512)
+            ├── supplierContactWechat: String (max=512)
+            ├── supplierContactAddress: String (max=512)
+            ├── defaultFlag: String (max=1)
+            └── remark: String (max=255)
+```
+
+### Response DTO位置
+```
+coffee-liberica-end/
+└── business/liberica-business-master/master-api/
+    └── src/main/java/com/newpeak/liberica/master/api/pojo/response/
+        └── MasterSupplierContactResponse.java
+            └── (同 get 接口)
+```
+
+## 2.3 CLI参数设计
+
+### 命令结构
+```
+barista liberica supplier-contacts update <contact-id> [options]
+```
+
+### 位置参数
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| contact-id | string | ✅ | 供应商联系人ID |
+
+### 全局选项
+| 选项 | 类型 | 说明 |
+|------|------|------|
+| `--env` | string | 目标环境(dev\|test\|prod-cn\|prod-jp) |
+| `--tenant` | string | 租户代码 |
+| `--dry-run` | boolean | 预览模式 |
+| `--json` | boolean | JSON输出 |
+
+### 命令选项
+| 选项 | 短选项 | 类型 | 必填 | 默认值 | 说明 | 对应DTO字段 |
+|------|--------|------|------|--------|------|-------------|
+| --name | -n | string | ⬜ | - | 姓名 | supplierContactName |
+| --phone | -p | string | ⬜ | - | 手机号 | supplierContactPhone |
+| --telephone | -t | string | ⬜ | - | 座机号 | supplierContactTelephone |
+| --email | -e | string | ⬜ | - | 电子邮箱 | supplierContactEmail |
+| --sex | -x | string | ⬜ | - | 性别 | supplierContactSex |
+| --birthday | -b | string | ⬜ | - | 生日(YYYY-MM-DD) | supplierContactBirthday |
+| --qq | -q | string | ⬜ | - | QQ号 | supplierContactQq |
+| --wechat | -w | string | ⬜ | - | 微信号 | supplierContactWechat |
+| --address | -a | string | ⬜ | - | 详细地址 | supplierContactAddress |
+| --default | -d | boolean | ⬜ | - | 是否默认联系人 | defaultFlag |
+| --remark | -r | string | ⬜ | - | 备注 | remark |
+
+**注意**：所有字段在 update 时都是可选的，至少需要提供一个要更新的字段。
+
+## 2.4 字段映射表
+
+| CLI参数 | DTO字段 | 类型转换 | 验证规则 |
+|---------|---------|----------|----------|
+| <contact-id> | supplierContactId | string→Long | @NotNull |
+| --name / -n | supplierContactName | 直接传递 | max=255 |
+| --phone / -p | supplierContactPhone | 直接传递 | max=256 |
+| --telephone / -t | supplierContactTelephone | 直接传递 | max=256 |
+| --email / -e | supplierContactEmail | 直接传递 | max=512 |
+| --sex / -x | supplierContactSex | 直接传递 | max=255 |
+| --birthday / -b | supplierContactBirthday | string→Date | yyyy-MM-dd |
+| --qq / -q | supplierContactQq | 直接传递 | max=512 |
+| --wechat / -w | supplierContactWechat | 直接传递 | max=512 |
+| --address / -a | supplierContactAddress | 直接传递 | max=512 |
+| --default / -d | defaultFlag | boolean→Y/N | max=1 |
+| --remark / -r | remark | 直接传递 | max=255 |
+
+## 2.5 错误码引用
+
+### ExceptionEnum位置
+```
+coffee-liberica-end/
+└── business/liberica-business-master/master-api/
+    └── src/main/java/com/newpeak/liberica/master/api/exception/enums/
+        └── MasterSupplierContactExceptionEnum.java
+            └── MASTER_SUPPLIER_CONTACT_NOT_EXIST("01001XXX001", "租户供应商联系人不存在")
+```
+
+### 已知错误码
+| 错误码 | 错误消息 | 触发条件 |
+|--------|----------|----------|
+| 01001XXX001 | 租户供应商联系人不存在 | contact-id 不存在或不属于当前租户 |
+
+## 2.6 权限检查
+
+| 检查项 | 位置 | 说明 |
+|--------|------|------|
+| PermissionConstants | `EDIT_MASTER_SUPPLIER_CONTACT` | 编辑供应商联系人需要此权限 |
+| 注解 | `@PostResource(requirePermissionCode = "EDIT_MASTER_SUPPLIER_CONTACT")` | Controller方法上 |
+
+## 2.7 实现要点
+
+1. **位置参数**：contact-id 必须指定
+2. **可选字段**：所有业务字段都是可选的，至少提供一个
+3. **dry-run 模式**：预览模式下只显示将要更新的数据，不实际调用 API
+4. **输出格式**：成功后显示更新后的联系人信息
+5. **错误处理**：联系人不存在时显示友好错误信息
+
+## 2.8 示例用法
+
+```bash
+# 更新联系人姓名（dry-run 预览）
+barista liberica supplier-contacts update 12345 --name "新姓名" --dry-run
+
+# 实际更新
+barista liberica supplier-contacts update 12345 --name "新姓名" --phone "13900139000"
+
+# 更新多个字段
+barista liberica supplier-contacts update 12345 --email "new@example.com" --address "新地址"
+
+# JSON 输出
+barista liberica supplier-contacts update 12345 --name "新姓名" --json
+```

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

@@ -0,0 +1,222 @@
+# barista liberica warehouses create
+
+Create a new warehouse.
+
+## 2.1 Command Metadata
+
+| Field | Value |
+|------|-----|
+| Full Command | `barista liberica warehouses create` |
+| Description | Create a new warehouse |
+| HTTP Method | POST |
+| Requires Authentication | Yes |
+| Supports Dry-Run | Yes |
+
+## 2.2 Backend API Reference
+
+### Controller Location
+```
+coffee-liberica-end/
+└── facade/liberica-facade-enterprise/
+    └── src/main/java/com/newpeak/liberica/facade/enterprise/controller/stock/
+        └── EnterpriseWarehouseController.java
+            └── add(@PostResource(path = "/add", requiredPermission = true, requirePermissionCode = MasterWarehousePermissionConstants.ADD_MASTER_WAREHOUSE))
+                └── public ResponseData<MasterWarehouseResponse> add(
+                        @RequestHeader("X-TENANT-ID") Long tenantId,
+                        @RequestBody @Validated(BaseRequest.add.class) MasterWarehouseRequest masterWarehouseRequest
+                    )
+```
+
+### Request DTO Location
+```
+coffee-liberica-end/
+└── business/liberica-business-master/master-api/
+    └── src/main/java/com/newpeak/liberica/master/api/pojo/request/
+        └── MasterWarehouseRequest.java
+            ├── warehouseCode: String (@NotBlank on add, max=255)
+            ├── warehouseName: String (max=255)
+            ├── warehouseClasses: String (max=255)
+            ├── manager: String (max=255)
+            ├── warehouseTelephone: String (max=256)
+            ├── warehouseFax: String (max=256)
+            ├── warehouseAddress: String (max=512)
+            ├── enableLocation: String (@NotBlank on add, max=1, Y/N)
+            ├── enableNegativeInventory: String (max=1, Y/N)
+            ├── statusFlag: Integer
+            └── remark: String (max=255)
+```
+
+### Response DTO Location
+```
+coffee-liberica-end/
+└── business/liberica-business-master/master-api/
+    └── src/main/java/com/newpeak/liberica/master/api/pojo/response/
+        └── MasterWarehouseResponse.java
+            ├── warehouseId: Long
+            ├── warehouseCode: String
+            ├── warehouseName: String
+            ├── warehouseClasses: String
+            ├── manager: String
+            ├── warehouseTelephone: String
+            ├── warehouseFax: String
+            ├── warehouseAddress: String
+            ├── enableLocation: String (Y/N)
+            ├── enableNegativeInventory: String (Y/N)
+            ├── statusFlag: Integer (1=enable, 2=disable)
+            ├── remark: String
+            └── locations: List<MasterWarehouseLocationResponse>
+```
+
+## 2.3 CLI Parameter Design
+
+### Command Structure
+```
+barista liberica warehouses create [options]
+```
+
+### Global Options
+| Option | Type | Description |
+|------|------|------|
+| `--env` | string | Target environment (dev\|test\|prod-cn\|prod-jp) |
+| `--tenant` | string | Tenant code |
+| `--dry-run` | boolean | Preview mode (no actual API call) |
+| `--json` | boolean | JSON output |
+
+### Command Options
+| Option | Short | Type | Required | Default | Description | Maps to DTO Field |
+|------|--------|------|------|--------|------|-------------|
+| --code | -c | string | Yes | - | Warehouse code | warehouseCode |
+| --name | -n | string | Yes | - | Warehouse name | warehouseName |
+| --classes | — | string | No | - | Warehouse class/category | warehouseClasses |
+| --manager | -m | string | No | - | Warehouse manager | manager |
+| --phone | — | string | No | - | Warehouse telephone | warehouseTelephone |
+| --fax | — | string | No | - | Warehouse fax | warehouseFax |
+| --address | -a | string | No | - | Warehouse address | warehouseAddress |
+| --enable-location | — | boolean | Yes | true | Enable location management | enableLocation |
+| --enable-negative-inventory | — | boolean | No | false | Allow negative inventory | enableNegativeInventory |
+| --remark | -r | string | No | - | Remarks | remark |
+
+## 2.4 Field Mapping Table
+
+| CLI Parameter | DTO Field | Type Conversion | Validation Rule |
+|---------|---------|----------|----------|
+| --code / -c | warehouseCode | Direct | @NotBlank, max=255, unique per tenant |
+| --name / -n | warehouseName | Direct | max=255 |
+| --classes | warehouseClasses | Direct | max=255 |
+| --manager / -m | manager | Direct | max=255 |
+| --phone | warehouseTelephone | Direct | max=256 |
+| --fax | warehouseFax | Direct | max=256 |
+| --address / -a | warehouseAddress | Direct | max=512 |
+| --enable-location | enableLocation | boolean->String (Y/N) | @NotBlank, max=1 |
+| --enable-negative-inventory | enableNegativeInventory | boolean->String (Y/N) | max=1 |
+| --remark / -r | remark | Direct | max=255 |
+
+**Auto-Generated Fields:**
+| Field | Value |
+|------|-----|
+| tenantId | From JWT token (do NOT pass X-TENANT-ID header) |
+| statusFlag | Default 1 (enabled) |
+
+## 2.5 Error Code Reference
+
+### ExceptionEnum Location
+```
+coffee-liberica-end/
+└── business/liberica-business-master/master-api/
+    └── src/main/java/com/newpeak/liberica/master/api/exception/enums/
+        └── MasterWarehouseExceptionEnum.java
+            ├── MASTER_WAREHOUSE_NOT_EXIST("01001370001", "租户仓库不存在")
+            ├── MASTER_WAREHOUSE_CODE_FORMAT_CANNOT_EMPTY("01001370002", "仓库编码规则不能为空")
+            └── MASTER_WAREHOUSE_CODE_FORMAT_NOT_CORRECT("01001370003", "仓库编码规则格式不正确")
+```
+
+### Known Error Codes
+| Error Code | Error Message | Trigger Condition |
+|--------|----------|----------|
+| 01001370001 | Warehouse does not exist | Edit/detail with non-existent ID |
+| 01001370002 | Warehouse code format cannot be empty | Auto-generation rule not configured |
+| 01001370003 | Warehouse code format incorrect | Invalid code format pattern |
+
+## 2.6 Permission Check
+
+| Check Item | Location | Description |
+|--------|------|------|
+| PermissionConstants | `MasterWarehousePermissionConstants.ADD_MASTER_WAREHOUSE` | Controller layer `@PostResource(requirePermissionCode = "ADD_MASTER_WAREHOUSE")` |
+
+## 2.7 Implementation Notes
+
+1. **Required Fields**: `--code` and `--name` must be provided. `--enable-location` defaults to true.
+2. **Manual Code**: `warehouseCode` is NOT auto-generated. User must provide a unique code.
+3. **Dry-Run Support**: Use `--dry-run` to preview request without calling API.
+4. **Boolean Flags**: `--enable-location` defaults to `true` (Y), `--enable-negative-inventory` defaults to `false` (N).
+5. **No Batch Create**: This command does NOT support batch creation (one warehouse per call).
+6. **BigInteger ID**: `warehouseId` in response must be parsed as `string` in TypeScript to avoid precision loss.
+
+## 2.8 Example Usage
+
+```bash
+# Create with minimal required fields
+barista liberica warehouses create --code "WH-001" --name "Main Warehouse"
+
+# Create with all common options
+barista liberica warehouses create \
+  --code "WH-002" \
+  --name "East Storage" \
+  --classes "FINISHED_GOOD" \
+  --manager "John Doe" \
+  --phone "021-12345678" \
+  --address "123 Industrial Road" \
+  --enable-location \
+  --enable-negative-inventory \
+  --remark "Primary finished goods storage"
+
+# Disable location management
+barista liberica warehouses create \
+  --code "WH-003" \
+  --name "Bulk Storage" \
+  --no-enable-location
+
+# Dry-run to preview
+barista liberica warehouses create \
+  --code "WH-004" \
+  --name "Test Warehouse" \
+  --dry-run
+
+# JSON output
+barista liberica warehouses create \
+  --code "WH-005" \
+  --name "New Warehouse" \
+  --json
+```
+
+## 2.9 Request Body Structure
+
+```json
+{
+  "warehouseCode": "WH-001",
+  "warehouseName": "Main Warehouse",
+  "warehouseClasses": "FINISHED_GOOD",
+  "manager": "John Doe",
+  "warehouseTelephone": "021-12345678",
+  "warehouseFax": "021-87654321",
+  "warehouseAddress": "123 Industrial Road",
+  "enableLocation": "Y",
+  "enableNegativeInventory": "N",
+  "statusFlag": 1,
+  "remark": "Primary storage"
+}
+```
+
+## 2.10 API Path
+
+```
+POST /api/enterprise/purchases/warehouse/add
+```
+
+**Headers:**
+```
+Authorization: <token>  (No "Bearer " prefix)
+Content-Type: application/json
+```
+
+**Note**: Do NOT include `X-TENANT-ID` header. Tenant is extracted from JWT token.

package/docs/commands/liberica/warehouses/list.md

@@ -0,0 +1,184 @@
+# barista liberica warehouses list
+
+List warehouses with pagination.
+
+## 2.1 Command Metadata
+
+| Field | Value |
+|------|-----|
+| Full Command | `barista liberica warehouses list` |
+| Description | List warehouses with pagination |
+| HTTP Method | GET |
+| Requires Authentication | Yes |
+| Supports Dry-Run | No |
+
+## 2.2 Backend API Reference
+
+### Controller Location
+```
+coffee-liberica-end/
+└── facade/liberica-facade-enterprise/
+    └── src/main/java/com/newpeak/liberica/facade/enterprise/controller/stock/
+        └── EnterpriseWarehouseController.java
+            └── page(@GetResource(path = "/page"))
+                └── public ResponseData<PageResult<MasterWarehouseResponse>> page(
+                        @RequestHeader("X-TENANT-ID") Long tenantId,
+                        @ParameterObject MasterWarehouseRequest masterWarehouseRequest
+                    )
+```
+
+### Request DTO Location
+```
+coffee-liberica-end/
+└── business/liberica-business-master/master-api/
+    └── src/main/java/com/newpeak/liberica/master/api/pojo/request/
+        └── MasterWarehouseRequest.java
+            ├── warehouseCode: String
+            ├── warehouseName: String
+            ├── warehouseClasses: String
+            ├── manager: String
+            ├── warehouseTelephone: String
+            ├── warehouseFax: String
+            ├── warehouseAddress: String
+            ├── enableLocation: String (Y/N)
+            ├── enableNegativeInventory: String (Y/N)
+            ├── statusFlag: Integer
+            └── remark: String
+```
+
+### Response DTO Location
+```
+coffee-liberica-end/
+└── business/liberica-business-master/master-api/
+    └── src/main/java/com/newpeak/liberica/master/api/pojo/response/
+        └── MasterWarehouseResponse.java
+            ├── warehouseId: Long
+            ├── warehouseCode: String
+            ├── warehouseName: String
+            ├── warehouseClasses: String
+            ├── manager: String
+            ├── warehouseTelephone: String
+            ├── warehouseFax: String
+            ├── warehouseAddress: String
+            ├── enableLocation: String (Y/N)
+            ├── enableNegativeInventory: String (Y/N)
+            ├── statusFlag: Integer (1=enable, 2=disable)
+            ├── remark: String
+            └── locations: List<MasterWarehouseLocationResponse>
+```
+
+## 2.3 CLI Parameter Design
+
+### Command Structure
+```
+barista liberica warehouses list [options]
+```
+
+### Global Options
+| Option | Type | Description |
+|------|------|------|
+| `--env` | string | Target environment (dev\|test\|prod-cn\|prod-jp) |
+| `--tenant` | string | Tenant code |
+| `--json` | boolean | JSON output |
+
+### Command Options
+| Option | Short | Type | Required | Default | Description | Maps to Query Param |
+|------|--------|------|------|--------|------|-------------|
+| --page | -p | number | No | 1 | Page number (CLI 1-based) | pageNo (0-based) |
+| --size | -s | number | No | 20 | Page size | pageSize |
+| --status | — | number | No | - | Status filter (1=enable, 2=disable) | statusFlag |
+| --keyword | -k | string | No | - | Keyword search (warehouseName and warehouseCode) | warehouseName / warehouseCode |
+| --classes | — | string | No | - | Warehouse class filter | warehouseClasses |
+| --enable-location | — | boolean | No | - | Filter by location management enabled | enableLocation |
+
+## 2.4 Field Mapping Table
+
+| CLI Parameter | Query Param / DTO Field | Type Conversion | Validation Rule |
+|---------|---------|----------|----------|
+| --page / -p | pageNo | number, CLI page - 1 | >= 0 |
+| --size / -s | pageSize | number | > 0 |
+| --status | statusFlag | number | 1 or 2 |
+| --keyword / -k | warehouseName / warehouseCode | Direct | max=255 |
+| --classes | warehouseClasses | Direct | max=255 |
+| --enable-location | enableLocation | boolean->String (Y/N) | max=1 |
+
+## 2.5 Error Code Reference
+
+### ExceptionEnum Location
+```
+coffee-liberica-end/
+└── business/liberica-business-master/master-api/
+    └── src/main/java/com/newpeak/liberica/master/api/exception/enums/
+        └── MasterWarehouseExceptionEnum.java
+            ├── MASTER_WAREHOUSE_NOT_EXIST("01001370001", "租户仓库不存在")
+            ├── MASTER_WAREHOUSE_CODE_FORMAT_CANNOT_EMPTY("01001370002", "仓库编码规则不能为空")
+            └── MASTER_WAREHOUSE_CODE_FORMAT_NOT_CORRECT("01001370003", "仓库编码规则格式不正确")
+```
+
+### Known Error Codes
+| Error Code | Error Message | Trigger Condition |
+|--------|----------|----------|
+| 01001370001 | Warehouse does not exist | Detail query with non-existent ID |
+
+## 2.6 Permission Check
+
+| Check Item | Location | Description |
+|--------|------|------|
+| Page Query | No specific permission code on `@GetResource(path = "/page")` | Available to authenticated users |
+
+## 2.7 Implementation Notes
+
+1. **Pagination**: CLI uses 1-based page numbers. API uses 0-based. Convert: `pageNo = options.page - 1`.
+2. **Response Fields**: Backend returns `rows`, `pageNo`, `pageSize`, `totalRows`. Do NOT use `records` or `total`.
+3. **Keyword Search**: When `--keyword` is provided, send it as both `warehouseName` and `warehouseCode` query params.
+4. **BigInteger ID**: `warehouseId` in response rows must be kept as `string` in TypeScript.
+5. **Table Output**: Default columns: ID, Code, Name, Classes, Location, Status.
+6. **JSON Output**: When `--json` is used, wrap response with standardized pagination object.
+
+## 2.8 Example Usage
+
+```bash
+# List all warehouses (first page, 20 per page)
+barista liberica warehouses list
+
+# List with pagination
+barista liberica warehouses list --page 2 --size 50
+
+# Filter by status
+barista liberica warehouses list --status 1
+
+# Keyword search
+barista liberica warehouses list --keyword "Main"
+
+# Filter by class
+barista liberica warehouses list --classes "FINISHED_GOOD"
+
+# JSON output
+barista liberica warehouses list --json
+
+# Combine filters
+barista liberica warehouses list \
+  --page 1 \
+  --size 10 \
+  --status 1 \
+  --keyword "WH-001" \
+  --json
+```
+
+## 2.9 API Path
+
+```
+GET /api/enterprise/purchases/warehouse/page
+```
+
+**Query Parameters:**
+```
+?pageNo=0&pageSize=20&statusFlag=1&warehouseCode=Main&warehouseName=Main
+```
+
+**Headers:**
+```
+Authorization: <token>  (No "Bearer " prefix)
+```
+
+**Note**: Do NOT include `X-TENANT-ID` header. Tenant is extracted from JWT token.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newpeak/barista-cli",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "AI Tools CLI for Liberica and Arabica services",
   "type": "module",
   "bin": "./bin/barista",

package/src/commands/liberica/calendar/index.ts

@@ -0,0 +1,13 @@
+import { Command } from 'commander';
+import { createCalendarSetCommand } from './set.js';
+import { createCalendarListCommand } from './list.js';
+
+export function createCalendarCommand(): Command {
+  const calendarCommand = new Command('calendar');
+  calendarCommand.description('Manage calendar (workdays, holidays)');
+
+  calendarCommand.addCommand(createCalendarSetCommand());
+  calendarCommand.addCommand(createCalendarListCommand());
+
+  return calendarCommand;
+}