@newpeak/barista-cli 0.1.11 → 0.1.12

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

@@ -1,333 +0,0 @@
-# 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

@@ -1,152 +0,0 @@
-# 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

@@ -1,123 +0,0 @@
-# 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
-```