@newpeak/barista-cli 0.1.3 → 0.1.5

package/docs/commands/liberica/materials-create.md

@@ -0,0 +1,293 @@
+# barista liberica materials create
+
+Create a new material (product).
+
+## 2.1 Command Metadata
+
+| Field | Value |
+|------|-----|
+| Full Command | `barista liberica materials create` |
+| Description | Create a new material |
+| 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/master/
+        └── EnterpriseMaterialController.java
+            └── add(@PostResource(path = "/add", requiredPermission = true, requirePermissionCode = MasterMaterialPermissionConstants.ADD_MASTER_MATERIAL))
+                └── public ResponseData<MasterMaterialResponse> add(
+                        @RequestHeader("X-TENANT-ID") Long tenantId,
+                        @RequestBody @Validated(BaseRequest.add.class) MasterMaterialRequest request
+                    )
+```
+
+### Request DTO Location
+```
+coffee-liberica-end/
+└── business/liberica-business-sales/sales-api/
+    └── src/main/java/com/newpeak/liberica/sales/api/pojo/request/
+        └── MasterMaterialRequest.java
+            ├── materialCode: String (@NotBlank on add, max=255)
+            ├── materialNo: String (@NotBlank on add, max=255)
+            ├── materialName: String (@NotBlank on add, max=255)
+            ├── materialShortName: String (max=255)
+            ├── materialClass: String (@NotBlank on add, max=255)
+            ├── materialType: String (max=255)
+            ├── materialUomCode: String (max=255)
+            ├── enableSale: String (Y/N, max=1)
+            ├── enablePurchase: String (Y/N, max=1)
+            ├── enableSubMaterial: String (Y/N, max=1)
+            ├── enableOutsourcing: String (Y/N, max=1)
+            ├── enableDivision: String (Y/N, max=1)
+            ├── materialMaker: String (max=255)
+            ├── defaultWarehouse: String (max=255)
+            ├── defaultSupplier: String (max=255)
+            ├── unitPrice: BigDecimal
+            ├── currency: String (max=255)
+            └── remark: String (max=255)
+```
+
+### Response DTO Location
+```
+coffee-liberica-end/
+└── business/liberica-business-sales/sales-api/
+    └── src/main/java/com/newpeak/liberica/sales/api/pojo/response/
+        └── MasterMaterialResponse.java
+            ├── materialId: Long
+            ├── materialCode: String
+            ├── materialNo: String
+            ├── materialName: String
+            ├── materialShortName: String
+            ├── materialClass: String
+            ├── materialType: String
+            ├── materialUomCode: String
+            ├── enableSale: String (Y/N)
+            ├── enablePurchase: String (Y/N)
+            ├── statusFlag: Integer (1=enable, 2=disable)
+            └── createTime: String
+```
+
+## 2.3 CLI Parameter Design
+
+### Command Structure
+```
+barista liberica materials 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 |
+|------|--------|------|------|--------|------|-------------|
+| --name | -n | string | Yes | - | Material name | materialName |
+| --class | -c | string | Yes | - | Material class/category | materialClass |
+| --type | -t | string | No | - | Specification/model | materialType |
+| --unit | -u | string | No | - | Unit of measure | materialUomCode |
+| --code | — | string | No | Auto-generated | Material code | materialCode |
+| --no | — | string | No | Same as code | Material number | materialNo |
+| --short-name | — | string | No | - | Short name | materialShortName |
+| --maker | — | string | No | - | Manufacturer | materialMaker |
+| --sale | — | boolean | No | true | Enable sale flag | enableSale |
+| --purchase | — | boolean | No | true | Enable purchase flag | enablePurchase |
+| --sub-material | — | boolean | No | false | Can be sub-material | enableSubMaterial |
+| --outsourcing | — | boolean | No | false | Enable outsourcing | enableOutsourcing |
+| --division | — | boolean | No | false | Enable cutting/division | enableDivision |
+| --warehouse | -w | string | No | - | Default warehouse | defaultWarehouse |
+| --supplier | -s | string | No | - | Default supplier | defaultSupplier |
+| --price | -p | number | No | - | Unit price | unitPrice |
+| --currency | — | string | No | - | Currency code | currency |
+| --remark | -r | string | No | - | Remarks | remark |
+
+## 2.4 Field Mapping Table
+
+| CLI Parameter | DTO Field | Type Conversion | Validation Rule |
+|---------|---------|----------|----------|
+| --name / -n | materialName | Direct | @NotBlank, max=255 |
+| --class / -c | materialClass | Direct | @NotBlank, max=255 |
+| --type / -t | materialType | Direct | max=255 |
+| --unit / -u | materialUomCode | Direct | max=255 |
+| --code | materialCode | Direct | max=255, auto-generated if empty |
+| --no | materialNo | Direct | max=255, defaults to code |
+| --short-name | materialShortName | Direct | max=255 |
+| --maker | materialMaker | Direct | max=255 |
+| --sale | enableSale | boolean->String (Y/N) | max=1 |
+| --purchase | enablePurchase | boolean->String (Y/N) | max=1 |
+| --sub-material | enableSubMaterial | boolean->String (Y/N) | max=1 |
+| --outsourcing | enableOutsourcing | boolean->String (Y/N) | max=1 |
+| --division | enableDivision | boolean->String (Y/N) | max=1 |
+| --warehouse / -w | defaultWarehouse | Direct | max=255 |
+| --supplier / -s | defaultSupplier | Direct | max=255 |
+| --price / -p | unitPrice | number->BigDecimal | - |
+| --currency | currency | Direct | max=255 |
+| --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) |
+| materialCode | Auto-generated via getCodeByType('TenantMaterialCode') if not provided |
+| materialNo | Defaults to materialCode if not provided |
+
+## 2.5 Auto Code Generation Flow
+
+When `--code` is not provided, the CLI automatically generates a material code:
+
+```typescript
+// Call getCodeByType API to generate code
+const codeResponse = await apiClient.getCodeByType(
+  environment, 
+  tenant, 
+  'TenantMaterialCode'  // Code type from TenantCodeType enum
+);
+
+if (codeResponse.success && codeResponse.data) {
+  materialCode = codeResponse.data;
+} else {
+  throw new Error('Failed to generate material code');
+}
+```
+
+**API Details:**
+- Endpoint: `GET /api/enterprise/master/id/getCodeByType?type=TenantMaterialCode`
+- Response: `{ success: true, data: "MAT-2024-0001" }`
+- Code Type: `TenantMaterialCode` (defined in `TenantCodeType.java`)
+
+**Backend Code Generation:**
+```
+coffee-liberica-end/
+└── business/liberica-business-master/master-api/
+    └── src/main/java/com/newpeak/liberica/master/api/enums/
+        └── TenantCodeType.java
+            └── TenantMaterialCode  // Line 66
+```
+
+## 2.6 Error Code Reference
+
+### ExceptionEnum Location
+```
+coffee-liberica-end/
+└── business/liberica-business-sales/sales-api/
+    └── src/main/java/com/newpeak/liberica/sales/api/exception/enums/
+        └── MasterMaterialExceptionEnum.java
+            ├── MASTER_MATERIAL_NOT_EXIST("01001200001", "租户物料不存在")
+            ├── MASTER_MATERIAL_CODE_FORMAT_CANNOT_EMPTY("01001200003", "物料编码规则不能为空")
+            ├── MASTER_MATERIAL_CODE_FORMAT_NOT_CORRECT("01001200004", "物料编码规则格式不正确")
+            ├── MASTER_MATERIAL_CODE_VALIDATE_EMPTY_ERROR("01001200005", "{}不能为空")
+            ├── MASTER_MATERIAL_CODE_VALIDATE_NOT_EXIST_ERROR("01001200006", "指定{}不存在")
+            ├── MASTER_MATERIAL_NO_VALIDATE_EMPTY_ERROR("01001200007", "{}不能为空")
+            ├── MASTER_MATERIAL_NAME_VALIDATE_EMPTY_ERROR("01001200009", "{}不能为空")
+            ├── ENABLE_DIVISION_MATERIAL_NEED_WIDE_AND_LONG("01001200012", "可分割物料必须设置长和宽")
+            └── ENABLE_DIVISION_MATERIAL_NEED_WIDE_AND_LONG_GT_ZERO("01001200013", "可分割物料长和宽必须大于0")
+```
+
+### Known Error Codes
+| Error Code | Error Message | Trigger Condition |
+|--------|----------|----------|
+| 01001200001 | Material does not exist | Query/edit with non-existent ID |
+| 01001200003 | Material code format cannot be empty | Auto-generation rule not configured |
+| 01001200004 | Material code format incorrect | Invalid code format pattern |
+| 01001200005 | {} cannot be empty | Required field missing (materialCode) |
+| 01001200007 | {} cannot be empty | Required field missing (materialNo) |
+| 01001200009 | {} cannot be empty | Required field missing (materialName) |
+| 01001200012 | Divisible material must set length and width | enableDivision=true without dimensions |
+| 01001200013 | Divisible material length and width must be > 0 | enableDivision with invalid dimensions |
+
+## 2.7 Permission Check
+
+| Check Item | Location | Description |
+|--------|------|------|
+| PermissionConstants | `MasterMaterialPermissionConstants.ADD_MASTER_MATERIAL` | Controller layer `@PostResource(requirePermissionCode = "ADD_MASTER_MATERIAL")` |
+
+## 2.8 Implementation Notes
+
+1. **Required Fields**: `--name` and `--class` must be provided
+2. **Auto-Generated Code**: `materialCode` is auto-generated via `getCodeByType('TenantMaterialCode')` if not provided
+3. **Material Number**: `materialNo` defaults to `materialCode` if not explicitly provided
+4. **Dry-Run Support**: Use `--dry-run` to preview request without calling API
+5. **Boolean Flags**: All enable flags (sale, purchase, etc.) default to sensible values
+6. **No Batch Create**: This command does NOT support batch creation (one material per call)
+7. **No Interactive Wizard**: No interactive prompts for optional fields (use explicit options)
+
+## 2.9 Example Usage
+
+```bash
+# Create with minimal required fields (auto-generates code)
+barista liberica materials create --name "Steel Plate" --class "RAW_MATERIAL"
+
+# Create with all common options
+barista liberica materials create \
+  --name "Aluminum Sheet 5052" \
+  --class "RAW_MATERIAL" \
+  --type "5052-H32" \
+  --unit "PCS" \
+  --sale \
+  --purchase \
+  --warehouse "MAIN_WH" \
+  --price 125.50 \
+  --currency "USD" \
+  --remark "Standard aluminum sheet"
+
+# Create with explicit code (skip auto-generation)
+barista liberica materials create \
+  --code "MAT-001" \
+  --name "Custom Part" \
+  --class "FINISHED_GOOD"
+
+# Dry-run to preview
+barista liberica materials create \
+  --name "Test Material" \
+  --class "TEST" \
+  --dry-run
+
+# JSON output
+barista liberica materials create \
+  --name "New Product" \
+  --class "PRODUCT" \
+  --json
+```
+
+## 2.10 Request Body Structure
+
+```json
+{
+  "materialCode": "MAT-2024-0001",
+  "materialNo": "MAT-2024-0001",
+  "materialName": "Steel Plate",
+  "materialClass": "RAW_MATERIAL",
+  "materialType": "SPCC",
+  "materialUomCode": "PCS",
+  "enableSale": "Y",
+  "enablePurchase": "Y",
+  "enableSubMaterial": "N",
+  "enableOutsourcing": "N",
+  "enableDivision": "N",
+  "statusFlag": 1
+}
+```
+
+## 2.11 API Path
+
+```
+POST /api/enterprise/sales/material/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/materials-delete.md

@@ -0,0 +1,240 @@
+# barista liberica materials delete
+
+删除指定物料。
+
+## 2.1 命令元数据
+
+| 字段 | 值 |
+|------|-----|
+| 完整命令 | `barista liberica materials delete` |
+| 功能描述 | 删除指定物料 |
+| HTTP方法 | POST |
+| 是否需要认证 | ✅ 是 |
+| 是否支持dry-run | ✅ 是（默认行为） |
+
+## 2.2 后端接口引用
+
+### Controller位置
+```
+coffee-liberica-end/
+└── facade/liberica-facade-enterprise/
+    └── src/main/java/com/newpeak/liberica/facade/enterprise/controller/master/
+        └── EnterpriseMaterialController.java
+            └── delete(@PostResource(path = "/delete", requiredPermission = true, requirePermissionCode = MasterMaterialPermissionConstants.DEL_MASTER_MATERIAL))
+                └── public ResponseData<?> delete(
+                        @RequestHeader("X-TENANT-ID") Long tenantId,
+                        @RequestBody @Validated(BaseRequest.delete.class) MasterMaterialRequest masterMaterialRequest
+                    )
+```
+
+### Request DTO位置
+```
+coffee-liberica-end/
+└── business/liberica-business-sales/sales-api/
+    └── src/main/java/com/newpeak/liberica/sales/api/pojo/request/
+        └── MasterMaterialRequest.java
+            ├── materialId: Long (@NotNull on delete)
+            └── tenantId: Long
+```
+
+**删除请求体结构：**
+```json
+{
+  "materialId": 123456789
+}
+```
+
+### Response DTO位置
+```
+coffee-liberica-end/
+└── business/liberica-business-sales/sales-api/
+    └── src/main/java/com/newpeak/liberica/sales/api/pojo/response/
+        └── MasterMaterialResponse.java
+            ├── materialId: Long
+            ├── materialCode: String
+            ├── materialNo: String
+            ├── materialName: String
+            └── statusFlag: Integer (1=启用, 2=禁用)
+```
+
+## 2.3 CLI参数设计
+
+### 命令结构
+```bash
+barista liberica materials delete <materialId> [options]
+```
+
+### 全局选项
+| 选项 | 类型 | 说明 |
+|------|------|------|
+| `--env` | string | 目标环境(dev\|test\|prod-cn\|prod-jp) |
+| `--tenant` | string | 租户代码 |
+| `--dry-run` | boolean | 预览模式（默认开启） |
+| `--json` | boolean | JSON输出 |
+
+### 命令选项
+| 选项 | 短选项 | 类型 | 必填 | 默认值 | 说明 | 对应DTO字段 |
+|------|--------|------|------|--------|------|-------------|
+| materialId | - | string | ✅ | - | 物料ID（位置参数） | materialId |
+| --force | -f | boolean | ⬜ | false | 跳过确认直接删除 | - |
+| --json | - | boolean | ⬜ | false | JSON格式输出 | - |
+
+### 位置参数
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| materialId | string | ✅ | 要删除的物料ID |
+
+## 2.4 字段映射表
+
+| CLI参数 | DTO字段 | 类型转换 | 验证规则 |
+|---------|---------|----------|----------|
+| materialId (位置参数) | materialId | string→Long | @NotNull |
+
+## 2.5 确认流程
+
+删除操作默认启用dry-run模式，需要用户显式确认：
+
+### 默认行为（无--force）
+```bash
+$ barista liberica materials delete 123456789
+
+🗑️  Delete Material (dev)
+
+  Material ID: 123456789
+  Name: 测试物料
+  Code: MAT-001
+
+🔍 Dry-Run Mode: No actual deletion will be made
+
+  To delete, add: --force
+```
+
+### 强制删除（带--force）
+```bash
+$ barista liberica materials delete 123456789 --force
+
+🗑️  Delete Material (dev)
+
+  Material ID: 123456789
+  Name: 测试物料
+  Code: MAT-001
+
+✓ Material "测试物料" (ID: 123456789) deleted
+```
+
+### JSON输出模式
+```bash
+$ barista liberica materials delete 123456789 --json
+{
+  "success": true,
+  "dryRun": true,
+  "material": {
+    "materialId": "123456789",
+    "materialName": "测试物料",
+    "materialCode": "MAT-001"
+  }
+}
+
+$ barista liberica materials delete 123456789 --force --json
+{
+  "success": true,
+  "materialId": "123456789",
+  "name": "测试物料"
+}
+```
+
+## 2.6 错误码引用
+
+### ExceptionEnum位置
+```
+coffee-liberica-end/
+└── business/liberica-business-sales/sales-api/
+    └── src/main/java/com/newpeak/liberica/sales/api/exception/enums/
+        └── MasterMaterialExceptionEnum.java
+            ├── MASTER_MATERIAL_NOT_EXIST("01001310001", "租户物料不存在")
+            └── DELETE_MASTER_WAREHOUSE_ERROR("01001310014", "删除物料仓库错误")
+```
+
+### Service层业务校验
+```
+coffee-liberica-end/
+└── business/liberica-business-sales/sales-business/
+    └── src/main/java/com/newpeak/liberica/sales/modular/master/business/impl/
+        └── MasterMaterialBusinessImpl.java
+            └── del(MasterMaterialRequest request)
+                ├── Line 384: 检查物料是否存在
+                │   └── throw new SalesServiceException(MasterMaterialExceptionEnum.MASTER_MATERIAL_NOT_EXIST)
+                └── Line 1387: 检查仓库关联
+                    └── throw new SalesServiceException(MasterMaterialExceptionEnum.DELETE_MASTER_WAREHOUSE_ERROR)
+```
+
+### 已知错误码
+| 错误码 | 错误消息 | 触发条件 |
+|--------|----------|----------|
+| 01001310001 | 租户物料不存在 | 物料ID不存在或已被删除 |
+| 01001310014 | 删除物料仓库错误 | 物料与仓库存在关联，无法删除 |
+
+## 2.7 权限检查
+
+| 检查项 | 位置 | 说明 |
+|--------|------|------|
+| PermissionConstants | `MasterMaterialPermissionConstants.DEL_MASTER_MATERIAL` | Controller层 `@PostResource(requirePermissionCode = "DEL_MASTER_MATERIAL")` |
+
+## 2.8 实现要点
+
+1. **必填参数**：materialId 作为位置参数必须提供
+2. **Dry-run默认开启**：不带 `--force` 时只显示预览信息
+3. **物料详情获取**：删除前先调用 `/detail` 接口获取物料信息用于确认提示
+4. **ID类型处理**：后端使用 Long (BigInteger)，CLI使用 string 避免精度丢失
+5. **权限要求**：需要 `DEL_MASTER_MATERIAL` 权限
+
+## 2.9 示例用法
+
+```bash
+# 预览删除（dry-run模式，默认行为）
+barista liberica materials delete 123456789
+
+# 强制删除（跳过确认）
+barista liberica materials delete 123456789 --force
+
+# 指定环境删除
+barista liberica materials delete 123456789 --env test --force
+
+# JSON输出预览
+barista liberica materials delete 123456789 --json
+
+# JSON输出并强制删除
+barista liberica materials delete 123456789 --force --json
+```
+
+## 2.10 实现参考
+
+### --force 模式参考
+参考 `suppliers/delete.ts` 的实现：
+
+```typescript
+if (!options.force) {
+  if (jsonOutput) {
+    console.log(JSON.stringify({ success: true, dryRun: true, supplier }));
+  } else {
+    console.log(chalk.cyan('\n🔍 Dry-Run Mode: No actual deletion will be made\n'));
+    console.log(chalk.yellow('  To delete, add: --force\n'));
+  }
+  return;
+}
+
+// 实际删除
+const response = await apiClient.deleteSupplier(environment, tenant, supplierId);
+```
+
+### 请求体构造
+```typescript
+const request = {
+  materialId: parseInt(materialId)  // string to Long
+};
+```
+
+### API路径
+```
+POST /api/enterprise/sales/material/delete
+```

package/docs/commands/liberica/materials-disable.md

@@ -0,0 +1,150 @@
+# barista liberica materials disable
+
+Disable (deactivate) a material.
+
+## 2.1 命令元数据
+
+| 字段 | 值 |
+|------|-----|
+| 完整命令 | `barista liberica materials disable <materialId>` |
+| 功能描述 | 禁用（停用）物料 |
+| HTTP方法 | POST |
+| 是否需要认证 | ✅ 是 |
+| 是否支持dry-run | ✅ 是 |
+
+## 2.2 后端接口引用
+
+### Controller位置
+```
+coffee-liberica-end/
+└── facade/liberica-facade-enterprise/
+    └── src/main/java/com/newpeak/liberica/facade/enterprise/controller/master/
+        └── EnterpriseMaterialController.java
+            └── batchDeActive(@PostResource(path = "/batchDeActive", requiredPermission = true, requirePermissionCode = MasterMaterialPermissionConstants.DE_ACTIVE_MASTER_MATERIAL))
+                └── public ResponseData<?> batchDeActive(
+                        @RequestHeader("X-TENANT-ID") Long tenantId,
+                        @RequestBody @Validated(BaseRequest.batchDelete.class) MasterMaterialRequest masterMaterialRequest
+                    )
+```
+
+### Request DTO位置
+```
+coffee-liberica-end/
+└── business/liberica-business-sales/sales-api/
+    └── src/main/java/com/newpeak/liberica/sales/api/pojo/request/
+        └── MasterMaterialRequest.java
+            └── materialIdList: Set<Long>
+```
+
+### Response DTO位置
+```
+coffee-liberica-end/
+└── business/liberica-business-sales/sales-api/
+    └── src/main/java/com/newpeak/liberica/sales/api/pojo/response/
+        └── MasterMaterialResponse.java
+            └── 返回更新后的物料详情（同 create/update）
+```
+
+## 2.3 CLI参数设计
+
+### 命令结构
+```
+barista liberica materials disable <materialId> [options]
+```
+
+### 位置参数
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| materialId | string | ✅ | 物料ID (materialId) |
+
+### 全局选项
+| 选项 | 类型 | 说明 |
+|------|------|------|
+| `--env` | string | 目标环境(dev\|test\|prod-cn\|prod-jp) |
+| `--tenant` | string | 租户代码 |
+| `--dry-run` | boolean | 预览模式（不实际调用API） |
+| `--json` | boolean | JSON输出 |
+
+### 命令选项
+| 选项 | 短选项 | 类型 | 必填 | 默认值 | 说明 |
+|------|--------|------|------|--------|------|
+| --force | -f | boolean | ⬜ | false | 跳过确认提示 |
+
+**说明**：
+- `--dry-run` 预览禁用操作的影响（显示将禁用的物料信息）
+- `--force` 直接执行，不显示确认提示（适用于脚本自动化）
+
+## 2.4 字段映射表
+
+| CLI参数 | DTO字段 | 类型转换 | 验证规则 |
+|---------|---------|----------|----------|
+| <materialId> (位置参数) | materialIdList | string→Long | @NotEmpty, 转为单元素Set |
+
+**请求体构建**：
+```json
+{
+  "materialIdList": [<materialId>]
+}
+```
+
+## 2.5 错误码引用
+
+### ExceptionEnum位置
+```
+coffee-liberica-end/
+└── business/liberica-business-sales/sales-api/
+    └── src/main/java/com/newpeak/liberica/sales/api/exception/enums/
+        └── MasterMaterialExceptionEnum.java
+            ├── MASTER_MATERIAL_NOT_EXIST("01001320001", "租户物料不存在")
+            └── ...
+```
+
+### Service层业务校验
+```
+coffee-liberica-end/
+└── business/liberica-business-sales/sales-business/
+    └── src/main/java/com/newpeak/liberica/sales/modular/master/business/
+        └── MasterMaterialBusiness.java
+            └── batchDeActive(MasterMaterialRequest masterMaterialRequest)
+                └── Line 155-169: 批量禁用物料
+                    └── 调用 masterMaterialService.batchDeActive(masterMaterialRequest)
+```
+
+### 已知错误码
+| 错误码 | 错误消息 | 触发条件 |
+|--------|----------|----------|
+| 01001320001 | 租户物料不存在 | materialId 不存在或不属于当前租户 |
+
+## 2.6 权限检查
+
+| 检查项 | 位置 | 说明 |
+|--------|------|------|
+| PermissionConstants | `MasterMaterialPermissionConstants.DE_ACTIVE_MASTER_MATERIAL` | Controller层 `@PostResource(requirePermissionCode = "DE_ACTIVE_MASTER_MATERIAL")` |
+
+## 2.7 实现要点
+
+1. **批量API使用单ID**：后端使用 `/batchDeActive` 批量接口，CLI传入单元素数组 `[materialId]`
+2. **幂等性**：batchDeActive 操作是幂等的——对已禁用的物料再次调用效果相同（直接 set statusFlag=DISABLE）
+3. **Dry-run模式**：预览显示将禁用的物料信息，但不实际发送请求
+4. **无强制选项**：--force 跳过确认提示，但不绕过后端权限检查
+5. **API路径**：`POST /api/enterprise/sales/material/batchDeActive`
+
+## 2.8 示例用法
+
+```bash
+# 禁用物料（交互确认）
+barista liberica materials disable 12345
+
+# 跳过确认直接禁用
+barista liberica materials disable 12345 --force
+
+# Dry-run 预览
+barista liberica materials disable 12345 --dry-run
+
+# JSON 输出
+barista liberica materials disable 12345 --force --json
+
+# 物料不存在
+barista liberica materials disable 99999
+# 输出: Error: 租户物料不存在 (01001320001)
+```