@newpeak/barista-cli 0.1.4 → 0.1.6

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)
+```

package/docs/commands/liberica/materials/enable.md

@@ -0,0 +1,146 @@
+# barista liberica materials enable
+
+启用（激活）物料。
+
+## 2.1 命令元数据
+
+| 字段 | 值 |
+|------|-----|
+| 完整命令 | `barista liberica materials enable <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
+            └── batchActive(@PostResource(path = "/batchActive", requiredPermission = true, requirePermissionCode = "ACTIVE_MASTER_MATERIAL"))
+                └── public ResponseData<?> batchActive(
+                        @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
+            └── 返回成功响应（无数据体）
+```
+
+## 2.3 CLI参数设计
+
+### 命令结构
+```
+barista liberica materials enable <materialId> [options]
+```
+
+### 位置参数
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| materialId | string | ✅ | 物料ID |
+
+### 全局选项
+| 选项 | 类型 | 说明 |
+|------|------|------|
+| `--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[0] | string→Long | @NotEmpty, 单元素数组 |
+
+**请求体构造**：
+```json
+{
+  "materialIdList": [12345]
+}
+```
+
+## 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("01001410001", "租户物料不存在")
+            ├── MASTER_MATERIAL_CODE_VALIDATE_NOT_EXIST_ERROR("01001410006", "指定{}不存在")
+            └── MASTER_MATERIAL_NAME_VALIDATE_NOT_EXIST_ERROR("01001410010", "指定{}不存在")
+```
+
+### 已知错误码
+| 错误码 | 错误消息 | 触发条件 |
+|--------|----------|----------|
+| 01001410001 | 租户物料不存在 | materialId 不存在或不属于当前租户 |
+| 01001410006 | 指定xxx不存在 | 指定关联的物料编码不存在 |
+| 01001410010 | 指定xxx不存在 | 指定关联的物料名称不存在 |
+
+## 2.6 权限检查
+
+| 检查项 | 位置 | 说明 |
+|--------|------|------|
+| PermissionConstants | `MasterMaterialPermissionConstants.ACTIVE_MASTER_MATERIAL` | Controller层 `@PostResource(requirePermissionCode = "ACTIVE_MASTER_MATERIAL")` |
+
+## 2.7 实现要点
+
+1. **批量API单条使用**：后端使用 `/batchActive` 批量接口，但 CLI 仅支持单条启用，将单个 ID 包装为单元素数组 `{ materialIdList: [id] }`
+2. **幂等性**：batchActive 操作是幂等的，对已启用的物料再次调用效果相同（直接设置 statusFlag=ENABLE）
+3. **Dry-run模式**：预览显示将启用的物料信息，但不实际发送请求
+4. **无强制选项**：--force 跳过确认提示，但不绕过后端权限检查
+5. **与disable对称**：enable 与 disable 互为逆操作，使用相同的 materialIdList 参数结构
+
+## 2.8 示例用法
+
+```bash
+# 启用物料（交互确认）
+barista liberica materials enable 12345
+
+# 跳过确认直接启用
+barista liberica materials enable 12345 --force
+
+# Dry-run 预览
+barista liberica materials enable 12345 --dry-run
+
+# JSON 输出
+barista liberica materials enable 12345 --force --json
+
+# 物料不存在
+barista liberica materials enable 99999
+# 输出: Error: 租户物料不存在 (01001410001)
+
+# 对已启用物料重复启用（幂等，无报错）
+barista liberica materials enable 12345 --force
+# 输出: ✓ 物料启用成功
+```