@newpeak/barista-cli 0.1.7 → 0.1.9

package/docs/commands/REFERENCE.md

@@ -138,7 +138,27 @@
 | 获取供应商详情 | `barista liberica suppliers get <id>` | GET | 查看供应商信息 | 待创建 |
 | 更新供应商 | `barista liberica suppliers update <id>` | POST | 修改供应商信息 | 待创建 |
 
-### 7. materials（物料管理）- 📋 待开发
+### 7. client-contacts（客户联系人管理）- 📋 开发中
+
+| 功能 | 命令 | HTTP | 说明 | 设计文档 |
+|------|------|------|------|----------|
+| 获取联系人列表 | `barista liberica client-contacts list` | GET | 查看客户的所有联系人 | [docs](./liberica/client-contacts/list.md) |
+| 获取联系人详情 | `barista liberica client-contacts get <id>` | GET | 查看联系人信息 | [docs](./liberica/client-contacts/get.md) |
+| 创建联系人 | `barista liberica client-contacts create` | POST | 添加客户联系人 | [docs](./liberica/client-contacts/create.md) |
+| 更新联系人 | `barista liberica client-contacts update <id>` | POST | 修改联系人信息 | [docs](./liberica/client-contacts/update.md) |
+| 删除联系人 | `barista liberica client-contacts delete <id>` | POST | 删除联系人 | [docs](./liberica/client-contacts/delete.md) |
+
+### 8. supplier-contacts（供应商联系人管理）- 📋 开发中
+
+| 功能 | 命令 | HTTP | 说明 | 设计文档 |
+|------|------|------|------|----------|
+| 获取联系人列表 | `barista liberica supplier-contacts list` | GET | 查看供应商的所有联系人 | [docs](./liberica/supplier-contacts/list.md) |
+| 获取联系人详情 | `barista liberica supplier-contacts get <id>` | GET | 查看联系人信息 | [docs](./liberica/supplier-contacts/get.md) |
+| 创建联系人 | `barista liberica supplier-contacts create` | POST | 添加供应商联系人 | [docs](./liberica/supplier-contacts/create.md) |
+| 更新联系人 | `barista liberica supplier-contacts update <id>` | POST | 修改联系人信息 | [docs](./liberica/supplier-contacts/update.md) |
+| 删除联系人 | `barista liberica supplier-contacts delete <id>` | POST | 删除联系人 | [docs](./liberica/supplier-contacts/delete.md) |
+
+### 9. materials（物料管理）- 📋 待开发
 
 | 功能 | 命令 | HTTP | 说明 | 设计文档 |
 |------|------|------|------|----------|
@@ -148,7 +168,7 @@
 | 搜索物料 | `barista liberica materials search` | GET | 按条件搜索物料 | 待创建 |
 | 更新物料 | `barista liberica materials update <id>` | POST | 修改物料信息 | 待创建 |
 
-### 8. sales-prices（销售价格）- 📋 待开发
+### 10. sales-prices（销售价格）- 📋 待开发
 
 | 功能 | 命令 | HTTP | 说明 | 设计文档 |
 |------|------|------|------|----------|
@@ -157,7 +177,7 @@
 | 获取价格详情 | `barista liberica sales-prices get <id>` | GET | 查看价格详情 | 待创建 |
 | 更新销售价格 | `barista liberica sales-prices update <id>` | POST | 修改销售价格 | 待创建 |
 
-### 9. purchase-prices（采购价格）- 📋 待开发
+### 11. purchase-prices（采购价格）- 📋 待开发
 
 | 功能 | 命令 | HTTP | 说明 | 设计文档 |
 |------|------|------|------|----------|
@@ -166,7 +186,7 @@
 | 获取价格详情 | `barista liberica purchase-prices get <id>` | GET | 查看价格详情 | 待创建 |
 | 更新采购价格 | `barista liberica purchase-prices update <id>` | POST | 修改采购价格 | 待创建 |
 
-### 10. sales-orders（销售订单）- 📋 待开发
+### 12. sales-orders（销售订单）- 📋 待开发
 
 | 功能 | 命令 | HTTP | 说明 | 设计文档 |
 |------|------|------|------|----------|

package/docs/commands/liberica/calendar/DESIGN.md

@@ -0,0 +1,333 @@
+# barista liberica calendar
+
+工作日历管理命令组。支持查询租户工作日历列表和设置指定日期的日历类型。
+
+---
+
+## 2.1 命令元数据
+
+### calendar list
+
+| 字段 | 值 |
+|------|-----|
+| 完整命令 | `barista liberica calendar list` |
+| 功能描述 | 查询租户工作日历列表 |
+| HTTP方法 | GET |
+| 是否需要认证 | ✅ 是 |
+| 是否支持dry-run | ⬜ 否 |
+
+### calendar set
+
+| 字段 | 值 |
+|------|-----|
+| 完整命令 | `barista liberica calendar set` |
+| 功能描述 | 设置指定日期的日历类型 |
+| HTTP方法 | POST |
+| 是否需要认证 | ✅ 是 |
+| 是否支持dry-run | ✅ 是 |
+
+---
+
+## 2.2 后端接口引用
+
+### Controller位置
+
+```
+coffee-liberica-end/
+└── facade/liberica-facade-enterprise/
+    └── src/main/java/com/newpeak/liberica/facade/enterprise/controller/
+        └── EnterpriseCalendarController.java
+            └── page(@GetResource(path = "/page"))
+                └── public ResponseData<Map<String, List<WorkDayCalendar>>> page(
+                        @RequestHeader("X-TENANT-ID") Long tenantId,
+                        @ParameterObject WorkCalendarRequest request
+                    )
+            └── edit(@PostResource(path = "/edit", requiredPermission = true, requirePermissionCode = "EDIT_CALENDAR"))
+                └── public ResponseData<?> edit(
+                        @RequestHeader("X-TENANT-ID") Long tenantId,
+                        @RequestBody TenantCalendarRequest request
+                    )
+```
+
+### Request DTO位置
+
+**WorkCalendarRequest（列表查询）**
+```
+coffee-liberica-end/
+└── support/support-t-calendar/data-calendar-business/
+    └── src/main/java/com/newpeak/liberica/business/support/calendar/pojo/request/
+        └── WorkCalendarRequest.java
+            ├── year: Integer
+            ├── month: Integer
+            ├── months: Integer
+            └── entityCode: String
+```
+
+**TenantCalendarRequest（编辑日历类型）**
+```
+coffee-liberica-end/
+└── support/support-t-calendar/data-calendar-business/
+    └── src/main/java/com/newpeak/liberica/business/support/calendar/pojo/request/
+        └── TenantCalendarRequest.java
+            ├── tenantId: Long
+            ├── countryCode: String
+            ├── calendarDate: String (@NotBlank)
+            ├── dateType: DateType (@NotBlank)
+            ├── remark: String
+            └── versionFlag: Long
+```
+
+### Response DTO位置
+
+**WorkDayCalendar（列表响应元素）**
+```
+coffee-liberica-end/
+└── support/support-t-calendar/data-calendar-api/
+    └── src/main/java/com/newpeak/liberica/support/calendar/api/
+        └── WorkDayCalendar.java (interface)
+            ├── getCalendarDate(): String
+            ├── getRemark(): String
+            ├── getDateType(): DateType
+            ├── isWorkDay(): boolean
+            ├── isNonWorkDay(): boolean
+            └── isWeekend(): boolean
+```
+
+**DateType枚举**
+```
+coffee-liberica-end/
+└── support/support-t-calendar/data-calendar-api/
+    └── src/main/java/com/newpeak/liberica/support/calendar/api/
+        └── DateType.java
+            ├── WORKDAY
+            ├── WEEKEND
+            └── HOLIDAY
+```
+
+---
+
+## 2.3 CLI参数设计
+
+### 命令结构
+
+```bash
+barista liberica calendar <subcommand> [options]
+
+# Subcommands
+barista liberica calendar list [options]
+barista liberica calendar set [options]
+```
+
+### 全局选项
+
+| 选项 | 类型 | 说明 |
+|------|------|------|
+| `--env` | string | 目标环境(dev\|test\|prod-cn\|prod-jp) |
+| `--tenant` | string | 租户代码（仅Liberica） |
+| `--dry-run` | boolean | 预览模式 |
+| `--json` | boolean | JSON输出 |
+
+### calendar list 命令选项
+
+| 选项 | 短选项 | 类型 | 必填 | 默认值 | 说明 | 对应DTO字段 |
+|------|--------|------|------|--------|------|-------------|
+| --year | -y | number | ✅ | - | 年份 | year |
+| --month | -m | number | ✅ | - | 月份 (1-12) | month |
+| --months | — | number | ⬜ | 12 | 查询月数 | months |
+| --grid | -g | boolean | ⬜ | false | 日历网格视图 | - |
+| --json | — | boolean | ⬜ | false | JSON输出 | - |
+
+### calendar set 命令选项
+
+| 选项 | 短选项 | 类型 | 必填 | 默认值 | 说明 | 对应DTO字段 |
+|------|--------|------|------|--------|------|-------------|
+| --date | -d | string | ✅ | - | 日期 (yyyy-MM-dd) | calendarDate |
+| --type | -t | string | ✅ | - | 日期类型 (WORKDAY\|WEEKEND\|HOLIDAY) | dateType |
+| --remark | -r | string | ⬜ | - | 备注说明 | remark |
+| --dry-run | — | boolean | ⬜ | false | 预览模式 | - |
+| --json | — | boolean | ⬜ | false | JSON输出 | - |
+
+---
+
+## 2.4 字段映射表
+
+### calendar list
+
+| CLI参数 | DTO字段 | 类型转换 | 验证规则 |
+|---------|---------|----------|----------|
+| --year / -y | year | number→Integer | 4位数字，>= 2000 |
+| --month / -m | month | number→Integer | 1-12 |
+| --months | months | number→Integer | >= 1，默认12 |
+
+### calendar set
+
+| CLI参数 | DTO字段 | 类型转换 | 验证规则 |
+|---------|---------|----------|----------|
+| --date / -d | calendarDate | 直接传递 | yyyy-MM-dd，@NotBlank |
+| --type / -t | dateType | 直接传递 | 枚举值 WORKDAY/WEEKEND/HOLIDAY，@NotBlank |
+| --remark / -r | remark | 直接传递 | 可选，max=255 |
+
+**自动填充字段（不通过CLI参数）：**
+
+| 字段 | 值 |
+|------|-----|
+| tenantId | 由后端从JWT Token中解析，CLI不传递 X-TENANT-ID header |
+| countryCode | 后端根据tenantId查询Tenant表自动填充 |
+| versionFlag | 编辑时由后端查询现有记录自动填充（upsert逻辑） |
+
+---
+
+## 2.5 错误码引用
+
+### ExceptionEnum位置
+
+```
+coffee-liberica-end/
+└── support/support-t-calendar/data-calendar-business/
+    └── src/main/java/com/newpeak/liberica/business/support/calendar/enums/
+        ├── CalendarExceptionEnum.java
+        │   └── CALENDAR_NOT_EXISTED("01001100001", "查询结果不存在")
+        └── TenantCalendarExceptionEnum.java
+            └── TENANT_CALENDAR_NOT_EXISTED("01001100001", "查询结果不存在")
+```
+
+### 已知错误码
+
+| 错误码 | 错误消息 | 触发条件 |
+|--------|----------|----------|
+| 01001100001 | 查询结果不存在 | 查询无匹配结果（通常返回空列表或空Map） |
+
+### Service层业务校验
+
+`EnterpriseCalendarController.edit()` 内部采用 upsert 逻辑：
+1. 根据 `tenantId + calendarDate` 查询现有记录
+2. 若记录不存在，调用 `tenantCalendarBusiness.add(request)` 新增
+3. 若记录存在，设置 `tenantCalendarId` 后调用 `tenantCalendarBusiness.edit(request)` 更新
+
+---
+
+## 2.6 权限检查
+
+| 检查项 | 位置 | 说明 |
+|--------|------|------|
+| `calendar list` | `@GetResource(path = "/page")` | 无 requiredPermission（无需权限码） |
+| `calendar set` | `@PostResource(path = "/edit", requiredPermission = true, requirePermissionCode = "EDIT_CALENDAR")` | 需要 EDIT_CALENDAR 权限 |
+
+---
+
+## 2.7 实现要点
+
+### 通用约定
+
+1. **无 X-TENANT-ID Header**：CLI 规范禁止传递此 Header，租户信息通过 JWT Token 由后端解析。
+2. **ID 类型**：所有 ID 字段使用 `string` 类型（避免后端 BigInteger 精度丢失）。
+3. **错误响应归一化**：后端存在两种错误格式，需在 `handleApiError()` 中统一处理：
+   - 格式1: `{ success: false, code: "A150001", message: "..." }`
+   - 格式2: `{ success: false, error: { code: "...", message: "..." } }`
+
+### calendar list 实现要点
+
+1. **参数验证**：`--year` 和 `--month` 为必填项；`--months` 默认值为 12。
+2. **API 路径**：`GET /api/enterprise/portal/calendar/page`
+3. **响应结构**：返回 `Map<String, List<WorkDayCalendar>>`，Key 为日期字符串（如 `"2025-04"`），Value 为该月份每日的日历对象列表。
+4. **输出模式**：
+   - 默认输出：按月份分组表格，显示日期、类型、备注
+   - `--grid` 模式：日历网格视图，每行一周，标注工作日/周末/假日
+   - `--json` 模式：结构化 JSON 输出
+
+### calendar set 实现要点
+
+1. **参数验证**：`--date` 格式必须为 `yyyy-MM-dd`；`--type` 必须为 `WORKDAY|WEEKEND|HOLIDAY` 之一。
+2. **API 路径**：`POST /api/enterprise/portal/calendar/edit`
+3. **Dry-run 支持**：使用 `--dry-run` 时构造 `TenantCalendarRequest` 但不发送请求，输出预览信息（日期、目标类型、备注）。
+4. **Upsert 行为**：后端自动判断是新增还是更新同一日期的记录。
+5. **成功响应**：`SuccessResponseData<>` 无具体 data 内容，输出成功提示即可。
+
+---
+
+## 2.8 测试策略（TDD）
+
+### 单元测试文件位置
+
+```
+coffee-barista-cli/
+└── tests/unit/commands/liberica/calendar/
+    ├── list.test.ts
+    └── set.test.ts
+```
+
+### calendar list 测试场景
+
+- [ ] 正常查询：提供 `--year` 和 `--month`，返回多月份日历数据
+- [ ] 默认 `--months=12`：未传该参数时验证 API 请求参数
+- [ ] 自定义 `--months`：验证请求参数正确传递
+- [ ] `--grid` 视图：验证表格按周排列输出
+- [ ] `--json` 输出：验证 JSON 结构包含 `success` 和 `data`
+- [ ] 缺少必填参数：`--year` 或 `--month` 缺失时返回验证错误
+- [ ] 无效参数：`--month 13` 返回验证错误
+- [ ] 空结果：API 返回空 Map 时友好提示
+- [ ] 错误响应：模拟后端两种错误格式，验证统一处理
+
+### calendar set 测试场景
+
+- [ ] 正常设置：`--date` 和 `--type` 均有效，API 调用成功
+- [ ] 带备注设置：`--remark` 参数正确传递
+- [ ] `--dry-run` 模式：不调用 API，输出预览信息
+- [ ] `--json` 输出：dry-run 和正常模式均验证 JSON 结构
+- [ ] 缺少必填参数：`--date` 或 `--type` 缺失时返回验证错误
+- [ ] 无效日期格式：`--date 2025/04/15` 返回验证错误
+- [ ] 无效类型值：`--type INVALID` 返回验证错误
+- [ ] 错误响应：模拟无权限/后端异常，验证友好提示和退出码
+
+### 集成测试流程
+
+```bash
+# 1. 登录
+barista liberica auth login dev shanghai admin@shanghai.newpeaksh.com 123456
+
+# 2. 查询 2025 年 4 月日历
+barista liberica calendar list --year 2025 --month 4
+
+# 3. 查询 2025 年 4 月起连续 3 个月
+barista liberica calendar list --year 2025 --month 4 --months 3
+
+# 4. 网格视图
+barista liberica calendar list --year 2025 --month 4 --grid
+
+# 5. JSON 输出
+barista liberica calendar list --year 2025 --month 4 --json
+
+# 6. 设置日期类型（dry-run）
+barista liberica calendar set --date 2025-04-15 --type HOLIDAY --remark "测试假日" --dry-run
+
+# 7. 实际设置日期类型
+barista liberica calendar set --date 2025-04-15 --type HOLIDAY --remark "测试假日"
+
+# 8. 验证设置结果
+barista liberica calendar list --year 2025 --month 4 --json
+```
+
+---
+
+## 2.9 示例用法
+
+```bash
+# 查询 2025 年全年工作日历
+barista liberica calendar list --year 2025 --month 1
+
+# 查询 2025 年第二季度（4-6月）
+barista liberica calendar list --year 2025 --month 4 --months 3
+
+# 网格视图展示
+barista liberica calendar list -y 2025 -m 4 --grid
+
+# 设置 2025-04-15 为假日
+barista liberica calendar set --date 2025-04-15 --type HOLIDAY --remark "清明节调休"
+
+# 预览设置（不实际提交）
+barista liberica calendar set -d 2025-04-15 -t HOLIDAY -r "测试" --dry-run
+
+# JSON 输出（便于脚本处理）
+barista liberica calendar list --year 2025 --month 4 --json
+barista liberica calendar set --date 2025-04-15 --type WORKDAY --json
+```

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

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

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

@@ -0,0 +1,123 @@
+# barista liberica client-contacts delete
+
+删除客户联系人。
+
+## 2.1 命令元数据
+
+| 字段 | 值 |
+|------|-----|
+| 完整命令 | `barista liberica client-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/sales/
+        └── EnterpriseClientContactController.java
+            └── delete(@PostResource(path = "/delete", requiredPermission = true, requirePermissionCode = "DEL_MASTER_CLIENT_CONTACT"))
+                └── public ResponseData<?> delete(
+                        @RequestHeader("X-TENANT-ID") Long tenantId,
+                        @RequestBody @Validated(BaseRequest.delete.class) MasterClientContactRequest masterClientContactRequest
+                    )
+```
+
+### Request DTO位置
+```
+coffee-liberica-end/
+└── business/liberica-business-sales/sales-api/
+    └── src/main/java/com/newpeak/liberica/sales/api/pojo/request/
+        └── MasterClientContactRequest.java
+            └── clientContactId: Long (@NotNull on delete)
+```
+
+### Response DTO位置
+```
+coffee-liberica-end/
+└── business/liberica-business-sales/sales-api/
+    └── src/main/java/com/newpeak/liberica/sales/api/pojo/response/
+        └── SuccessResponseData<?>
+            └── 无具体数据
+```
+
+## 2.3 CLI参数设计
+
+### 命令结构
+```
+barista liberica client-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> | clientContactId | 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/
+        └── MasterClientContactExceptionEnum.java
+            └── MASTER_CLIENT_CONTACT_NOT_EXIST("01001207001", "租户客户联系人不存在")
+```
+
+### 已知错误码
+| 错误码 | 错误消息 | 触发条件 |
+|--------|----------|----------|
+| 01001207001 | 租户客户联系人不存在 | contact-id 不存在或不属于当前租户 |
+
+## 2.6 权限检查
+
+| 检查项 | 位置 | 说明 |
+|--------|------|------|
+| PermissionConstants | `DEL_MASTER_CLIENT_CONTACT` | 删除客户联系人需要此权限 |
+| 注解 | `@PostResource(requirePermissionCode = "DEL_MASTER_CLIENT_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 client-contacts delete 12345
+# 输出: 🔍 Dry-Run 模式：不会实际删除
+#       将删除联系人: 张三 (ID: 12345)
+#       添加 --force 选项以确认删除
+
+# 确认删除
+barista liberica client-contacts delete 12345 --force
+
+# JSON 预览
+barista liberica client-contacts delete 12345 --json
+
+# JSON 确认删除
+barista liberica client-contacts delete 12345 --force --json
+```