@newpeak/barista-cli 0.1.4 → 0.1.5

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

@@ -0,0 +1,188 @@
+# barista liberica materials get
+
+获取单个物料详情。
+
+## 2.1 命令元数据
+
+| 字段 | 值 |
+|------|-----|
+| 完整命令 | `barista liberica materials get <id>` |
+| 功能描述 | 获取单个物料详情 |
+| HTTP方法 | GET |
+| 是否需要认证 | ✅ 是 |
+| 是否支持dry-run | ⬜ 否 |
+
+## 2.2 后端接口引用
+
+### Controller位置
+```
+coffee-liberica-end/
+└── facade/liberica-facade-enterprise/
+    └── src/main/java/com/newpeak/liberica/facade/enterprise/controller/master/
+        └── EnterpriseMaterialController.java
+            └── detail(@GetResource(path = "/detail"))
+                └── public ResponseData<MasterMaterialResponse> detail(
+                        @RequestHeader("X-TENANT-ID") Long tenantId,
+                        @ParameterObject @Validated(BaseRequest.detail.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 detail)
+```
+
+### 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
+            ├── materialShortName: String
+            ├── materialMaker: String
+            ├── materialTags: Tags
+            ├── materialTagNames: List<String>
+            ├── materialClass: String
+            ├── mouldType: String
+            ├── materialBarCode: String
+            ├── materialType: String
+            ├── materialUomCode: String
+            ├── enableMultiUom: String (Y/N)
+            ├── multiUomCodes: MultiUom
+            ├── enableSale: String (Y/N)
+            ├── enablePurchase: String (Y/N)
+            ├── enableSubMaterial: String (Y/N)
+            ├── enableOutsourcing: String (Y/N)
+            ├── enableDivision: String (Y/N)
+            ├── enableShelfLifeManagement: String (Y/N)
+            ├── stopProduction: String (Y/N)
+            ├── shelfLifeUnit: String
+            ├── shelfLife: Integer
+            ├── shelfLifeWarningDays: Integer
+            ├── shippingMethod: String
+            ├── transactionMethod: String
+            ├── tradeType: String
+            ├── productionPeriod: Integer
+            ├── productionQuantityPerLot: BigDecimal
+            ├── lowLotRate: Float
+            ├── useMaterialLotRate: String (Y/N)
+            ├── substituteMaterials: SubstituteMaterials
+            ├── safetyInventory: BigDecimal
+            ├── defaultWarehouse: String
+            ├── defaultSupplier: String
+            ├── follower: String
+            ├── minPackageQuantity: String
+            ├── grossWeight: String
+            ├── netWeight: String
+            ├── color: String
+            ├── longX: BigDecimal
+            ├── longXUom: String
+            ├── wideY: BigDecimal
+            ├── wideYUom: String
+            ├── highZ: BigDecimal
+            ├── highZUom: String
+            ├── volume: String
+            ├── volumeUom: String
+            ├── thickness: BigDecimal
+            ├── thicknessUom: String
+            ├── totalThickness: BigDecimal
+            ├── diameter: BigDecimal
+            ├── diameterUom: String
+            ├── outerDiameter: BigDecimal
+            ├── outerDiameterUom: String
+            ├── innerDiameter: BigDecimal
+            ├── innerDiameterUom: String
+            ├── defaultClient: String
+            ├── unitPrice: BigDecimal
+            ├── currency: String
+            ├── statusFlag: Integer (1=enable, 2=disable)
+            ├── remark: String
+            ├── salesOrderCount: String
+            ├── salesOrderSummary: String
+            ├── createTime: String
+            └── updateTime: String
+```
+
+## 2.3 CLI参数设计
+
+### 命令结构
+```
+barista liberica materials get <id> [options]
+```
+
+### 位置参数
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| id | string | ✅ | 物料ID (materialId) |
+
+### 全局选项
+| 选项 | 类型 | 说明 |
+|------|------|------|
+| `--env` | string | 目标环境(dev\|test\|prod-cn\|prod-jp) |
+| `--tenant` | string | 租户代码 |
+| `--json` | boolean | JSON输出 |
+
+### 命令选项
+| 选项 | 短选项 | 类型 | 必填 | 默认值 | 说明 |
+|------|--------|------|------|--------|------|
+| — | — | — | — | — | 此命令无额外选项，ID 通过位置参数传入 |
+
+## 2.4 字段映射表
+
+| CLI参数 | DTO字段 | 类型转换 | 验证规则 |
+|---------|---------|----------|----------|
+| <id> (位置参数) | materialId | string→Long | @NotNull, 必须为正整数 |
+
+## 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("01001340001", "租户物料不存在")
+            ├── MASTER_MATERIAL_CODE_VALIDATE_NOT_EXIST_ERROR("01001340006", "指定{}不存在")
+            └── MASTER_MATERIAL_NAME_VALIDATE_NOT_EXIST_ERROR("01001340010", "指定{}不存在")
+```
+
+### 已知错误码
+| 错误码 | 错误消息 | 触发条件 |
+|--------|----------|----------|
+| 01001340001 | 租户物料不存在 | materialId 不存在或不属于当前租户 |
+
+## 2.6 权限检查
+
+| 检查项 | 位置 | 说明 |
+|--------|------|------|
+| 注解 | `@GetResource(path = "/detail")` | 无 requiredPermission |
+
+## 2.7 实现要点
+
+1. **位置参数**：`get` 命令使用 `<id>` 位置参数指定物料ID
+2. **错误处理**：物料不存在时抛出 `MASTER_MATERIAL_NOT_EXIST`，CLI 显示友好错误信息
+3. **tenantId来源**：来自 X-TENANT-ID header，后端自动按租户隔离数据
+4. **API端点**：GET `/api/enterprise/sales/material/detail?materialId={id}`
+5. **ID类型注意**：后端使用 Long (BigInteger) 类型，CLI 中使用 string 避免 JavaScript 精度丢失
+
+## 2.8 示例用法
+
+```bash
+# 获取物料详情
+barista liberica materials get 12345
+
+# JSON 输出
+barista liberica materials get 12345 --json
+
+# 物料不存在
+barista liberica materials get 99999
+# 输出: Error: 租户物料不存在 (01001340001)
+```

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

@@ -0,0 +1,198 @@
+# barista liberica materials list
+
+分页查询物料列表。
+
+## 2.1 命令元数据
+
+| 字段 | 值 |
+|------|-----|
+| 完整命令 | `barista liberica materials list` |
+| 功能描述 | 分页查询物料列表 |
+| HTTP方法 | GET |
+| 是否需要认证 | ✅ 是 |
+| 是否支持dry-run | ⬜ 否 |
+
+## 2.2 后端接口引用
+
+### Controller位置
+```
+coffee-liberica-end/
+└── facade/liberica-facade-enterprise/
+    └── src/main/java/com/newpeak/liberica/facade/enterprise/controller/master/
+        └── EnterpriseMaterialController.java
+            └── page(@GetResource(path = "/page"))
+                └── public ResponseData<PageResult<MasterMaterialResponse>> page(
+                        @RequestHeader("X-TENANT-ID") Long tenantId,
+                        @ParameterObject 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
+            ├── pageNo: Long (分页页码，从0开始)
+            ├── pageSize: Long (分页大小)
+            ├── materialId: Long (物料ID)
+            ├── materialCode: String (物料编码)
+            ├── materialNo: String (物料号码)
+            ├── materialName: String (物料名称)
+            ├── materialClass: String (物料类别)
+            ├── statusFlag: Integer (状态：1=启用，2=禁用)
+            ├── queryMaterialTags: List<String> (物料标签查询条件)
+            ├── queryMaterialClass: List<String> (物料类别查询条件)
+            ├── queryMaterialCode: Set<String> (物料编码范围查询条件)
+            └── excludeMaterialCode: Set<String> (排除物料编码范围查询条件)
+```
+
+### 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
+            ├── materialShortName: String
+            ├── materialMaker: String
+            ├── materialTags: Tags
+            ├── materialClass: String
+            ├── materialBarCode: String
+            ├── materialType: String
+            ├── materialUomCode: String
+            ├── enableMultiUom: String (Y/N)
+            ├── enableSale: String (Y/N)
+            ├── enablePurchase: String (Y/N)
+            ├── enableSubMaterial: String (Y/N)
+            ├── enableOutsourcing: String (Y/N)
+            ├── enableDivision: String (Y/N)
+            ├── enableShelfLifeManagement: String (Y/N)
+            ├── stopProduction: String (Y/N)
+            ├── safetyInventory: BigDecimal
+            ├── defaultWarehouse: String
+            ├── defaultSupplier: String
+            ├── follower: String
+            ├── unitPrice: BigDecimal
+            ├── currency: String
+            ├── statusFlag: Integer (1=启用，2=禁用)
+            ├── remark: String
+            ├── createTime: String
+            └── updateTime: String
+```
+
+### 分页包装器
+```
+cn.stylefeng.roses.kernel.db.api.pojo.page.PageResult
+    ├── totalRows: long
+    ├── pageSize: long
+    ├── pageNo: long
+    └── rows: List<MasterMaterialResponse>
+```
+
+## 2.3 CLI参数设计
+
+### 命令结构
+```
+barista liberica materials list [options]
+```
+
+### 全局选项
+| 选项 | 类型 | 说明 |
+|------|------|------|
+| `--env` | string | 目标环境(dev\|test\|prod-cn\|prod-jp) |
+| `--tenant` | string | 租户代码 |
+| `--json` | boolean | JSON输出 |
+
+### 命令选项
+| 选项 | 短选项 | 类型 | 必填 | 默认值 | 说明 | 对应DTO字段 |
+|------|--------|------|------|--------|------|-------------|
+| --page | -p | number | ⬜ | 1 | 页码（从1开始） | pageNo (转换：CLI页码-1) |
+| --size | -s | number | ⬜ | 20 | 每页条数 | pageSize |
+| --status | — | string | ⬜ | - | 状态：enable/disable | statusFlag (enable=1, disable=2) |
+| --class | -c | string | ⬜ | - | 物料类别 | queryMaterialClass |
+| --keyword | -k | string | ⬜ | - | 搜索关键词（物料编码/物料号码/物料名称） | materialCode/materialNo/materialName |
+
+## 2.4 字段映射表
+
+| CLI参数 | DTO字段 | 类型转换 | 验证规则 |
+|---------|---------|----------|----------|
+| --page / -p | pageNo | number→Long，CLI页码-1 | >= 1 |
+| --size / -s | pageSize | number→Long | 1-100 |
+| --status | statusFlag | string→Integer | enable=1, disable=2 |
+| --class / -c | queryMaterialClass | string→List<String> | - |
+| --keyword / -k | materialCode/materialNo/materialName | 直接传递 | 模糊查询 |
+
+## 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("01001411001", "租户物料不存在")
+            ├── MASTER_MATERIAL_CODE_FORMAT_CANNOT_EMPTY("01001411003", "物料编码规则不能为空")
+            ├── MASTER_MATERIAL_CODE_FORMAT_NOT_CORRECT("01001411004", "物料编码规则格式不正确")
+            ├── MASTER_MATERIAL_CODE_VALIDATE_EMPTY_ERROR("01001411005", "{}不能为空")
+            ├── MASTER_MATERIAL_CODE_VALIDATE_NOT_EXIST_ERROR("01001411006", "指定{}不存在")
+            ├── MASTER_MATERIAL_NO_VALIDATE_EMPTY_ERROR("01001411007", "{}不能为空")
+            ├── MASTER_MATERIAL_NO_VALIDATE_NOT_EXIST_ERROR("01001411008", "指定{}不存在")
+            ├── MASTER_MATERIAL_NAME_VALIDATE_EMPTY_ERROR("01001411009", "{}不能为空")
+            ├── MASTER_MATERIAL_NAME_VALIDATE_NOT_EXIST_ERROR("01001411010", "指定{}不存在")
+            └── MASTER_MATERIAL_NAME_DOES_NOT_MATCH_NO_ERROR("01001411011", "{}与{}不匹配")
+```
+
+### 已知错误码
+| 错误码 | 错误消息 | 触发条件 |
+|--------|----------|----------|
+| 01001411001 | 租户物料不存在 | 查询详情时ID不存在 |
+| 01001411006 | 指定物料编码不存在 | 物料编码无效 |
+| 01001411008 | 指定物料号码不存在 | 物料号码无效 |
+| 01001411010 | 指定物料名称不存在 | 物料名称无效 |
+
+## 2.6 权限检查
+
+| 检查项 | 位置 | 说明 |
+|--------|------|------|
+| 注解 | `@GetResource(path = "/page")` | 无 requiredPermission（无需权限码） |
+
+**注意**：page 接口在 Controller 层无需权限校验，数据范围通过 tenantId 隔离。
+
+## 2.7 实现要点
+
+1. **分页默认值**：page=1, size=20
+2. **分页转换**：CLI使用1-based页码，API使用0-based页码（调用时需减1）
+3. **搜索行为**：keyword 同时匹配 materialCode、materialNo 和 materialName（模糊查询）
+4. **状态映射**：CLI参数 `enable`/`disable` 映射到 API 值 `1`/`2`
+5. **无结果处理**：返回空列表，不抛出异常
+6. **tenantId来源**：来自 JWT token（无需 X-TENANT-ID header）
+7. **输出格式**：表格形式展示，分页信息在底部显示
+
+## 2.8 示例用法
+
+```bash
+# 默认分页
+barista liberica materials list
+
+# 指定页码和每页条数
+barista liberica materials list --page 2 --size 50
+
+# 按状态筛选
+barista liberica materials list --status enable
+
+# 按物料类别筛选
+barista liberica materials list --class "raw_material"
+
+# 关键词搜索
+barista liberica materials list --keyword "螺丝"
+
+# 组合筛选
+barista liberica materials list --page 1 --size 10 --status enable --keyword "M001"
+
+# JSON 输出（便于脚本处理）
+barista liberica materials list --page 1 --size 20 --json
+```

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

@@ -0,0 +1,250 @@
+# barista liberica materials update
+
+更新物料信息。
+
+## 2.1 命令元数据
+
+| 字段 | 值 |
+|------|-----|
+| 完整命令 | `barista liberica materials update <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
+            └── edit(@PostResource(path = "/edit", requiredPermission = true, requirePermissionCode = "EDIT_MASTER_MATERIAL"))
+                └── public ResponseData<?> edit(
+                        @RequestHeader("X-TENANT-ID") Long tenantId,
+                        @RequestBody @Validated(BaseRequest.edit.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 edit) — 必须提供
+            ├── materialCode: String
+            ├── materialNo: String
+            ├── materialName: String
+            ├── materialShortName: String
+            ├── materialMaker: String
+            ├── materialClass: String
+            ├── materialType: String
+            ├── materialUomCode: String
+            ├── materialBarCode: String
+            ├── enableSale: String (Y/N)
+            ├── enablePurchase: String (Y/N)
+            ├── enableSubMaterial: String (Y/N)
+            ├── enableOutsourcing: String (Y/N)
+            ├── enableDivision: String (Y/N)
+            ├── productionPeriod: Integer
+            ├── unitPrice: BigDecimal
+            ├── currency: String
+            ├── defaultWarehouse: String
+            ├── defaultSupplier: String
+            ├── defaultClient: String
+            ├── safetyInventory: BigDecimal
+            ├── longX: BigDecimal
+            ├── wideY: BigDecimal
+            ├── highZ: BigDecimal
+            ├── thickness: BigDecimal
+            ├── grossWeight: String
+            ├── netWeight: String
+            ├── color: String
+            └── remark: String
+```
+
+### 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
+            ├── materialShortName: String
+            ├── materialClass: String
+            ├── materialType: String
+            ├── materialUomCode: String
+            ├── statusFlag: Integer (1=enable, 2=disable)
+            ├── createTime: String
+            └── updateTime: String
+```
+
+## 2.3 CLI参数设计
+
+### 命令结构
+```
+barista liberica materials update <materialId> [options]
+```
+
+### 位置参数
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| materialId | string | ✅ | 物料ID (materialId) |
+
+### 全局选项
+| 选项 | 类型 | 说明 |
+|------|------|------|
+| `--env` | string | 目标环境(dev\|test\|prod-cn\|prod-jp) |
+| `--tenant` | string | 租户代码 |
+| `--dry-run` | boolean | 预览模式（不实际调用API） |
+| `--json` | boolean | JSON输出 |
+
+### 命令选项
+| 选项 | 短选项 | 类型 | 必填 | 默认值 | 说明 | 对应DTO字段 |
+|------|--------|------|------|--------|------|-------------|
+| --name | -n | string | ⬜ | - | 物料名称 | materialName |
+| --class | -c | string | ⬜ | - | 物料类别 | materialClass |
+| --type | -t | string | ⬜ | - | 规格型号 | materialType |
+| --unit | -u | string | ⬜ | - | 计量单位 | materialUomCode |
+| --short-name | — | string | ⬜ | - | 物料简称 | materialShortName |
+| --maker | — | string | ⬜ | - | 生产厂商 | materialMaker |
+| --barcode | — | string | ⬜ | - | 条形码 | materialBarCode |
+| --enable-sale | — | boolean | ⬜ | - | 可销售 | enableSale |
+| --enable-purchase | — | boolean | ⬜ | - | 可采购 | enablePurchase |
+| --enable-sub-material | — | boolean | ⬜ | - | 可为子件 | enableSubMaterial |
+| --enable-outsourcing | — | boolean | ⬜ | - | 可委外 | enableOutsourcing |
+| --enable-division | — | boolean | ⬜ | - | 可切割 | enableDivision |
+| --production-period | — | number | ⬜ | - | 生产周期(天) | productionPeriod |
+| --unit-price | — | number | ⬜ | - | 单价 | unitPrice |
+| --currency | — | string | ⬜ | - | 币种 | currency |
+| --default-warehouse | — | string | ⬜ | - | 默认仓库 | defaultWarehouse |
+| --default-supplier | — | string | ⬜ | - | 默认供应商 | defaultSupplier |
+| --default-client | — | string | ⬜ | - | 默认客户 | defaultClient |
+| --safety-inventory | — | number | ⬜ | - | 安全库存 | safetyInventory |
+| --long-x | — | number | ⬜ | - | 长 | longX |
+| --wide-y | — | number | ⬜ | - | 宽 | wideY |
+| --high-z | — | number | ⬜ | - | 高 | highZ |
+| --thickness | — | number | ⬜ | - | 厚度 | thickness |
+| --gross-weight | — | string | ⬜ | - | 毛重 | grossWeight |
+| --net-weight | — | string | ⬜ | - | 净重 | netWeight |
+| --color | — | string | ⬜ | - | 颜色 | color |
+| --remark | -r | string | ⬜ | - | 备注 | remark |
+
+**注意**：物料ID(materialId)为必填，通过位置参数 `<materialId>` 传入。后端处理部分更新，未提供的字段保持原值。
+
+## 2.4 字段映射表
+
+| CLI参数 | DTO字段 | 类型转换 | 验证规则 |
+|---------|---------|----------|----------|
+| <materialId> (位置参数) | materialId | string→Long | @NotNull |
+| --name / -n | materialName | 直接传递 | max=255 |
+| --class / -c | materialClass | 直接传递 | max=255 |
+| --type / -t | materialType | 直接传递 | max=255 |
+| --unit / -u | materialUomCode | 直接传递 | max=255 |
+| --short-name | materialShortName | 直接传递 | max=255 |
+| --maker | materialMaker | 直接传递 | max=255 |
+| --barcode | materialBarCode | 直接传递 | max=255 |
+| --enable-sale | enableSale | boolean→String | Y 或 N |
+| --enable-purchase | enablePurchase | boolean→String | Y 或 N |
+| --enable-sub-material | enableSubMaterial | boolean→String | Y 或 N |
+| --enable-outsourcing | enableOutsourcing | boolean→String | Y 或 N |
+| --enable-division | enableDivision | boolean→String | Y 或 N |
+| --production-period | productionPeriod | number→Integer | - |
+| --unit-price | unitPrice | number→BigDecimal | - |
+| --currency | currency | 直接传递 | max=255 |
+| --default-warehouse | defaultWarehouse | 直接传递 | max=255 |
+| --default-supplier | defaultSupplier | 直接传递 | max=255 |
+| --default-client | defaultClient | 直接传递 | max=255 |
+| --safety-inventory | safetyInventory | number→BigDecimal | - |
+| --long-x | longX | number→BigDecimal | - |
+| --wide-y | wideY | number→BigDecimal | - |
+| --high-z | highZ | number→BigDecimal | - |
+| --thickness | thickness | number→BigDecimal | - |
+| --gross-weight | grossWeight | 直接传递 | max=255 |
+| --net-weight | netWeight | 直接传递 | max=255 |
+| --color | color | 直接传递 | max=255 |
+| --remark / -r | remark | 直接传递 | max=255 |
+
+## 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("01001512001", "租户物料不存在")
+            ├── MASTER_MATERIAL_CODE_VALIDATE_NOT_EXIST_ERROR("01001512006", "指定{}不存在")
+            ├── MASTER_MATERIAL_NAME_VALIDATE_NOT_EXIST_ERROR("01001512010", "指定{}不存在")
+            ├── ENABLE_DIVISION_MATERIAL_NEED_WIDE_AND_LONG("01001512012", "可分割物料必须设置长和宽")
+            └── ENABLE_DIVISION_MATERIAL_NEED_WIDE_AND_LONG_GT_ZERO("01001512013", "可分割物料长和宽必须大于0")
+```
+
+### 已知错误码
+| 错误码 | 错误消息 | 触发条件 |
+|--------|----------|----------|
+| 01001512001 | 租户物料不存在 | materialId 不存在或不属于当前租户 |
+| 01001512006 | 指定xxx不存在 | 指定关联的物料编码不存在 |
+| 01001512012 | 可分割物料必须设置长和宽 | 设置enableDivision=Y但未提供长宽 |
+| 01001512013 | 可分割物料长和宽必须大于0 | 设置enableDivision=Y且长宽<=0 |
+
+## 2.6 权限检查
+
+| 检查项 | 位置 | 说明 |
+|--------|------|------|
+| PermissionConstants | `MasterMaterialPermissionConstants.EDIT_MASTER_MATERIAL` | Controller层 `@PostResource(requirePermissionCode = "EDIT_MASTER_MATERIAL")` |
+
+## 2.7 实现要点
+
+1. **materialId位置参数**：`<materialId>` 通过位置参数传入，映射到 `materialId` 字段
+2. **请求体结构**：必须将 `materialId` 包含在请求体中，后端通过此ID定位记录
+3. **部分更新**：只发送需要更新的字段，未提供的字段保持原值
+4. **Dry-run支持**：使用 --dry-run 时构造请求体但不发送，显示预览信息
+5. **后端验证**：edit() 方法调用 `masterMaterialBusiness.edit()`，后端会校验物料是否存在
+
+## 2.8 示例用法
+
+```bash
+# 更新物料名称
+barista liberica materials update 12345 --name "新产品名称"
+
+# 更新物料类别和规格
+barista liberica materials update 12345 \
+  --class "原材料" \
+  --type "ABC-001" \
+  --unit "KG"
+
+# 更新价格信息
+barista liberica materials update 12345 \
+  --unit-price 100.50 \
+  --currency "CNY"
+
+# 启用可销售属性
+barista liberica materials update 12345 --enable-sale true
+
+# 同时更新多个字段
+barista liberica materials update 12345 \
+  --name "新产品" \
+  --class "成品" \
+  --type "XYZ-999" \
+  --unit "PCS" \
+  --unit-price 299.99 \
+  --enable-sale true \
+  --enable-purchase true \
+  --remark "更新备注信息"
+
+# Dry-run 预览
+barista liberica materials update 12345 --name "新产品" --dry-run
+
+# JSON 输出
+barista liberica materials update 12345 --name "新产品" --json
+
+# 物料不存在
+barista liberica materials update 99999 --name "测试"
+# 输出: Error: 租户物料不存在 (01001512001)
+```