@newpeak/barista-cli 0.1.6 → 0.1.8

package/docs/commands/liberica/supplier-contacts/create.md

@@ -0,0 +1,152 @@
+# barista liberica supplier-contacts create
+
+创建供应商联系人。
+
+## 2.1 命令元数据
+
+| 字段 | 值 |
+|------|-----|
+| 完整命令 | `barista liberica supplier-contacts create` |
+| 功能描述 | 添加新供应商联系人 |
+| HTTP方法 | POST |
+| 是否需要认证 | ✅ 是 |
+| 是否支持dry-run | ✅ 是 |
+
+## 2.2 后端接口引用
+
+### Controller位置
+```
+coffee-liberica-end/
+└── facade/liberica-facade-enterprise/
+    └── src/main/java/com/newpeak/liberica/facade/enterprise/controller/purchases/
+        └── EnterpriseSupplierContactController.java
+            └── add(@PostResource(path = "/add", requiredPermission = true, requirePermissionCode = "ADD_MASTER_SUPPLIER_CONTACT"))
+                └── public ResponseData<MasterSupplierContactResponse> add(
+                        @RequestHeader("X-TENANT-ID") Long tenantId,
+                        @RequestBody @Validated(BaseRequest.add.class) MasterSupplierContactRequest masterSupplierContactRequest
+                    )
+```
+
+### Request DTO位置
+```
+coffee-liberica-end/
+└── business/liberica-business-master/master-api/
+    └── src/main/java/com/newpeak/liberica/master/api/pojo/request/
+        └── MasterSupplierContactRequest.java
+            ├── supplierId: Long (@NotNull)
+            ├── supplierContactName: String (@NotBlank, max=255)
+            ├── supplierContactPhone: String (max=256)
+            ├── supplierContactTelephone: String (max=256)
+            ├── supplierContactEmail: String (max=512)
+            ├── supplierContactSex: String (max=255)
+            ├── supplierContactBirthday: Date
+            ├── supplierContactQq: String (max=512)
+            ├── supplierContactWechat: String (max=512)
+            ├── supplierContactAddress: String (max=512)
+            ├── defaultFlag: String (@NotBlank, max=1)
+            └── remark: String (max=255)
+```
+
+### Response DTO位置
+```
+coffee-liberica-end/
+└── business/liberica-business-master/master-api/
+    └── src/main/java/com/newpeak/liberica/master/api/pojo/response/
+        └── MasterSupplierContactResponse.java
+            └── (同 get 接口)
+```
+
+## 2.3 CLI参数设计
+
+### 命令结构
+```
+barista liberica supplier-contacts create [options]
+```
+
+### 全局选项
+| 选项 | 类型 | 说明 |
+|------|------|------|
+| `--env` | string | 目标环境(dev\|test\|prod-cn\|prod-jp) |
+| `--tenant` | string | 租户代码 |
+| `--dry-run` | boolean | 预览模式 |
+| `--json` | boolean | JSON输出 |
+
+### 命令选项
+| 选项 | 短选项 | 类型 | 必填 | 默认值 | 说明 | 对应DTO字段 |
+|------|--------|------|------|--------|------|-------------|
+| --supplier-id | -s | string | ✅ | - | 供应商ID | supplierId |
+| --name | -n | string | ✅ | - | 姓名 | supplierContactName |
+| --phone | -p | string | ⬜ | - | 手机号 | supplierContactPhone |
+| --telephone | -t | string | ⬜ | - | 座机号 | supplierContactTelephone |
+| --email | -e | string | ⬜ | - | 电子邮箱 | supplierContactEmail |
+| --sex | -x | string | ⬜ | - | 性别 | supplierContactSex |
+| --birthday | -b | string | ⬜ | - | 生日(YYYY-MM-DD) | supplierContactBirthday |
+| --qq | -q | string | ⬜ | - | QQ号 | supplierContactQq |
+| --wechat | -w | string | ⬜ | - | 微信号 | supplierContactWechat |
+| --address | -a | string | ⬜ | - | 详细地址 | supplierContactAddress |
+| --default | -d | boolean | ⬜ | N | 是否默认联系人 | defaultFlag |
+| --remark | -r | string | ⬜ | - | 备注 | remark |
+
+## 2.4 字段映射表
+
+| CLI参数 | DTO字段 | 类型转换 | 验证规则 |
+|---------|---------|----------|----------|
+| --supplier-id / -s | supplierId | string→Long | @NotNull |
+| --name / -n | supplierContactName | 直接传递 | @NotBlank, max=255 |
+| --phone / -p | supplierContactPhone | 直接传递 | max=256 |
+| --telephone / -t | supplierContactTelephone | 直接传递 | max=256 |
+| --email / -e | supplierContactEmail | 直接传递 | max=512 |
+| --sex / -x | supplierContactSex | 直接传递 | max=255 |
+| --birthday / -b | supplierContactBirthday | string→Date | yyyy-MM-dd |
+| --qq / -q | supplierContactQq | 直接传递 | max=512 |
+| --wechat / -w | supplierContactWechat | 直接传递 | max=512 |
+| --address / -a | supplierContactAddress | 直接传递 | max=512 |
+| --default / -d | defaultFlag | boolean→Y/N | @NotBlank, max=1 |
+| --remark / -r | remark | 直接传递 | max=255 |
+
+## 2.5 错误码引用
+
+### ExceptionEnum位置
+```
+coffee-liberica-end/
+└── business/liberica-business-master/master-api/
+    └── src/main/java/com/newpeak/liberica/master/api/exception/enums/
+        └── MasterSupplierContactExceptionEnum.java
+```
+
+### 已知错误码
+| 错误码 | 错误消息 | 触发条件 |
+|--------|----------|----------|
+| 01001XXX001 | 租户供应商联系人不存在 | 供应商ID不存在 |
+| 01001XXX... | 相关验证错误 | 字段验证失败 |
+
+## 2.6 权限检查
+
+| 检查项 | 位置 | 说明 |
+|--------|------|------|
+| PermissionConstants | `ADD_MASTER_SUPPLIER_CONTACT` | 添加供应商联系人需要此权限 |
+| 注解 | `@PostResource(requirePermissionCode = "ADD_MASTER_SUPPLIER_CONTACT")` | Controller方法上 |
+
+## 2.7 实现要点
+
+1. **必填参数**：--supplier-id 和 --name 必须指定
+2. **defaultFlag**：--default 不指定时默认为 "N"，指定时为 "Y"
+3. **dry-run 模式**：预览模式下只显示将要发送的数据，不实际调用 API
+4. **输出格式**：成功后显示创建的联系人信息
+5. **错误处理**：字段验证错误显示友好提示
+
+## 2.8 示例用法
+
+```bash
+# 创建供应商联系人（dry-run 预览）
+barista liberica supplier-contacts create --supplier-id 123 --name "张三" --phone "13800138000" --dry-run
+
+# 实际创建
+barista liberica supplier-contacts create --supplier-id 123 --name "张三" --phone "13800138000" --email "zhang@example.com"
+
+# 创建默认联系人
+barista liberica supplier-contacts create --supplier-id 123 --name "李四" --default --address "北京市朝阳区xxx"
+
+# JSON 输出
+barista liberica supplier-contacts create --supplier-id 123 --name "张三" --json
+```

package/docs/commands/liberica/supplier-contacts/delete.md

@@ -0,0 +1,123 @@
+# barista liberica supplier-contacts delete
+
+删除供应商联系人。
+
+## 2.1 命令元数据
+
+| 字段 | 值 |
+|------|-----|
+| 完整命令 | `barista liberica supplier-contacts delete <contact-id>` |
+| 功能描述 | 删除供应商联系人 |
+| HTTP方法 | POST |
+| 是否需要认证 | ✅ 是 |
+| 是否支持dry-run | ✅ 是（默认） |
+
+## 2.2 后端接口引用
+
+### Controller位置
+```
+coffee-liberica-end/
+└── facade/liberica-facade-enterprise/
+    └── src/main/java/com/newpeak/liberica/facade/enterprise/controller/purchases/
+        └── EnterpriseSupplierContactController.java
+            └── delete(@PostResource(path = "/delete", requiredPermission = true, requirePermissionCode = "DEL_MASTER_SUPPLIER_CONTACT"))
+                └── public ResponseData<?> delete(
+                        @RequestHeader("X-TENANT-ID") Long tenantId,
+                        @RequestBody @Validated(BaseRequest.delete.class) MasterSupplierContactRequest masterSupplierContactRequest
+                    )
+```
+
+### Request DTO位置
+```
+coffee-liberica-end/
+└── business/liberica-business-master/master-api/
+    └── src/main/java/com/newpeak/liberica/master/api/pojo/request/
+        └── MasterSupplierContactRequest.java
+            └── supplierContactId: Long (@NotNull on delete)
+```
+
+### Response DTO位置
+```
+coffee-liberica-end/
+└── business/liberica-business-master/master-api/
+    └── src/main/java/com/newpeak/liberica/master/api/pojo/response/
+        └── SuccessResponseData<?>
+            └── 无具体数据
+```
+
+## 2.3 CLI参数设计
+
+### 命令结构
+```
+barista liberica supplier-contacts delete <contact-id> [options]
+```
+
+### 位置参数
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| contact-id | string | ✅ | 供应商联系人ID |
+
+### 全局选项
+| 选项 | 类型 | 说明 |
+|------|------|------|
+| `--env` | string | 目标环境(dev\|test\|prod-cn\|prod-jp) |
+| `--tenant` | string | 租户代码 |
+| `--dry-run` | boolean | 预览模式（默认开启） |
+| `--force` | boolean | 跳过确认，直接执行删除 |
+| `--json` | boolean | JSON输出 |
+
+## 2.4 字段映射表
+
+| CLI参数 | DTO字段 | 类型转换 | 验证规则 |
+|---------|---------|----------|----------|
+| <contact-id> | supplierContactId | string→Long | @NotNull |
+
+## 2.5 错误码引用
+
+### ExceptionEnum位置
+```
+coffee-liberica-end/
+└── business/liberica-business-master/master-api/
+    └── src/main/java/com/newpeak/liberica/master/api/exception/enums/
+        └── MasterSupplierContactExceptionEnum.java
+            └── MASTER_SUPPLIER_CONTACT_NOT_EXIST("01001XXX001", "租户供应商联系人不存在")
+```
+
+### 已知错误码
+| 错误码 | 错误消息 | 触发条件 |
+|--------|----------|----------|
+| 01001XXX001 | 租户供应商联系人不存在 | contact-id 不存在或不属于当前租户 |
+
+## 2.6 权限检查
+
+| 检查项 | 位置 | 说明 |
+|--------|------|------|
+| PermissionConstants | `DEL_MASTER_SUPPLIER_CONTACT` | 删除供应商联系人需要此权限 |
+| 注解 | `@PostResource(requirePermissionCode = "DEL_MASTER_SUPPLIER_CONTACT")` | Controller方法上 |
+
+## 2.7 实现要点
+
+1. **位置参数**：contact-id 必须指定
+2. **默认 dry-run**：不带 --force 时默认是 dry-run 模式，只预览不执行
+3. **--force 确认**：实际删除前必须显式指定 --force
+4. **输出格式**：预览模式显示将要删除的联系人信息，确认后显示删除结果
+5. **错误处理**：联系人不存在时显示友好错误信息
+
+## 2.8 示例用法
+
+```bash
+# 预览删除（默认 dry-run）
+barista liberica supplier-contacts delete 12345
+# 输出: 🔍 Dry-Run 模式：不会实际删除
+#       将删除联系人: 张三 (ID: 12345)
+#       添加 --force 选项以确认删除
+
+# 确认删除
+barista liberica supplier-contacts delete 12345 --force
+
+# JSON 预览
+barista liberica supplier-contacts delete 12345 --json
+
+# JSON 确认删除
+barista liberica supplier-contacts delete 12345 --force --json
+```

package/docs/commands/liberica/supplier-contacts/get.md

@@ -0,0 +1,133 @@
+# barista liberica supplier-contacts get
+
+获取单个供应商联系人详情。
+
+## 2.1 命令元数据
+
+| 字段 | 值 |
+|------|-----|
+| 完整命令 | `barista liberica supplier-contacts get <contact-id>` |
+| 功能描述 | 获取单个供应商联系人详情 |
+| HTTP方法 | GET |
+| 是否需要认证 | ✅ 是 |
+| 是否支持dry-run | ⬜ 否 |
+
+## 2.2 后端接口引用
+
+### Controller位置
+```
+coffee-liberica-end/
+└── facade/liberica-facade-enterprise/
+    └── src/main/java/com/newpeak/liberica/facade/enterprise/controller/purchases/
+        └── EnterpriseSupplierContactController.java
+            └── detail(@GetResource(path = "/detail"))
+                └── public ResponseData<MasterSupplierContactResponse> detail(
+                        @RequestHeader("X-TENANT-ID") Long tenantId,
+                        MasterSupplierContactRequest masterSupplierContactRequest
+                    )
+```
+
+### Request DTO位置
+```
+coffee-liberica-end/
+└── business/liberica-business-master/master-api/
+    └── src/main/java/com/newpeak/liberica/master/api/pojo/request/
+        └── MasterSupplierContactRequest.java
+            └── supplierContactId: Long (@NotNull on detail)
+```
+
+### Response DTO位置
+```
+coffee-liberica-end/
+└── business/liberica-business-master/master-api/
+    └── src/main/java/com/newpeak/liberica/master/api/pojo/response/
+        └── MasterSupplierContactResponse.java
+            ├── supplierContactId: Long
+            ├── supplierId: Long
+            ├── supplierContactName: String
+            ├── supplierContactPhone: String
+            ├── supplierContactTelephone: String
+            ├── supplierContactEmail: String
+            ├── supplierContactSex: String
+            ├── supplierContactBirthday: Date
+            ├── supplierContactQq: String
+            ├── supplierContactWechat: String
+            ├── supplierContactAddress: String
+            ├── defaultFlag: String (Y/N)
+            ├── remark: String
+            ├── createTime: String
+            └── updateTime: String
+```
+
+## 2.3 CLI参数设计
+
+### 命令结构
+```
+barista liberica supplier-contacts get <contact-id> [options]
+```
+
+### 位置参数
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| contact-id | string | ✅ | 供应商联系人ID (supplierContactId) |
+
+### 全局选项
+| 选项 | 类型 | 说明 |
+|------|------|------|
+| `--env` | string | 目标环境(dev\|test\|prod-cn\|prod-jp) |
+| `--tenant` | string | 租户代码 |
+| `--json` | boolean | JSON输出 |
+
+### 命令选项
+| 选项 | 短选项 | 类型 | 必填 | 默认值 | 说明 |
+|------|--------|------|------|--------|------|
+| — | — | — | — | — | 此命令无额外选项，ID 通过位置参数传入 |
+
+## 2.4 字段映射表
+
+| CLI参数 | DTO字段 | 类型转换 | 验证规则 |
+|---------|---------|----------|----------|
+| <contact-id> (位置参数) | supplierContactId | string→Long | @NotNull, 必须为正整数 |
+
+## 2.5 错误码引用
+
+### ExceptionEnum位置
+```
+coffee-liberica-end/
+└── business/liberica-business-master/master-api/
+    └── src/main/java/com/newpeak/liberica/master/api/exception/enums/
+        └── MasterSupplierContactExceptionEnum.java
+            └── MASTER_SUPPLIER_CONTACT_NOT_EXIST("01001XXX001", "租户供应商联系人不存在")
+```
+
+### 已知错误码
+| 错误码 | 错误消息 | 触发条件 |
+|--------|----------|----------|
+| 01001XXX001 | 租户供应商联系人不存在 | contact-id 不存在或不属于当前租户 |
+
+## 2.6 权限检查
+
+| 检查项 | 位置 | 说明 |
+|--------|------|------|
+| 注解 | `@GetResource(path = "/detail")` | 无 requiredPermission |
+
+## 2.7 实现要点
+
+1. **位置参数**：`get` 命令使用 `<contact-id>` 位置参数指定联系人ID
+2. **错误处理**：联系人不存在时抛出 `MASTER_SUPPLIER_CONTACT_NOT_EXIST`，CLI 显示友好错误信息
+3. **tenantId来源**：来自 X-TENANT-ID header，后端自动按租户隔离数据
+4. **输出格式**：表格形式展示联系人详情，或 JSON 格式
+
+## 2.8 示例用法
+
+```bash
+# 获取联系人详情
+barista liberica supplier-contacts get 12345
+
+# JSON 输出
+barista liberica supplier-contacts get 12345 --json
+
+# 联系人不存在
+barista liberica supplier-contacts get 99999
+# 输出: Error: 租户供应商联系人不存在 (01001XXX001)
+```

package/docs/commands/liberica/supplier-contacts/list.md

@@ -0,0 +1,143 @@
+# barista liberica supplier-contacts list
+
+查询供应商联系人列表。
+
+## 2.1 命令元数据
+
+| 字段 | 值 |
+|------|-----|
+| 完整命令 | `barista liberica supplier-contacts list` |
+| 功能描述 | 查询指定供应商的联系人列表 |
+| HTTP方法 | GET |
+| 是否需要认证 | ✅ 是 |
+| 是否支持dry-run | ⬜ 否 |
+
+## 2.2 后端接口引用
+
+### Controller位置
+```
+coffee-liberica-end/
+└── facade/liberica-facade-enterprise/
+    └── src/main/java/com/newpeak/liberica/facade/enterprise/controller/purchases/
+        └── EnterpriseSupplierContactController.java
+            └── list(@GetResource(path = "/list"))
+                └── public ResponseData<List<MasterSupplierContactResponse>> list(
+                        @RequestHeader("X-TENANT-ID") Long tenantId,
+                        MasterSupplierContactRequest masterSupplierContactRequest
+                    )
+```
+
+### Request DTO位置
+```
+coffee-liberica-end/
+└── business/liberica-business-master/master-api/
+    └── src/main/java/com/newpeak/liberica/master/api/pojo/request/
+        └── MasterSupplierContactRequest.java
+            ├── supplierId: Long (@NotNull)
+            ├── supplierContactName: String (搜索关键词)
+            ├── pageNo: Long (分页页码)
+            └── pageSize: Long (分页大小)
+```
+
+### Response DTO位置
+```
+coffee-liberica-end/
+└── business/liberica-business-master/master-api/
+    └── src/main/java/com/newpeak/liberica/master/api/pojo/response/
+        └── MasterSupplierContactResponse.java
+            ├── supplierContactId: Long
+            ├── supplierId: Long
+            ├── supplierContactName: String
+            ├── supplierContactPhone: String
+            ├── supplierContactTelephone: String
+            ├── supplierContactEmail: String
+            ├── supplierContactSex: String
+            ├── supplierContactBirthday: Date
+            ├── supplierContactQq: String
+            ├── supplierContactWechat: String
+            ├── supplierContactAddress: String
+            ├── defaultFlag: String (Y/N)
+            ├── remark: String
+            ├── createTime: String
+            └── updateTime: String
+```
+
+## 2.3 CLI参数设计
+
+### 命令结构
+```
+barista liberica supplier-contacts list [options]
+```
+
+### 全局选项
+| 选项 | 类型 | 说明 |
+|------|------|------|
+| `--env` | string | 目标环境(dev\|test\|prod-cn\|prod-jp) |
+| `--tenant` | string | 租户代码 |
+| `--json` | boolean | JSON输出 |
+
+### 命令选项
+| 选项 | 短选项 | 类型 | 必填 | 默认值 | 说明 | 对应DTO字段 |
+|------|--------|------|------|--------|------|-------------|
+| --supplier-id | -s | string | ✅ | - | 供应商ID | supplierId |
+| --page | -p | number | ⬜ | 1 | 页码 | pageNo |
+| --size | -z | number | ⬜ | 20 | 每页条数 | pageSize |
+| --search | -S | string | ⬜ | - | 搜索关键词(姓名) | supplierContactName |
+
+## 2.4 字段映射表
+
+| CLI参数 | DTO字段 | 类型转换 | 验证规则 |
+|---------|---------|----------|----------|
+| --supplier-id / -s | supplierId | string→Long | @NotNull |
+| --page / -p | pageNo | number→Long | >= 1 |
+| --size / -z | pageSize | number→Long | 1-100 |
+| --search / -S | supplierContactName | 直接传递 | 模糊查询 |
+
+## 2.5 错误码引用
+
+### ExceptionEnum位置
+```
+coffee-liberica-end/
+└── business/liberica-business-master/master-api/
+    └── src/main/java/com/newpeak/liberica/master/api/exception/enums/
+        └── MasterSupplierContactExceptionEnum.java
+            └── MASTER_SUPPLIER_CONTACT_NOT_EXIST("01001XXX001", "租户供应商联系人不存在")
+```
+
+### 已知错误码
+| 错误码 | 错误消息 | 触发条件 |
+|--------|----------|----------|
+| 01001XXX001 | 租户供应商联系人不存在 | 供应商ID不存在时 |
+
+## 2.6 权限检查
+
+| 检查项 | 位置 | 说明 |
+|--------|------|------|
+| 注解 | `@GetResource(path = "/list")` | 无 requiredPermission（无需权限码） |
+
+**注意**：list 接口在 Controller 层无需权限校验，数据范围通过 tenantId 隔离。
+
+## 2.7 实现要点
+
+1. **必填参数**：--supplier-id 必须指定
+2. **分页默认值**：page=1, size=20
+3. **搜索行为**：supplierContactName 支持模糊查询
+4. **无结果处理**：返回空列表，不抛出异常
+5. **tenantId来源**：来自 X-TENANT-ID header
+6. **输出格式**：表格形式展示联系人列表
+
+## 2.8 示例用法
+
+```bash
+# 列出供应商的所有联系人
+barista liberica supplier-contacts list --supplier-id 12345
+
+# 指定页码和每页条数
+barista liberica supplier-contacts list --supplier-id 12345 --page 2 --size 50
+
+# 搜索联系人
+barista liberica supplier-contacts list --supplier-id 12345 --search "张"
+
+# JSON 输出（便于脚本处理）
+barista liberica supplier-contacts list --supplier-id 12345 --json
+```