@newpeak/barista-cli 0.1.9 → 0.1.11

package/docs/commands/liberica/transfer-out-forms/create.md

@@ -0,0 +1,280 @@
+# barista liberica transfer-out-forms create
+
+Create a new transfer-out form.
+
+## 2.1 Command Metadata
+
+| Field | Value |
+|------|-----|
+| Full Command | `barista liberica transfer-out-forms create` |
+| Description | Create a new transfer-out form |
+| 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/
+        └── EnterpriseTransferOutFormController.java
+            └── add(@PostResource(path = "/add", requiredPermission = true, requirePermissionCode = TransferOutFormPermissionConstants.ADD_TRANSFER_OUT_FORM))
+                └── public ResponseData<?> add(
+                        @RequestHeader("X-TENANT-ID") Long tenantId,
+                        @RequestBody @Validated(BaseRequest.add.class) TransferOutFormRequest transferOutFormRequest
+                    )
+```
+
+### Request DTO Location
+```
+coffee-liberica-end/
+└── business/liberica-business-stock/stock-api/
+    └── src/main/java/com/newpeak/liberica/stock/api/pojo/request/
+        └── TransferOutFormRequest.java
+            ├── warehouseCode: String (@NotBlank on add, max=255)
+            ├── stockDate: Date (@NotNull on add)
+            ├── transferOutType: String (@NotBlank on add, max=255)
+            ├── transferOutFormCode: String (max=255)
+            ├── follower: String (max=255)
+            ├── followerName: String (max=255)
+            ├── remark: String (max=255)
+            ├── itemList: List<TransferOutFormItemRequest> (@NotEmpty on add)
+            └── lotList: List<TransferOutFormLotRequest>
+```
+
+**TransferOutFormItemRequest (required fields on add):**
+```
+├── materialCode: String (@NotBlank, max=255)
+├── materialUomCode: String (@NotBlank, max=255)
+├── formQuantity: BigDecimal (@NotNull)
+├── formMaterialUomCode: String (@NotBlank, max=255)
+├── stockQuantity: BigDecimal (@NotNull)
+├── sourceType: String (max=255)
+├── sourceCode: String (max=255)
+├── materialName: String (max=255)
+├── materialType: String (max=255)
+├── materialCharacteristicCode: String (max=255)
+├── color: String (max=255)
+├── longX: BigDecimal
+├── wideY: BigDecimal
+├── highZ: BigDecimal
+├── lotNoList: List<String>
+├── unitPrice: BigDecimal
+├── localCurrency: String (max=255)
+├── stockAmount: BigDecimal
+└── remark: String (max=255)
+```
+
+**TransferOutFormLotRequest (required fields on add):**
+```
+├── warehouseCode: String (@NotBlank, max=255)
+├── materialCode: String (@NotBlank, max=255)
+├── materialUomCode: String (@NotBlank, max=255)
+├── lotNo: String (max=255)
+├── stockQuantity: BigDecimal (@NotNull)
+├── materialName: String (max=255)
+├── materialType: String (max=255)
+├── materialCharacteristicCode: String (max=255)
+├── color: String (max=255)
+├── longX: BigDecimal
+├── wideY: BigDecimal
+├── highZ: BigDecimal
+├── unitPrice: BigDecimal
+├── localCurrency: String (max=255)
+├── stockAmount: BigDecimal
+└── remark: String (max=255)
+```
+
+### Response DTO Location
+```
+coffee-liberica-end/
+└── business/liberica-business-stock/stock-api/
+    └── src/main/java/com/newpeak/liberica/stock/api/pojo/response/
+        └── TransferOutFormResponse.java
+            ├── transferOutFormId: Long
+            ├── transferOutFormCode: String
+            ├── warehouseCode: String
+            ├── stockDate: Date
+            ├── transferOutType: String
+            ├── follower: String
+            ├── followerName: String
+            ├── reviewFlag: String
+            ├── reviewer: String
+            ├── reviewerName: String
+            ├── reviewTime: Instant
+            ├── remark: String
+            ├── enough: boolean
+            ├── itemList: List<TransferOutFormItemResponse>
+            ├── lotList: List<TransferOutFormLotResponse>
+            ├── createTime: String
+            └── updateTime: String
+```
+
+## 2.3 CLI Parameter Design
+
+### Command Structure
+```
+barista liberica transfer-out-forms 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 |
+|------|--------|------|------|--------|------|-------------|
+| --warehouse-code | -w | string | Yes | - | Warehouse code | warehouseCode |
+| --stock-date | -d | string | Yes | - | Stock date (YYYY-MM-DD) | stockDate |
+| --transfer-out-type | -t | string | Yes | - | Transfer-out type | transferOutType |
+| --code | -c | string | No | - | Transfer-out form code | transferOutFormCode |
+| --follower | -f | string | No | - | Follower code | follower |
+| --follower-name | -n | string | No | - | Follower name | followerName |
+| --remark | -r | string | No | - | Remark | remark |
+| --items | -i | string | Yes | - | Item list as JSON array | itemList |
+| --lots | -l | string | No | - | Lot list as JSON array | lotList |
+
+## 2.4 Field Mapping Table
+
+| CLI Parameter | DTO Field | Type Conversion | Validation Rule |
+|---------|---------|----------|----------|
+| --warehouse-code / -w | warehouseCode | Direct | @NotBlank, max=255 |
+| --stock-date / -d | stockDate | string→Date | @NotNull, yyyy-MM-dd |
+| --transfer-out-type / -t | transferOutType | Direct | @NotBlank, max=255 |
+| --code / -c | transferOutFormCode | Direct | max=255 |
+| --follower / -f | follower | Direct | max=255 |
+| --follower-name / -n | followerName | Direct | max=255 |
+| --remark / -r | remark | Direct | max=255 |
+| --items / -i | itemList | string→JSON Array | @NotEmpty |
+| --lots / -l | lotList | string→JSON Array | - |
+
+**Auto-Generated Fields:**
+| Field | Value |
+|------|-----|
+| tenantId | From JWT token (do NOT pass X-TENANT-ID header) |
+| transferOutFormCode | Auto-generated if not provided |
+
+## 2.5 Error Code Reference
+
+### ExceptionEnum Location
+```
+coffee-liberica-end/
+└── business/liberica-business-stock/stock-api/
+    └── src/main/java/com/newpeak/liberica/stock/api/exception/enums/
+        └── TransferOutFormExceptionEnum.java
+            ├── TRANSFER_OUT_FORM_NOT_EXIST("01001190001", "租户出库单不存在")
+```
+
+### Known Error Codes
+| Error Code | Error Message | Trigger Condition |
+|--------|----------|----------|
+| 01001190001 | Transfer-out form does not exist | Edit/detail with non-existent ID |
+
+## 2.6 Permission Check
+
+| Check Item | Location | Description |
+|--------|------|------|
+| PermissionConstants | `TransferOutFormPermissionConstants.ADD_TRANSFER_OUT_FORM` | Controller layer `@PostResource(requirePermissionCode = "ADD_TRANSFER_OUT_FORM")` |
+
+## 2.7 Implementation Notes
+
+1. **Required fields**: `--warehouse-code`, `--stock-date`, `--transfer-out-type`, and `--items` must be provided.
+2. **JSON item input**: `--items` accepts a JSON array string of line items. Each item must include `materialCode`, `materialUomCode`, `formQuantity`, `formMaterialUomCode`, and `stockQuantity`.
+3. **JSON lot input**: `--lots` accepts a JSON array string of batch lots. Each lot must include `warehouseCode`, `materialCode`, `materialUomCode`, `lotNo`, and `stockQuantity`.
+4. **Dry-run support**: Use `--dry-run` to preview the request body without calling the API.
+5. **BigInteger ID handling**: `transferOutFormId` in the response must be parsed as `string` in TypeScript to avoid precision loss.
+6. **Date format**: `stockDate` must be in `yyyy-MM-dd` format and converted to a Date object.
+
+## 2.8 Example Usage
+
+```bash
+# Create with minimal required fields
+barista liberica transfer-out-forms create \
+  --warehouse-code WH001 \
+  --stock-date 2025-05-15 \
+  --transfer-out-type adjustment \
+  --items '[{"materialCode":"MAT001","materialUomCode":"kg","formQuantity":500,"formMaterialUomCode":"kg","stockQuantity":500}]'
+
+# Create with all options
+barista liberica transfer-out-forms create \
+  --warehouse-code WH001 \
+  --stock-date 2025-05-15 \
+  --transfer-out-type adjustment \
+  --code "TO-2025-0001" \
+  --follower "EMP001" \
+  --follower-name "Zhang San" \
+  --remark "Monthly adjustment" \
+  --items '[{"materialCode":"MAT001","materialName":"Coffee Beans A","materialUomCode":"kg","formQuantity":500,"formMaterialUomCode":"kg","stockQuantity":500,"unitPrice":50,"stockAmount":25000}]' \
+  --lots '[{"warehouseCode":"WH001","materialCode":"MAT001","materialUomCode":"kg","lotNo":"LOT202501","stockQuantity":500}]'
+
+# Dry-run preview
+barista liberica transfer-out-forms create \
+  --warehouse-code WH001 \
+  --stock-date 2025-05-15 \
+  --transfer-out-type adjustment \
+  --items '[{"materialCode":"MAT001","materialUomCode":"kg","formQuantity":500,"formMaterialUomCode":"kg","stockQuantity":500}]' \
+  --dry-run
+
+# JSON output
+barista liberica transfer-out-forms create \
+  --warehouse-code WH001 \
+  --stock-date 2025-05-15 \
+  --transfer-out-type adjustment \
+  --items '[...]' \
+  --json
+```
+
+## 2.9 Request Body Structure
+
+```json
+{
+  "warehouseCode": "WH001",
+  "stockDate": "2025-05-15",
+  "transferOutType": "adjustment",
+  "transferOutFormCode": "TO-2025-0001",
+  "follower": "EMP001",
+  "followerName": "Zhang San",
+  "remark": "Monthly adjustment",
+  "itemList": [
+    {
+      "materialCode": "MAT001",
+      "materialName": "Coffee Beans A",
+      "materialUomCode": "kg",
+      "formQuantity": 500,
+      "formMaterialUomCode": "kg",
+      "stockQuantity": 500,
+      "unitPrice": 50,
+      "stockAmount": 25000
+    }
+  ],
+  "lotList": [
+    {
+      "warehouseCode": "WH001",
+      "materialCode": "MAT001",
+      "materialUomCode": "kg",
+      "lotNo": "LOT202501",
+      "stockQuantity": 500
+    }
+  ]
+}
+```
+
+## 2.10 API Path
+
+```
+POST /api/enterprise/stock/transferOut/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/transfer-out-forms/get.md

@@ -0,0 +1,211 @@
+# barista liberica transfer-out-forms get
+
+Get a single transfer-out form detail.
+
+## 2.1 Command Metadata
+
+| Field | Value |
+|------|-----|
+| Full Command | `barista liberica transfer-out-forms get <id>` |
+| Description | Get a single transfer-out form detail |
+| 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/
+        └── EnterpriseTransferOutFormController.java
+            └── detail(@GetResource(path = "/detail"))
+                └── public ResponseData<TransferOutFormResponse> detail(
+                        @RequestHeader("X-TENANT-ID") Long tenantId,
+                        @ParameterObject @Validated(BaseRequest.detail.class) TransferOutFormRequest transferOutFormRequest
+                    )
+```
+
+### Request DTO Location
+```
+coffee-liberica-end/
+└── business/liberica-business-stock/stock-api/
+    └── src/main/java/com/newpeak/liberica/stock/api/pojo/request/
+        └── TransferOutFormRequest.java
+            └── transferOutFormId: Long (@NotNull on detail)
+```
+
+### Response DTO Location
+```
+coffee-liberica-end/
+└── business/liberica-business-stock/stock-api/
+    └── src/main/java/com/newpeak/liberica/stock/api/pojo/response/
+        └── TransferOutFormResponse.java
+            ├── transferOutFormId: Long
+            ├── transferOutFormCode: String
+            ├── warehouseCode: String
+            ├── stockDate: Date
+            ├── transferOutType: String
+            ├── follower: String
+            ├── followerName: String
+            ├── reviewFlag: String
+            ├── reviewer: String
+            ├── reviewerName: String
+            ├── reviewTime: Instant
+            ├── remark: String
+            ├── enough: boolean
+            ├── itemList: List<TransferOutFormItemResponse>
+            ├── lotList: List<TransferOutFormLotResponse>
+            ├── createTime: String
+            └── updateTime: String
+```
+
+## 2.3 CLI Parameter Design
+
+### Command Structure
+```
+barista liberica transfer-out-forms get <id> [options]
+```
+
+### Positional Arguments
+| Argument | Type | Required | Description |
+|------|------|------|------|
+| id | string | Yes | Transfer-out form ID (transferOutFormId) |
+
+### 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 |
+|------|--------|------|------|--------|------|
+| — | — | — | — | — | No additional options; ID passed as positional argument |
+
+## 2.4 Field Mapping Table
+
+| CLI Parameter | DTO Field | Type Conversion | Validation Rule |
+|---------|---------|----------|----------|
+| <id> (positional) | transferOutFormId | string→Long | @NotNull |
+
+## 2.5 Error Code Reference
+
+### ExceptionEnum Location
+```
+coffee-liberica-end/
+└── business/liberica-business-stock/stock-api/
+    └── src/main/java/com/newpeak/liberica/stock/api/exception/enums/
+        └── TransferOutFormExceptionEnum.java
+            ├── TRANSFER_OUT_FORM_NOT_EXIST("01001190001", "租户出库单不存在")
+```
+
+### Known Error Codes
+| Error Code | Error Message | Trigger Condition |
+|--------|----------|----------|
+| 01001190001 | Transfer-out form does not exist | ID does not exist or does not belong to current tenant |
+
+## 2.6 Permission Check
+
+| Check Item | Location | Description |
+|--------|------|------|
+| Annotation | `@GetResource(path = "/detail")` | No requiredPermission |
+
+## 2.7 Implementation Notes
+
+1. **Positional argument**: `get` command uses `<id>` positional argument for the transfer-out form ID.
+2. **BigInteger ID handling**: `transferOutFormId` must be parsed as `string` in TypeScript to avoid precision loss.
+3. **Nested data**: Response includes `itemList` (line items) and `lotList` (batch lots). Display these in a nested table or JSON structure.
+4. **Inventory check**: The `enough` field indicates whether stock is sufficient.
+5. **Error handling**: When the form does not exist, display friendly error message with error code.
+
+## 2.8 Example Usage
+
+```bash
+# Get transfer-out form detail
+barista liberica transfer-out-forms get 123456789
+
+# JSON output
+barista liberica transfer-out-forms get 123456789 --json
+```
+
+## 2.9 Output Examples
+
+### Table Output
+```
+Transfer-Out Form Detail
+
+Basic Info
+┌─────────────────┬─────────────────────────────┐
+│ Field           │ Value                       │
+├─────────────────┼─────────────────────────────┤
+│ Form ID         │ 123456789                   │
+│ Form Code       │ TO-2025-0001                │
+│ Warehouse       │ WH001                       │
+│ Stock Date      │ 2025-05-15                  │
+│ Type            │ adjustment                  │
+│ Follower        │ Zhang San                   │
+│ Review Flag     │ reviewed                    │
+│ Reviewer        │ admin                       │
+│ Review Time     │ 2025-05-15 10:30:00         │
+│ Stock Sufficient│ Yes                         │
+│ Remark          │ Monthly adjustment          │
+└─────────────────┴─────────────────────────────┘
+
+Items
+┌─────────────┬──────────────┬──────────────────┬───────────────┬─────────────┐
+│ Item ID     │ Material Code│ Material Name    │ Form Qty      │ Stock Qty   │
+├─────────────┼──────────────┼──────────────────┼───────────────┼─────────────┤
+│ 1000001     │ MAT001       │ Coffee Beans A   │ 500.00 kg     │ 500.00 kg   │
+│ 1000002     │ MAT002       │ Coffee Beans B   │ 300.00 kg     │ 300.00 kg   │
+└─────────────┴──────────────┴──────────────────┴───────────────┴─────────────┘
+```
+
+### JSON Output
+```json
+{
+  "success": true,
+  "data": {
+    "transferOutFormId": "123456789",
+    "transferOutFormCode": "TO-2025-0001",
+    "warehouseCode": "WH001",
+    "stockDate": "2025-05-15",
+    "transferOutType": "adjustment",
+    "followerName": "Zhang San",
+    "reviewFlag": "reviewed",
+    "reviewerName": "Admin",
+    "reviewTime": "2025-05-15T10:30:00Z",
+    "remark": "Monthly adjustment",
+    "enough": true,
+    "itemList": [
+      {
+        "transferOutFormItemId": "1000001",
+        "materialCode": "MAT001",
+        "materialName": "Coffee Beans A",
+        "formQuantity": "500.00",
+        "formMaterialUomCode": "kg",
+        "stockQuantity": "500.00",
+        "materialUomCode": "kg",
+        "unitPrice": "50.00",
+        "stockAmount": "25000.00"
+      }
+    ],
+    "lotList": []
+  }
+}
+```
+
+## 2.10 API Path
+
+```
+GET /api/enterprise/stock/transferOut/detail?transferOutFormId=123456789
+```
+
+**Headers:**
+```
+Authorization: <token>  (No "Bearer " prefix)
+```
+
+**Note**: Do NOT include `X-TENANT-ID` header. Tenant is extracted from JWT token.