@newpeak/barista-cli 0.1.4 → 0.1.6

package/docs/commands/liberica/currency/create.md

@@ -0,0 +1,145 @@
+# barista liberica currency create
+
+创建新的币种。
+
+## 2.1 命令元数据
+
+| 字段 | 值 |
+|------|-----|
+| 完整命令 | `barista liberica currency create` |
+| 功能描述 | 创建新的币种 |
+| HTTP方法 | POST |
+| 是否需要认证 | ✅ 是 |
+| 是否支持dry-run | ✅ 是 |
+
+## 2.2 后端接口引用
+
+### Controller位置
+```
+coffee-liberica-end/
+└── facade/liberica-facade-enterprise/
+    └── src/main/java/com/newpeak/liberica/facade/enterprise/controller/finance/
+        └── FinanceCurrencyController.java
+            └── addCurrency(@PostResource(path = "/add"))
+                └── public ResponseData<CurrencyResponse> addCurrency(
+                        @RequestBody @Validated CurrencyRequest request
+                    )
+```
+
+### Request DTO位置
+```
+coffee-liberica-end/
+└── business/liberica-business-finance/finance-api/src/main/java/com/newpeak/liberica/finance/api/pojo/request/CurrencyRequest.java
+    ├── currencyCode: String (@NotBlank, 3位编码)
+    ├── currencyName: String (@NotBlank)
+    └── currencySign: String (符号，如 ¥, $)
+```
+
+### Response DTO位置
+```
+coffee-liberica-end/
+└── business/liberica-business-finance/finance-api/src/main/java/com/newpeak/liberica/finance/api/pojo/response/CurrencyResponse.java
+    ├── currencyId: String
+    ├── currencyCode: String (3位编码)
+    ├── currencyName: String
+    ├── currencySign: String
+    ├── statusFlag: Integer (1=启用)
+    ├── createTime: String
+    └── updateTime: String
+```
+
+### 辅助接口（创建流程内部使用）
+```
+coffee-liberica-end/
+└── facade/liberica-facade-platform/
+    └── src/main/java/com/newpeak/liberica/facade/platform/controller/
+        └── MasterCurrencyController.java
+            └── getAvailableList(@GetResource(path = "/available/list"))
+                └── 获取可用币种列表（用于选择currencyCode）
+            └── getCurrencyDefault(@GetResource(path = "/currency/default"))
+                └── 获取币种默认值（根据currencyCode自动填充名称和符号）
+```
+
+## 2.3 CLI参数设计
+
+### 命令结构
+```
+barista liberica currency create [options]
+```
+
+### 全局选项
+| 选项 | 类型 | 说明 |
+|------|------|------|
+| `--env` | string | 目标环境(dev\|test\|prod-cn\|prod-jp) |
+| `--tenant` | string | 租户代码 |
+| `--dry-run` | boolean | 预览模式 |
+| `--json` | boolean | JSON输出 |
+
+### 命令选项
+| 选项 | 短选项 | 类型 | 必填 | 默认值 | 说明 | 对应DTO字段 |
+|------|--------|------|------|--------|------|-------------|
+| --code | -c | string | ✅ | - | 币种编码（3位，如 CNY） | currencyCode |
+| --name | -n | string | ⬜ | - | 币种名称（可自动填充） | currencyName |
+| --sign | -S | string | ⬜ | - | 币种符号（可自动填充，如 ¥） | currencySign |
+
+## 2.4 字段映射表
+
+| CLI参数 | DTO字段 | 类型转换 | 验证规则 |
+|---------|---------|----------|----------|
+| --code / -c | currencyCode | string→String | @NotBlank, 3位字母, ISO 4217 |
+| --name / -n | currencyName | string→String | @NotBlank, max=255 |
+| --sign / -S | currencySign | string→String | max=10 |
+
+## 2.5 错误码引用
+
+### ExceptionEnum位置
+```
+coffee-liberica-end/
+└── business/liberica-business-finance/finance-api/src/main/java/com/newpeak/liberica/finance/api/exception/enums/CurrencyExceptionEnum.java
+```
+
+### 已知错误码
+| 错误码 | 错误消息 | 触发条件 |
+|--------|----------|----------|
+| CURRENCY_CODE_DUPLICATE | 币种编码重复 | 编码重复 |
+| CURRENCY_CODE_EMPTY | 币种编码不能为空 | 编码为空 |
+| CURRENCY_NAME_EMPTY | 币种名称不能为空 | 名称为空 |
+| CURRENCY_CODE_INVALID | 币种编码无效 | 非标准3位编码 |
+
+## 2.6 权限检查
+
+| 检查项 | 位置 | 说明 |
+|--------|------|------|
+| 注解 | FinanceCurrencyController.java | 需要 `finance_currency:add` 权限 |
+
+## 2.7 实现要点
+
+1. **必填参数**：currencyCode 为必填参数，currencyName 和 currencySign 可自动填充
+2. **自动填充流程**：
+   - 用户输入 currencyCode（如 CNY）
+   - 调用 `/master/currency/currency/default` 获取默认值
+   - 自动填充 currencyName（人民币）和 currencySign（¥）
+3. **编码规范**：currencyCode 必须为3位字母，符合ISO 4217标准
+4. **dry-run 支持**：支持 `--dry-run` 预览模式，显示将要创建的币种信息
+5. **编码唯一性**：后端会校验 currencyCode 是否已存在
+6. **状态默认**：新创建币种默认状态为启用（statusFlag=1）
+7. **API路径**：POST `/api/enterprise/finance/currency/add`
+8. **成功响应**：返回创建的币种详情，包括生成的 currencyId
+
+## 2.8 示例用法
+
+```bash
+# 创建币种（自动填充名称和符号）
+barista liberica currency create --code "CNY"
+barista liberica currency create -c "USD"
+
+# 创建并指定完整信息
+barista liberica currency create --code "EUR" --name "欧元" --sign "€"
+barista liberica currency create -c "JPY" -n "日元" -S "¥"
+
+# 预览模式（dry-run）
+barista liberica currency create --code "GBP" --dry-run
+
+# JSON 输出
+barista liberica currency create --code "CNY" --json
+```

package/docs/commands/liberica/currency/delete.md

@@ -0,0 +1,121 @@
+# barista liberica currency delete
+
+删除币种。
+
+## 2.1 命令元数据
+
+| 字段 | 值 |
+|------|-----|
+| 完整命令 | `barista liberica currency delete <currency-id>` |
+| 功能描述 | 删除币种 |
+| HTTP方法 | POST |
+| 是否需要认证 | ✅ 是 |
+| 是否支持dry-run | ⬜ 否 |
+
+## 2.2 后端接口引用
+
+### Controller位置
+```
+coffee-liberica-end/
+└── facade/liberica-facade-enterprise/
+    └── src/main/java/com/newpeak/liberica/facade/enterprise/controller/finance/
+        └── FinanceCurrencyController.java
+            └── deleteCurrency(@PostResource(path = "/delete"))
+                └── public ResponseData<Void> deleteCurrency(
+                        @RequestBody CurrencyRequest request
+                    )
+```
+
+### Request DTO位置
+```
+coffee-liberica-end/business/liberica-business-finance/finance-api/src/main/java/com/newpeak/liberica/finance/api/pojo/request/CurrencyRequest.java
+- 删除请求使用：{ currencyId: String }
+```
+
+### Response DTO位置
+```
+- 返回 void 或成功标记（ResponseData<Void>）
+```
+
+## 2.3 CLI参数设计
+
+### 命令结构
+```
+barista liberica currency delete <currency-id> [options]
+```
+
+### 全局选项
+| 选项 | 类型 | 说明 |
+|------|------|------|
+| `--env` | string | 目标环境(dev\|test\|prod-cn\|prod-jp) |
+| `--tenant` | string | 租户代码 |
+| `--json` | boolean | JSON输出 |
+
+### 位置参数
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| currency-id | string | ✅ | 币种ID |
+
+### 命令选项
+| 选项 | 短选项 | 类型 | 必填 | 默认值 | 说明 | 对应DTO字段 |
+|------|--------|------|------|--------|------|-------------|
+| --currency-id | -i | string | ⬜ | - | 币种ID（与位置参数互斥） | currencyId |
+| --force | -f | boolean | ⬜ | false | 强制删除，跳过确认提示 | - |
+
+## 2.4 字段映射表
+
+| CLI参数 | DTO字段 | 类型转换 | 验证规则 |
+|---------|---------|----------|----------|
+| currency-id (位置参数) | currencyId | string→String | @NotBlank |
+| --currency-id / -i | currencyId | string→String | @NotBlank |
+
+## 2.5 错误码引用
+
+### ExceptionEnum位置
+```
+coffee-liberica-end/
+└── business/liberica-business-finance/finance-api/src/main/java/com/newpeak/liberica/finance/api/exception/enums/CurrencyExceptionEnum.java
+```
+
+### 已知错误码
+| 错误码 | 错误消息 | 触发条件 |
+|--------|----------|----------|
+| CURRENCY_NOT_EXIST | 币种不存在 | 币种不存在 |
+| CURRENCY_IN_USE | 币种已被使用，无法删除 | 币种已被财务单据引用 |
+| CURRENCY_NO_PERMISSION | 无权限删除 | 无权限删除 |
+| CURRENCY_CANNOT_DELETE_BASE | 基础币种不能删除 | 系统预设币种无法删除 |
+
+## 2.6 权限检查
+
+| 检查项 | 位置 | 说明 |
+|--------|------|------|
+| 注解 | FinanceCurrencyController.java | 需要 `finance_currency:remove` 权限 |
+
+## 2.7 实现要点
+
+1. **ID必填**：currencyId为必填参数（位置参数或 --currency-id 选项）
+2. **确认提示**：默认会显示确认提示，需要用户确认（除非使用 --force）
+3. **强制删除**：使用 `--force` 或 `-f` 跳过确认提示
+4. **依赖检查**：后端可能会检查币种是否被财务单据引用
+5. **基础币种保护**：系统预设币种（如 CNY）可能无法删除
+6. **不可恢复**：删除操作不可逆，需谨慎操作
+7. **API路径**：POST `/api/enterprise/finance/currency/delete`
+8. **批量删除**：未来可能支持批量删除（通过逗号分隔的ID列表）
+
+## 2.8 示例用法
+
+```bash
+# 删除币种（带确认提示）
+barista liberica currency delete "1234567890123456789"
+
+# 通过选项参数删除
+barista liberica currency delete --currency-id "1234567890123456789"
+barista liberica currency delete -i "1234567890123456789"
+
+# 强制删除（跳过确认）
+barista liberica currency delete "1234567890123456789" --force
+barista liberica currency delete "1234567890123456789" -f
+
+# JSON 输出
+barista liberica currency delete "1234567890123456789" --force --json
+```

package/docs/commands/liberica/currency/disable.md

@@ -0,0 +1,119 @@
+# barista liberica currency disable
+
+禁用币种（批量）。
+
+## 2.1 命令元数据
+
+| 字段 | 值 |
+|------|-----|
+| 完整命令 | `barista liberica currency disable <currency-id...>` |
+| 功能描述 | 禁用一个或多个币种 |
+| HTTP方法 | POST |
+| 是否需要认证 | ✅ 是 |
+| 是否支持dry-run | ⬜ 否 |
+
+## 2.2 后端接口引用
+
+### Controller位置
+```
+coffee-liberica-end/
+└── facade/liberica-facade-enterprise/
+    └── src/main/java/com/newpeak/liberica/facade/enterprise/controller/finance/
+        └── FinanceCurrencyController.java
+            └── batchDeActive(@PostResource(path = "/batchDeActive"))
+                └── public ResponseData<Void> batchDeActive(
+                        @RequestBody Map<String, List<String>> request
+                    )
+```
+
+### Request DTO位置
+```
+- 批量禁用请求：{ currencyIdList: List<String> }
+```
+
+### Response DTO位置
+```
+- 返回 void 或成功标记（ResponseData<Void>）
+```
+
+## 2.3 CLI参数设计
+
+### 命令结构
+```
+barista liberica currency disable <currency-id...> [options]
+```
+
+### 全局选项
+| 选项 | 类型 | 说明 |
+|------|------|------|
+| `--env` | string | 目标环境(dev\|test\|prod-cn\|prod-jp) |
+| `--tenant` | string | 租户代码 |
+| `--json` | boolean | JSON输出 |
+
+### 位置参数
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| currency-id... | string | ✅ | 一个或多个币种ID |
+
+### 命令选项
+| 选项 | 短选项 | 类型 | 必填 | 默认值 | 说明 | 对应DTO字段 |
+|------|--------|------|------|--------|------|-------------|
+| --currency-id | -i | string | ⬜ | - | 币种ID（逗号分隔，与位置参数互斥） | currencyIdList |
+
+## 2.4 字段映射表
+
+| CLI参数 | DTO字段 | 类型转换 | 验证规则 |
+|---------|---------|----------|----------|
+| currency-id... (位置参数) | currencyIdList | string[]→List<String> | 至少一个ID |
+| --currency-id / -i | currencyIdList | string→List<String> | 逗号分隔 |
+
+## 2.5 错误码引用
+
+### ExceptionEnum位置
+```
+coffee-liberica-end/
+└── business/liberica-business-finance/finance-api/src/main/java/com/newpeak/liberica/finance/api/exception/enums/CurrencyExceptionEnum.java
+```
+
+### 已知错误码
+| 错误码 | 错误消息 | 触发条件 |
+|--------|----------|----------|
+| CURRENCY_NOT_EXIST | 币种不存在 | 币种不存在 |
+| CURRENCY_IN_USE | 币种已被使用，无法禁用 | 币种已被财务单据引用 |
+| CURRENCY_NO_PERMISSION | 无权限操作 | 无权限操作 |
+| CURRENCY_CANNOT_DISABLE_BASE | 基础币种不能禁用 | 系统预设币种无法禁用 |
+
+## 2.6 权限检查
+
+| 检查项 | 位置 | 说明 |
+|--------|------|------|
+| 注解 | FinanceCurrencyController.java | 需要 `finance_currency:edit` 权限 |
+
+## 2.7 实现要点
+
+1. **批量支持**：支持单个ID或多个ID（空格分隔）
+2. **ID来源**：可通过位置参数或 --currency-id 选项传递
+3. **逗号分隔**：--currency-id 选项支持逗号分隔的多个ID
+4. **状态变更**：将 statusFlag 从 1（启用）改为 2（禁用）
+5. **依赖检查**：后端可能会检查币种是否被财务单据引用
+6. **基础币种保护**：系统预设币种（如 CNY）可能无法禁用
+7. **部分失败**：如果某些ID不存在，后端可能返回错误或仅处理存在的ID
+8. **API路径**：POST `/api/enterprise/finance/currency/batchDeActive`
+9. **请求格式**：{ currencyIdList: ["id1", "id2", ...] }
+
+## 2.8 示例用法
+
+```bash
+# 禁用单个币种
+barista liberica currency disable "1234567890123456789"
+
+# 禁用多个币种
+barista liberica currency disable "1234567890123456789" "9876543210987654321"
+
+# 通过选项参数禁用（逗号分隔）
+barista liberica currency disable --currency-id "1234567890123456789,9876543210987654321"
+barista liberica currency disable -i "1234567890123456789,9876543210987654321"
+
+# JSON 输出
+barista liberica currency disable "1234567890123456789" --json
+```

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

@@ -0,0 +1,115 @@
+# barista liberica currency enable
+
+启用币种（批量）。
+
+## 2.1 命令元数据
+
+| 字段 | 值 |
+|------|-----|
+| 完整命令 | `barista liberica currency enable <currency-id...>` |
+| 功能描述 | 启用一个或多个币种 |
+| HTTP方法 | POST |
+| 是否需要认证 | ✅ 是 |
+| 是否支持dry-run | ⬜ 否 |
+
+## 2.2 后端接口引用
+
+### Controller位置
+```
+coffee-liberica-end/
+└── facade/liberica-facade-enterprise/
+    └── src/main/java/com/newpeak/liberica/facade/enterprise/controller/finance/
+        └── FinanceCurrencyController.java
+            └── batchActive(@PostResource(path = "/batchActive"))
+                └── public ResponseData<Void> batchActive(
+                        @RequestBody Map<String, List<String>> request
+                    )
+```
+
+### Request DTO位置
+```
+- 批量启用请求：{ currencyIdList: List<String> }
+```
+
+### Response DTO位置
+```
+- 返回 void 或成功标记（ResponseData<Void>）
+```
+
+## 2.3 CLI参数设计
+
+### 命令结构
+```
+barista liberica currency enable <currency-id...> [options]
+```
+
+### 全局选项
+| 选项 | 类型 | 说明 |
+|------|------|------|
+| `--env` | string | 目标环境(dev\|test\|prod-cn\|prod-jp) |
+| `--tenant` | string | 租户代码 |
+| `--json` | boolean | JSON输出 |
+
+### 位置参数
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| currency-id... | string | ✅ | 一个或多个币种ID |
+
+### 命令选项
+| 选项 | 短选项 | 类型 | 必填 | 默认值 | 说明 | 对应DTO字段 |
+|------|--------|------|------|--------|------|-------------|
+| --currency-id | -i | string | ⬜ | - | 币种ID（逗号分隔，与位置参数互斥） | currencyIdList |
+
+## 2.4 字段映射表
+
+| CLI参数 | DTO字段 | 类型转换 | 验证规则 |
+|---------|---------|----------|----------|
+| currency-id... (位置参数) | currencyIdList | string[]→List<String> | 至少一个ID |
+| --currency-id / -i | currencyIdList | string→List<String> | 逗号分隔 |
+
+## 2.5 错误码引用
+
+### ExceptionEnum位置
+```
+coffee-liberica-end/
+└── business/liberica-business-finance/finance-api/src/main/java/com/newpeak/liberica/finance/api/exception/enums/CurrencyExceptionEnum.java
+```
+
+### 已知错误码
+| 错误码 | 错误消息 | 触发条件 |
+|--------|----------|----------|
+| CURRENCY_NOT_EXIST | 币种不存在 | 币种不存在 |
+| CURRENCY_NO_PERMISSION | 无权限操作 | 无权限操作 |
+
+## 2.6 权限检查
+
+| 检查项 | 位置 | 说明 |
+|--------|------|------|
+| 注解 | FinanceCurrencyController.java | 需要 `finance_currency:edit` 权限 |
+
+## 2.7 实现要点
+
+1. **批量支持**：支持单个ID或多个ID（空格分隔）
+2. **ID来源**：可通过位置参数或 --currency-id 选项传递
+3. **逗号分隔**：--currency-id 选项支持逗号分隔的多个ID
+4. **状态变更**：将 statusFlag 从 2（禁用）改为 1（启用）
+5. **部分失败**：如果某些ID不存在，后端可能返回错误或仅处理存在的ID
+6. **API路径**：POST `/api/enterprise/finance/currency/batchActive`
+7. **请求格式**：{ currencyIdList: ["id1", "id2", ...] }
+
+## 2.8 示例用法
+
+```bash
+# 启用单个币种
+barista liberica currency enable "1234567890123456789"
+
+# 启用多个币种
+barista liberica currency enable "1234567890123456789" "9876543210987654321"
+
+# 通过选项参数启用（逗号分隔）
+barista liberica currency enable --currency-id "1234567890123456789,9876543210987654321"
+barista liberica currency enable -i "1234567890123456789,9876543210987654321"
+
+# JSON 输出
+barista liberica currency enable "1234567890123456789" --json
+```

package/docs/commands/liberica/currency/get.md

@@ -0,0 +1,118 @@
+# barista liberica currency get
+
+获取单个币种详情。
+
+## 2.1 命令元数据
+
+| 字段 | 值 |
+|------|-----|
+| 完整命令 | `barista liberica currency get <currency-id>` |
+| 功能描述 | 获取币种详情 |
+| HTTP方法 | GET |
+| 是否需要认证 | ✅ 是 |
+| 是否支持dry-run | ⬜ 否 |
+
+## 2.2 后端接口引用
+
+### Controller位置
+```
+coffee-liberica-end/
+└── facade/liberica-facade-enterprise/
+    └── src/main/java/com/newpeak/liberica/facade/enterprise/controller/finance/
+        └── FinanceCurrencyController.java
+            └── getCurrency(@GetResource(path = "/detail"))
+                └── public ResponseData<CurrencyResponse> getCurrency(
+                        @RequestParam String currencyId
+                    )
+```
+
+### Request DTO位置
+```
+[无Request DTO]
+- currencyId通过@RequestParam传递
+```
+
+### Response DTO位置
+```
+coffee-liberica-end/
+└── business/liberica-business-finance/finance-api/src/main/java/com/newpeak/liberica/finance/api/pojo/response/CurrencyResponse.java
+    ├── currencyId: String
+    ├── currencyCode: String (3位编码，如 CNY)
+    ├── currencyName: String (币种名称)
+    ├── currencySign: String (符号，如 ¥)
+    ├── statusFlag: Integer (1=启用，2=禁用)
+    ├── createTime: String
+    └── updateTime: String
+```
+
+## 2.3 CLI参数设计
+
+### 命令结构
+```
+barista liberica currency get <currency-id> [options]
+```
+
+### 全局选项
+| 选项 | 类型 | 说明 |
+|------|------|------|
+| `--env` | string | 目标环境(dev\|test\|prod-cn\|prod-jp) |
+| `--tenant` | string | 租户代码 |
+| `--json` | boolean | JSON输出 |
+
+### 位置参数
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| currency-id | string | ✅ | 币种ID |
+
+### 命令选项
+| 选项 | 短选项 | 类型 | 必填 | 默认值 | 说明 | 对应DTO字段 |
+|------|--------|------|------|--------|------|-------------|
+| --currency-id | -i | string | ⬜ | - | 币种ID（与位置参数互斥） | currencyId |
+
+## 2.4 字段映射表
+
+| CLI参数 | DTO字段 | 类型转换 | 验证规则 |
+|---------|---------|----------|----------|
+| currency-id (位置参数) | currencyId | string→String | @NotBlank |
+| --currency-id / -i | currencyId | string→String | @NotBlank |
+
+## 2.5 错误码引用
+
+### ExceptionEnum位置
+```
+coffee-liberica-end/
+└── business/liberica-business-finance/finance-api/src/main/java/com/newpeak/liberica/finance/api/exception/enums/CurrencyExceptionEnum.java
+```
+
+### 已知错误码
+| 错误码 | 错误消息 | 触发条件 |
+|--------|----------|----------|
+| CURRENCY_NOT_EXIST | 币种不存在 | ID不存在 |
+
+## 2.6 权限检查
+
+| 检查项 | 位置 | 说明 |
+|--------|------|------|
+| 注解 | 无需权限 | 登录用户可访问 |
+
+## 2.7 实现要点
+
+1. **参数解析**：支持位置参数 `<currency-id>` 和选项参数 `--currency-id`
+2. **ID必填**：currencyId为必填参数
+3. **输出格式**：格式化展示币种详情，包括基本信息和状态
+4. **错误处理**：币种不存在时显示友好错误提示
+5. **API路径**：GET `/api/enterprise/finance/currency/detail`
+
+## 2.8 示例用法
+
+```bash
+# 通过位置参数获取
+barista liberica currency get "1234567890123456789"
+
+# 通过选项参数获取
+barista liberica currency get --currency-id "1234567890123456789"
+barista liberica currency get -i "1234567890123456789"
+
+# JSON 输出
+barista liberica currency get "1234567890123456789" --json
+```