@newpeak/barista-cli 0.1.9 → 0.1.11

package/docs/commands/liberica/transfer-in-forms/batch-review.md

@@ -0,0 +1,157 @@
+# barista liberica transfer-in-forms batch-review
+
+批量审核调整入库单。
+
+## 2.1 命令元数据
+
+| 字段 | 值 |
+|------|-----|
+| 完整命令 | `barista liberica transfer-in-forms batch-review <ids...>` |
+| 功能描述 | 批量审核调整入库单 |
+| HTTP方法 | POST |
+| 是否需要认证 | ✅ 是 |
+| 是否支持dry-run | ✅ 是 |
+
+## 2.2 后端接口引用
+
+### Controller位置
+```
+coffee-liberica-end/
+└── facade/liberica-facade-enterprise/
+    └── src/main/java/com/newpeak/liberica/facade/enterprise/controller/stock/
+        └── EnterpriseTransferInFormController.java
+            └── batchReview(@PostResource(path = "/batchReview", requiredPermission = true, requirePermissionCode = TransferInFormPermissionConstants.REVIEW_TRANSFER_IN_FORM))
+                └── public ResponseData<?> batchReview(
+                        @RequestHeader("X-TENANT-ID") Long tenantId,
+                        @RequestBody @Validated(BaseRequest.batchDelete.class) TransferInFormRequest transferInFormRequest
+                    )
+```
+
+### Request DTO位置
+```
+coffee-liberica-end/
+└── business/liberica-business-stock/stock-api/
+    └── src/main/java/com/newpeak/liberica/stock/api/pojo/request/
+        └── TransferInFormRequest.java
+            └── transferInFormIdList: Set<Long> (@NotEmpty on batchDelete)
+```
+
+### Response DTO位置
+```
+coffee-liberica-end/
+└── business/liberica-business-stock/stock-api/
+    └── src/main/java/com/newpeak/liberica/stock/api/pojo/response/
+        └── SuccessResponseData (空 data)
+```
+
+## 2.3 CLI参数设计
+
+### 命令结构
+```
+barista liberica transfer-in-forms batch-review <ids...> [options]
+```
+
+### 位置参数
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| ids | string... | ✅ | 一个或多个调整入库单ID (transferInFormIdList) |
+
+### 全局选项
+| 选项 | 类型 | 说明 |
+|------|------|------|
+| `--env` | string | 目标环境(dev\|test\|prod-cn\|prod-jp) |
+| `--tenant` | string | 租户代码 |
+| `--dry-run` | boolean | 预览模式（不实际调用API） |
+| `--json` | boolean | JSON输出 |
+
+### 命令选项
+| 选项 | 短选项 | 类型 | 必填 | 默认值 | 说明 |
+|------|--------|------|------|--------|------|
+| --force | -f | boolean | ⬜ | false | 跳过确认提示，直接执行审核 |
+
+**说明**：
+- `--dry-run` 预览将要审核的入库单信息，不实际调用API
+- `--force` 直接执行审核，不显示确认提示（脚本自动化时使用）
+- 无 `--force` 且无 `--dry-run` 时，交互式提示用户确认
+
+## 2.4 字段映射表
+
+| CLI参数 | DTO字段 | 类型转换 | 验证规则 |
+|---------|---------|----------|----------|
+| <ids...> (位置参数) | transferInFormIdList | string[]→Set<Long> | @NotEmpty |
+
+## 2.5 错误码引用
+
+### ExceptionEnum位置
+```
+coffee-liberica-end/
+└── business/liberica-business-stock/stock-api/
+    └── src/main/java/com/newpeak/liberica/stock/api/exception/enums/
+        └── TransferInFormExceptionEnum.java
+            ├── TRANSFER_IN_FORM_NOT_EXIST("01001xx001", "租户入库单不存在")
+            └── ...
+```
+
+### 已知错误码
+| 错误码 | 错误消息 | 触发条件 |
+|--------|----------|----------|
+| 01001xx001 | 租户入库单不存在 | 某个 transferInFormId 不存在或不属于当前租户 |
+
+## 2.6 权限检查
+
+| 检查项 | 位置 | 说明 |
+|--------|------|------|
+| PermissionConstants | `TransferInFormPermissionConstants.REVIEW_TRANSFER_IN_FORM` | Controller层 `@PostResource(requirePermissionCode = "REVIEW_TRANSFER_IN_FORM")` |
+
+## 2.7 实现要点
+
+1. **变长参数**：接受一个或多个 ID 作为位置参数
+2. **BigInteger ID**：所有 ID 必须作为 `string` 处理，避免精度丢失
+3. **幂等性**：对已审核的入库单再次调用效果相同
+4. **No X-TENANT-ID**：租户通过 JWT token 传递，不要发送 `X-TENANT-ID` header
+5. **Dry-run模式**：显示将要审核的入库单编码列表，不实际调用API
+6. **批量操作**：一次性审核多个入库单，失败时返回后端错误信息
+
+## 2.8 示例用法
+
+```bash
+# 审核单个入库单（交互确认）
+barista liberica transfer-in-forms batch-review 1234567890123456789
+
+# 审核多个入库单（交互确认）
+barista liberica transfer-in-forms batch-review 1234567890123456789 9876543210987654321
+
+# 强制审核，跳过确认
+barista liberica transfer-in-forms batch-review 1234567890123456789 --force
+
+# Dry-run 预览
+barista liberica transfer-in-forms batch-review 1234567890123456789 --dry-run
+
+# JSON 输出
+barista liberica transfer-in-forms batch-review 1234567890123456789 --force --json
+```
+
+## 2.9 输出示例
+
+### 确认提示
+```
+即将审核以下 2 条调整入库单：
+  • TI20250001 (ID: 1234567890123456789)
+  • TI20250002 (ID: 9876543210987654321)
+
+确认审核？ [y/N]
+```
+
+### 成功输出
+```
+✓ 成功审核 2 条调整入库单
+```
+
+### JSON输出
+```json
+{
+  "success": true,
+  "data": null,
+  "message": "成功审核 2 条调整入库单"
+}
+```

package/docs/commands/liberica/transfer-in-forms/batch-unreview.md

@@ -0,0 +1,157 @@
+# barista liberica transfer-in-forms batch-unreview
+
+批量反审核调整入库单。
+
+## 2.1 命令元数据
+
+| 字段 | 值 |
+|------|-----|
+| 完整命令 | `barista liberica transfer-in-forms batch-unreview <ids...>` |
+| 功能描述 | 批量反审核调整入库单 |
+| HTTP方法 | POST |
+| 是否需要认证 | ✅ 是 |
+| 是否支持dry-run | ✅ 是 |
+
+## 2.2 后端接口引用
+
+### Controller位置
+```
+coffee-liberica-end/
+└── facade/liberica-facade-enterprise/
+    └── src/main/java/com/newpeak/liberica/facade/enterprise/controller/stock/
+        └── EnterpriseTransferInFormController.java
+            └── batchUnReview(@PostResource(path = "/batchUnReview", requiredPermission = true, requirePermissionCode = TransferInFormPermissionConstants.UN_REVIEW_TRANSFER_IN_FORM))
+                └── public ResponseData<?> batchUnReview(
+                        @RequestHeader("X-TENANT-ID") Long tenantId,
+                        @RequestBody @Validated(BaseRequest.batchDelete.class) TransferInFormRequest transferInFormRequest
+                    )
+```
+
+### Request DTO位置
+```
+coffee-liberica-end/
+└── business/liberica-business-stock/stock-api/
+    └── src/main/java/com/newpeak/liberica/stock/api/pojo/request/
+        └── TransferInFormRequest.java
+            └── transferInFormIdList: Set<Long> (@NotEmpty on batchDelete)
+```
+
+### Response DTO位置
+```
+coffee-liberica-end/
+└── business/liberica-business-stock/stock-api/
+    └── src/main/java/com/newpeak/liberica/stock/api/pojo/response/
+        └── SuccessResponseData (空 data)
+```
+
+## 2.3 CLI参数设计
+
+### 命令结构
+```
+barista liberica transfer-in-forms batch-unreview <ids...> [options]
+```
+
+### 位置参数
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| ids | string... | ✅ | 一个或多个调整入库单ID (transferInFormIdList) |
+
+### 全局选项
+| 选项 | 类型 | 说明 |
+|------|------|------|
+| `--env` | string | 目标环境(dev\|test\|prod-cn\|prod-jp) |
+| `--tenant` | string | 租户代码 |
+| `--dry-run` | boolean | 预览模式（不实际调用API） |
+| `--json` | boolean | JSON输出 |
+
+### 命令选项
+| 选项 | 短选项 | 类型 | 必填 | 默认值 | 说明 |
+|------|--------|------|------|--------|------|
+| --force | -f | boolean | ⬜ | false | 跳过确认提示，直接执行反审核 |
+
+**说明**：
+- `--dry-run` 预览将要反审核的入库单信息，不实际调用API
+- `--force` 直接执行反审核，不显示确认提示（脚本自动化时使用）
+- 无 `--force` 且无 `--dry-run` 时，交互式提示用户确认
+
+## 2.4 字段映射表
+
+| CLI参数 | DTO字段 | 类型转换 | 验证规则 |
+|---------|---------|----------|----------|
+| <ids...> (位置参数) | transferInFormIdList | string[]→Set<Long> | @NotEmpty |
+
+## 2.5 错误码引用
+
+### ExceptionEnum位置
+```
+coffee-liberica-end/
+└── business/liberica-business-stock/stock-api/
+    └── src/main/java/com/newpeak/liberica/stock/api/exception/enums/
+        └── TransferInFormExceptionEnum.java
+            ├── TRANSFER_IN_FORM_NOT_EXIST("01001xx001", "租户入库单不存在")
+            └── ...
+```
+
+### 已知错误码
+| 错误码 | 错误消息 | 触发条件 |
+|--------|----------|----------|
+| 01001xx001 | 租户入库单不存在 | 某个 transferInFormId 不存在或不属于当前租户 |
+
+## 2.6 权限检查
+
+| 检查项 | 位置 | 说明 |
+|--------|------|------|
+| PermissionConstants | `TransferInFormPermissionConstants.UN_REVIEW_TRANSFER_IN_FORM` | Controller层 `@PostResource(requirePermissionCode = "UN_REVIEW_TRANSFER_IN_FORM")` |
+
+## 2.7 实现要点
+
+1. **变长参数**：接受一个或多个 ID 作为位置参数
+2. **BigInteger ID**：所有 ID 必须作为 `string` 处理，避免精度丢失
+3. **幂等性**：对未审核的入库单再次调用效果相同
+4. **No X-TENANT-ID**：租户通过 JWT token 传递，不要发送 `X-TENANT-ID` header
+5. **Dry-run模式**：显示将要反审核的入库单编码列表，不实际调用API
+6. **后置单据限制**：如果入库单已生成下游单据（如库存记录），反审核可能失败
+
+## 2.8 示例用法
+
+```bash
+# 反审核单个入库单（交互确认）
+barista liberica transfer-in-forms batch-unreview 1234567890123456789
+
+# 反审核多个入库单（交互确认）
+barista liberica transfer-in-forms batch-unreview 1234567890123456789 9876543210987654321
+
+# 强制反审核，跳过确认
+barista liberica transfer-in-forms batch-unreview 1234567890123456789 --force
+
+# Dry-run 预览
+barista liberica transfer-in-forms batch-unreview 1234567890123456789 --dry-run
+
+# JSON 输出
+barista liberica transfer-in-forms batch-unreview 1234567890123456789 --force --json
+```
+
+## 2.9 输出示例
+
+### 确认提示
+```
+即将反审核以下 2 条调整入库单：
+  • TI20250001 (ID: 1234567890123456789)
+  • TI20250002 (ID: 9876543210987654321)
+
+⚠️  反审核后这些入库单将变为可编辑状态。确认反审核？ [y/N]
+```
+
+### 成功输出
+```
+✓ 成功反审核 2 条调整入库单
+```
+
+### JSON输出
+```json
+{
+  "success": true,
+  "data": null,
+  "message": "成功反审核 2 条调整入库单"
+}
+```

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

@@ -0,0 +1,220 @@
+# barista liberica transfer-in-forms create
+
+创建新的调整入库单。
+
+## 2.1 命令元数据
+
+| 字段 | 值 |
+|------|-----|
+| 完整命令 | `barista liberica transfer-in-forms create` |
+| 功能描述 | 创建新的调整入库单 |
+| HTTP方法 | POST |
+| 是否需要认证 | ✅ 是 |
+| 是否支持dry-run | ✅ 是 |
+
+## 2.2 后端接口引用
+
+### Controller位置
+```
+coffee-liberica-end/
+└── facade/liberica-facade-enterprise/
+    └── src/main/java/com/newpeak/liberica/facade/enterprise/controller/stock/
+        └── EnterpriseTransferInFormController.java
+            └── add(@PostResource(path = "/add", requiredPermission = true, requirePermissionCode = TransferInFormPermissionConstants.ADD_TRANSFER_IN_FORM))
+                └── public ResponseData<?> add(
+                        @RequestHeader("X-TENANT-ID") Long tenantId,
+                        @RequestBody @Validated(BaseRequest.add.class) TransferInFormRequest transferInFormRequest
+                    )
+```
+
+### Request DTO位置
+```
+coffee-liberica-end/
+└── business/liberica-business-stock/stock-api/
+    └── src/main/java/com/newpeak/liberica/stock/api/pojo/request/
+        └── TransferInFormRequest.java
+            ├── transferInFormCode: String (max=255)
+            ├── mainWarehouseCode: String (@NotBlank on add, max=255)
+            ├── stockDate: Date (@NotNull on add)
+            ├── transferInType: String (@NotBlank on add, max=255)
+            ├── follower: String (@NotBlank on add, max=255)
+            ├── followerName: String (max=255)
+            ├── remark: String (max=255)
+            └── itemList: List<TransferInFormItemRequest> (@NotEmpty on add, @Valid)
+```
+
+### Item Request DTO位置
+```
+coffee-liberica-end/
+└── business/liberica-business-stock/stock-api/
+    └── src/main/java/com/newpeak/liberica/stock/api/pojo/request/
+        └── TransferInFormItemRequest.java
+            ├── warehouseCode: String (@NotBlank on add, max=255)
+            ├── materialCode: String (@NotBlank on add, max=255)
+            ├── materialNo: String (max=255)
+            ├── materialName: String (max=255)
+            ├── materialType: String (max=255)
+            ├── materialCharacteristicCode: String (max=255)
+            ├── materialUomCode: String (max=255)
+            ├── color: String (max=255)
+            ├── longX: BigDecimal
+            ├── wideY: BigDecimal
+            ├── highZ: BigDecimal
+            ├── formQuantity: BigDecimal (@NotNull on add)
+            ├── formMaterialUomCode: String (@NotBlank on add, max=255)
+            ├── formUnitPrice: BigDecimal (@NotNull on add)
+            ├── stockQuantity: BigDecimal
+            ├── unitPrice: BigDecimal
+            ├── localCurrency: String (max=255)
+            ├── stockAmount: BigDecimal
+            ├── producedDate: Date
+            ├── lotCode: String (max=255)
+            ├── lotNo: String (max=255)
+            ├── supplierLotNo: String (max=255)
+            └── remark: String (max=255)
+```
+
+### Response DTO位置
+```
+coffee-liberica-end/
+└── business/liberica-business-stock/stock-api/
+    └── src/main/java/com/newpeak/liberica/stock/api/pojo/response/
+        └── SuccessResponseData (空 data)
+```
+
+## 2.3 CLI参数设计
+
+### 命令结构
+```
+barista liberica transfer-in-forms create [options]
+```
+
+### 全局选项
+| 选项 | 类型 | 说明 |
+|------|------|------|
+| `--env` | string | 目标环境(dev\|test\|prod-cn\|prod-jp) |
+| `--tenant` | string | 租户代码 |
+| `--dry-run` | boolean | 预览模式（不实际调用API） |
+| `--json` | boolean | JSON输出 |
+
+### 命令选项
+| 选项 | 短选项 | 类型 | 必填 | 默认值 | 说明 | 对应DTO字段 |
+|------|--------|------|------|--------|------|-------------|
+| --code | -c | string | ⬜ | - | 入库单编码 | transferInFormCode |
+| --warehouse-code | -w | string | ✅ | - | 主仓库编码 | mainWarehouseCode |
+| --stock-date | -d | string | ✅ | - | 入库日期(YYYY-MM-DD) | stockDate |
+| --type | -t | string | ✅ | - | 调整入库类型 | transferInType |
+| --follower | -f | string | ✅ | - | 入库人编码 | follower |
+| --follower-name | — | string | ⬜ | - | 入库人姓名 | followerName |
+| --remark | -r | string | ⬜ | - | 备注 | remark |
+| --items | -i | string | ✅ | - | 明细项JSON数组 | itemList |
+
+## 2.4 字段映射表
+
+| CLI参数 | DTO字段 | 类型转换 | 验证规则 |
+|---------|---------|----------|----------|
+| --code / -c | transferInFormCode | 直接传递 | max=255，为空则后端自动生成 |
+| --warehouse-code / -w | mainWarehouseCode | 直接传递 | @NotBlank, max=255 |
+| --stock-date / -d | stockDate | string→Date | @NotNull, yyyy-MM-dd |
+| --type / -t | transferInType | 直接传递 | @NotBlank, max=255 |
+| --follower / -f | follower | 直接传递 | @NotBlank, max=255 |
+| --follower-name | followerName | 直接传递 | max=255 |
+| --remark / -r | remark | 直接传递 | max=255 |
+| --items / -i | itemList | string(JSON)→List | @NotEmpty, @Valid |
+
+**自动填充字段（不通过CLI参数）：**
+| 字段 | 值 |
+|------|-----|
+| tenantId | 来自 JWT token（不要传递 X-TENANT-ID header） |
+
+## 2.5 错误码引用
+
+### ExceptionEnum位置
+```
+coffee-liberica-end/
+└── business/liberica-business-stock/stock-api/
+    └── src/main/java/com/newpeak/liberica/stock/api/exception/enums/
+        └── TransferInFormExceptionEnum.java
+            ├── TRANSFER_IN_FORM_NOT_EXIST("01001xx001", "租户入库单不存在")
+            └── ...
+```
+
+### 已知错误码
+| 错误码 | 错误消息 | 触发条件 |
+|--------|----------|----------|
+| 01001xx001 | 租户入库单不存在 | 关联查询时ID不存在 |
+
+## 2.6 权限检查
+
+| 检查项 | 位置 | 说明 |
+|--------|------|------|
+| PermissionConstants | `TransferInFormPermissionConstants.ADD_TRANSFER_IN_FORM` | Controller层 `@PostResource(requirePermissionCode = "ADD_TRANSFER_IN_FORM")` |
+
+## 2.7 实现要点
+
+1. **必填字段**：`--warehouse-code`、`--stock-date`、`--type`、`--follower`、`--items` 必须提供
+2. **自动生成编码**：`transferInFormCode` 为空时后端自动生成
+3. **No X-TENANT-ID**：租户通过 JWT token 传递，不要发送 `X-TENANT-ID` header
+4. **Dry-run支持**：使用 `--dry-run` 时构造请求体但不发送，显示预览信息
+5. **items格式**：`--items` 接收 JSON 字符串数组，包含至少一条明细
+6. **item必填字段**：每条明细必须包含 `warehouseCode`, `materialCode`, `formQuantity`, `formMaterialUomCode`, `formUnitPrice`
+
+## 2.8 示例用法
+
+```bash
+# 最小必填字段创建
+barista liberica transfer-in-forms create \
+  --warehouse-code "WH001" \
+  --stock-date 2025-05-13 \
+  --type "BORROW_IN" \
+  --follower "EMP001" \
+  --items '[{"warehouseCode":"WH001","materialCode":"MAT001","formQuantity":100,"formMaterialUomCode":"KG","formUnitPrice":5.00}]'
+
+# 完整字段创建
+barista liberica transfer-in-forms create \
+  --code "TI20250001" \
+  --warehouse-code "WH001" \
+  --stock-date 2025-05-13 \
+  --type "BORROW_IN" \
+  --follower "EMP001" \
+  --follower-name "张三" \
+  --remark "紧急调拨入库" \
+  --items '[
+    {"warehouseCode":"WH001","materialCode":"MAT001","materialName":"钢板","formQuantity":100,"formMaterialUomCode":"KG","formUnitPrice":5.00},
+    {"warehouseCode":"WH001","materialCode":"MAT002","materialName":"铝材","formQuantity":50,"formMaterialUomCode":"KG","formUnitPrice":8.00}
+  ]'
+
+# Dry-run 预览
+barista liberica transfer-in-forms create \
+  --warehouse-code "WH001" \
+  --stock-date 2025-05-13 \
+  --type "BORROW_IN" \
+  --follower "EMP001" \
+  --items '[...]' \
+  --dry-run
+```
+
+## 2.9 请求体结构示例
+
+```json
+{
+  "transferInFormCode": "TI20250001",
+  "mainWarehouseCode": "WH001",
+  "stockDate": "2025-05-13",
+  "transferInType": "BORROW_IN",
+  "follower": "EMP001",
+  "followerName": "张三",
+  "remark": "紧急调拨入库",
+  "itemList": [
+    {
+      "warehouseCode": "WH001",
+      "materialCode": "MAT001",
+      "materialName": "钢板",
+      "formQuantity": 100,
+      "formMaterialUomCode": "KG",
+      "formUnitPrice": 5.00,
+      "remark": ""
+    }
+  ]
+}
+```