@newpeak/barista-cli 0.1.0

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

@@ -0,0 +1,138 @@
+# barista liberica employees disable
+
+禁用（停用）员工账号。
+
+## 2.1 命令元数据
+
+| 字段 | 值 |
+|------|-----|
+| 完整命令 | `barista liberica employees disable <id>` |
+| 功能描述 | 禁用（停用）员工账号 |
+| HTTP方法 | POST |
+| 是否需要认证 | ✅ 是 |
+| 是否支持dry-run | ✅ 是 |
+
+## 2.2 后端接口引用
+
+### Controller位置
+```
+coffee-liberica-end/
+└── facade/liberica-facade-enterprise/
+    └── src/main/java/com/newpeak/liberica/facade/enterprise/controller/master/
+        └── EnterpriseEmployeeController.java
+            └── deActive(@PostResource(path = "/deActive", requiredPermission = true, requirePermissionCode = "DE_ACTIVE_EMPLOYEE"))
+                └── public ResponseData<String> deActive(
+                        @RequestHeader("X-TENANT-ID") Long tenantId,
+                        @RequestBody MasterEmployeeRequest request
+                    )
+```
+
+### Request DTO位置
+```
+coffee-liberica-end/
+└── business/liberica-business-master/master-api/
+    └── src/main/java/com/newpeak/liberica/master/api/pojo/request/
+        └── MasterEmployeeRequest.java
+            └── employeeId: Long
+```
+
+### Response DTO位置
+```
+coffee-liberica-end/
+└── business/liberica-business-master/master-api/
+    └── src/main/java/com/newpeak/liberica/master/api/pojo/response/
+        └── MasterEmployeeResponse.java
+            └── 返回更新后的员工详情（同 create/update）
+```
+
+## 2.3 CLI参数设计
+
+### 命令结构
+```
+barista liberica employees disable <id> [options]
+```
+
+### 位置参数
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| id | number | ✅ | 员工ID (employeeId) |
+
+### 全局选项
+| 选项 | 类型 | 说明 |
+|------|------|------|
+| `--env` | string | 目标环境(dev\|test\|prod-cn\|prod-jp) |
+| `--tenant` | string | 租户代码 |
+| `--dry-run` | boolean | 预览模式（不实际调用API） |
+| `--json` | boolean | JSON输出 |
+
+### 命令选项
+| 选项 | 短选项 | 类型 | 必填 | 默认值 | 说明 |
+|------|--------|------|------|--------|------|
+| --force | -f | boolean | ⬜ | false | 跳过确认提示 |
+
+**说明**：
+- `--dry-run` 预览禁用操作的影响（显示将禁用的员工信息）
+- `--force` 直接执行，不显示确认提示（适用于脚本自动化）
+
+## 2.4 字段映射表
+
+| CLI参数 | DTO字段 | 类型转换 | 验证规则 |
+|---------|---------|----------|----------|
+| <id> (位置参数) | employeeId | 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/
+        └── EmployeeExceptionEnum.java
+            ├── MASTER_EMPLOYEE_NOT_EXISTED("01001150001", "查询结果不存在")
+            ├── DELETE_EMPLOYEE_ERROR("01001150002", "删除职员失败，该职员下有绑定数据")
+            └── MASTER_EMPLOYEE_NAME_VALIDATE_NOT_EXIST_ERROR("01001150009", "指定{}不存在")
+```
+
+### 已知错误码
+| 错误码 | 错误消息 | 触发条件 |
+|--------|----------|----------|
+| 01001150001 | 查询结果不存在 | employeeId 不存在或不属于当前租户 |
+| 01001150002 | 删除职员失败，该职员下有绑定数据 | 禁用时该员工存在绑定数据 |
+
+## 2.6 权限检查
+
+| 检查项 | 位置 | 说明 |
+|--------|------|------|
+| PermissionConstants | `LibericaPermissionCodeConstants.DE_ACTIVE_EMPLOYEE` | Controller层 `@PostResource(requirePermissionCode = "DE_ACTIVE_EMPLOYEE")` |
+
+## 2.7 实现要点
+
+1. **幂等性**：deActive 操作是幂等的——对已禁用的员工再次调用效果相同（直接 set statusFlag=DISABLE）
+2. **幂等性原理**：后端直接 `LambdaUpdateWrapper.set(MasterEmployee::getStatusFlag, DISABLE)`，不检查当前状态
+3. **Dry-run模式**：预览显示将禁用的员工信息，但不实际发送请求
+4. **无强制选项**：--force 跳过确认提示，但不绕过后端权限检查
+5. **Error 01001150002**：如果禁用失败（存在绑定数据），显示后端错误消息
+
+## 2.8 示例用法
+
+```bash
+# 禁用员工（交互确认）
+barista liberica employees disable 12345
+
+# 跳过确认直接禁用
+barista liberica employees disable 12345 --force
+
+# Dry-run 预览
+barista liberica employees disable 12345 --dry-run
+
+# JSON 输出
+barista liberica employees disable 12345 --force --json
+
+# 员工不存在
+barista liberica employees disable 99999
+# 输出: Error: 员工不存在 (01001150001)
+
+# 员工有绑定数据
+barista liberica employees disable 12345 --force
+# 输出: Error: 删除职员失败，该职员下有绑定数据 (01001150002)
+```

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

@@ -0,0 +1,137 @@
+# barista liberica employees enable
+
+启用（激活）员工账号。
+
+## 2.1 命令元数据
+
+| 字段 | 值 |
+|------|-----|
+| 完整命令 | `barista liberica employees enable <id>` |
+| 功能描述 | 启用（激活）员工账号 |
+| HTTP方法 | POST |
+| 是否需要认证 | ✅ 是 |
+| 是否支持dry-run | ✅ 是 |
+
+## 2.2 后端接口引用
+
+### Controller位置
+```
+coffee-liberica-end/
+└── facade/liberica-facade-enterprise/
+    └── src/main/java/com/newpeak/liberica/facade/enterprise/controller/master/
+        └── EnterpriseEmployeeController.java
+            └── active(@PostResource(path = "/active", requiredPermission = true, requirePermissionCode = "ACTIVE_EMPLOYEE"))
+                └── public ResponseData<String> active(
+                        @RequestHeader("X-TENANT-ID") Long tenantId,
+                        @RequestBody MasterEmployeeRequest request
+                    )
+```
+
+### Request DTO位置
+```
+coffee-liberica-end/
+└── business/liberica-business-master/master-api/
+    └── src/main/java/com/newpeak/liberica/master/api/pojo/request/
+        └── MasterEmployeeRequest.java
+            └── employeeId: Long
+```
+
+### Response DTO位置
+```
+coffee-liberica-end/
+└── business/liberica-business-master/master-api/
+    └── src/main/java/com/newpeak/liberica/master/api/pojo/response/
+        └── MasterEmployeeResponse.java
+            └── 返回更新后的员工详情（同 create/update）
+```
+
+## 2.3 CLI参数设计
+
+### 命令结构
+```
+barista liberica employees enable <id> [options]
+```
+
+### 位置参数
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| id | number | ✅ | 员工ID (employeeId) |
+
+### 全局选项
+| 选项 | 类型 | 说明 |
+|------|------|------|
+| `--env` | string | 目标环境(dev\|test\|prod-cn\|prod-jp) |
+| `--tenant` | string | 租户代码 |
+| `--dry-run` | boolean | 预览模式（不实际调用API） |
+| `--json` | boolean | JSON输出 |
+
+### 命令选项
+| 选项 | 短选项 | 类型 | 必填 | 默认值 | 说明 |
+|------|--------|------|------|--------|------|
+| --force | -f | boolean | ⬜ | false | 跳过确认提示 |
+
+**说明**：
+- `--dry-run` 预览启用操作的影响（显示将启用的员工信息）
+- `--force` 直接执行，不显示确认提示（适用于脚本自动化）
+
+## 2.4 字段映射表
+
+| CLI参数 | DTO字段 | 类型转换 | 验证规则 |
+|---------|---------|----------|----------|
+| <id> (位置参数) | employeeId | string→Long | @NotNull |
+
+## 2.5 错误码引用
+
+### ExceptionEnum位置
+```
+coffee-liberica-end/
+└── business/liberica-business-master/master-api/
+    └── src/main/java/com/newpeak/liberica/master/api/pojo/request/
+        └── MasterEmployeeRequest.java
+            ├── MASTER_EMPLOYEE_NOT_EXISTED("01001150001", "查询结果不存在")
+            └── MASTER_EMPLOYEE_NAME_VALIDATE_NOT_EXIST_ERROR("01001150009", "指定{}不存在")
+```
+
+### 已知错误码
+| 错误码 | 错误消息 | 触发条件 |
+|--------|----------|----------|
+| 01001150001 | 查询结果不存在 | employeeId 不存在或不属于当前租户 |
+| 01001150009 | 指定xxx不存在 | 指定关联的员工编码不存在 |
+
+## 2.6 权限检查
+
+| 检查项 | 位置 | 说明 |
+|--------|------|------|
+| PermissionConstants | `LibericaPermissionCodeConstants.ACTIVE_EMPLOYEE` | Controller层 `@PostResource(requirePermissionCode = "ACTIVE_EMPLOYEE")` |
+
+## 2.7 实现要点
+
+1. **幂等性**：active 操作是幂等的——对已启用的员工再次调用效果相同（直接 set statusFlag=ENABLE）
+2. **幂等性原理**：后端直接 `LambdaUpdateWrapper.set(MasterEmployee::getStatusFlag, ENABLE)`，不检查当前状态
+3. **Dry-run模式**：预览显示将启用的员工信息，但不实际发送请求
+4. **无强制选项**：--force 跳过确认提示，但不绕过后端权限检查
+5. **与disable对称**：enable 与 disable 互为逆操作，使用相同的 employeeId 参数结构
+
+## 2.8 示例用法
+
+```bash
+# 启用员工（交互确认）
+barista liberica employees enable 12345
+
+# 跳过确认直接启用
+barista liberica employees enable 12345 --force
+
+# Dry-run 预览
+barista liberica employees enable 12345 --dry-run
+
+# JSON 输出
+barista liberica employees enable 12345 --force --json
+
+# 员工不存在
+barista liberica employees enable 99999
+# 输出: Error: 员工不存在 (01001150001)
+
+# 对已启用员工重复启用（幂等，无报错）
+barista liberica employees enable 12345 --force
+# 输出: ✓ 员工启用成功
+```

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

@@ -0,0 +1,153 @@
+# barista liberica employees get
+
+获取单个员工详情。
+
+## 2.1 命令元数据
+
+| 字段 | 值 |
+|------|-----|
+| 完整命令 | `barista liberica employees 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/
+        └── EnterpriseEmployeeController.java
+            └── detail(@GetResource(path = "/detail"))
+                └── public ResponseData<MasterEmployeeResponse> detail(
+                        @RequestHeader("X-TENANT-ID") Long tenantId,
+                        @RequestParam("employeeId") Long employeeId
+                    )
+```
+
+### Request DTO位置
+```
+coffee-liberica-end/
+└── business/liberica-business-master/master-api/
+    └── src/main/java/com/newpeak/liberica/master/api/pojo/request/
+        └── MasterEmployeeRequest.java
+            └── employeeId: 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/
+        └── MasterEmployeeResponse.java
+            ├── employeeId: Long
+            ├── employeeCode: String
+            ├── employeeName: String
+            ├── employeeNo: String
+            ├── employeePhone: String
+            ├── employeeEmail: String
+            ├── employeeSex: SexEnum
+            ├── employeeIdType: String
+            ├── employeeIdNo: String
+            ├── employeeJoinedDate: Date
+            ├── employeeLeaveDate: Date
+            ├── employeeBirthday: Date
+            ├── organizationId: Long
+            ├── orgCode: String
+            ├── orgName: String
+            ├── organizationManagerFlag: String
+            ├── positionId: String
+            ├── positionName: String
+            ├── jobType: String
+            ├── jobLevelNo: String
+            ├── evaluator1: String (员工编码)
+            ├── evaluator2: String (员工编码)
+            ├── coach: String (员工编码)
+            ├── employeeStatus: String
+            ├── statusFlag: Integer (1=enable, 2=disable)
+            ├── employeeBankAccount: String
+            ├── employeeDepositBank: String
+            ├── account: String
+            ├── encryptPassword: String
+            ├── showQrCode: boolean
+            ├── qrCode: String (SVG)
+            ├── createTime: String
+            └── updateTime: String
+```
+
+## 2.3 CLI参数设计
+
+### 命令结构
+```
+barista liberica employees get <id> [options]
+```
+
+### 位置参数
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| id | number | ✅ | 员工ID (employeeId) |
+
+### 全局选项
+| 选项 | 类型 | 说明 |
+|------|------|------|
+| `--env` | string | 目标环境(dev\|test\|prod-cn\|prod-jp) |
+| `--tenant` | string | 租户代码 |
+| `--json` | boolean | JSON输出 |
+
+### 命令选项
+| 选项 | 短选项 | 类型 | 必填 | 默认值 | 说明 |
+|------|--------|------|------|--------|------|
+| — | — | — | — | — | 此命令无额外选项，ID 通过位置参数传入 |
+
+## 2.4 字段映射表
+
+| CLI参数 | DTO字段 | 类型转换 | 验证规则 |
+|---------|---------|----------|----------|
+| <id> (位置参数) | employeeId | 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/
+        └── EmployeeExceptionEnum.java
+            ├── MASTER_EMPLOYEE_NOT_EXISTED("01001150001", "查询结果不存在")
+            ├── MASTER_EMPLOYEE_CODE_VALIDATE_NOT_EXIST_ERROR("01001150007", "指定{}不存在")
+            └── MASTER_EMPLOYEE_NAME_VALIDATE_NOT_EXIST_ERROR("01001150009", "指定{}不存在")
+```
+
+### 已知错误码
+| 错误码 | 错误消息 | 触发条件 |
+|--------|----------|----------|
+| 01001150001 | 查询结果不存在 | employeeId 不存在或不属于当前租户 |
+
+## 2.6 权限检查
+
+| 检查项 | 位置 | 说明 |
+|--------|------|------|
+| 注解 | `@GetResource(path = "/detail")` | 无 requiredPermission |
+
+## 2.7 实现要点
+
+1. **位置参数**：`get` 命令使用 `<id>` 位置参数指定员工ID
+2. **错误处理**：员工不存在时抛出 `MASTER_EMPLOYEE_NOT_EXISTED`，CLI 显示友好错误信息
+3. **tenantId来源**：来自 X-TENANT-ID header，后端自动按租户隔离数据
+4. **QR Code**：响应中包含 qrCode (SVG)，可在需要时通过 --json 输出展示
+
+## 2.8 示例用法
+
+```bash
+# 获取员工详情
+barista liberica employees get 12345
+
+# JSON 输出
+barista liberica employees get 12345 --json
+
+# 员工不存在
+barista liberica employees get 99999
+# 输出: Error: 员工不存在 (01001150001)
+```

package/docs/commands/liberica/employees/list.md

@@ -0,0 +1,168 @@
+# barista liberica employees list
+
+分页查询员工列表。
+
+## 2.1 命令元数据
+
+| 字段 | 值 |
+|------|-----|
+| 完整命令 | `barista liberica employees 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/
+        └── EnterpriseEmployeeController.java
+            └── page(@GetResource(path = "/page"))
+                └── public ResponseData<PageResult<MasterEmployeeResponse>> page(
+                        @RequestHeader("X-TENANT-ID") Long tenantId,
+                        MasterEmployeeRequest request
+                    )
+```
+
+### Request DTO位置
+```
+coffee-liberica-end/
+└── business/liberica-business-master/master-api/
+    └── src/main/java/com/newpeak/liberica/master/api/pojo/request/
+        └── MasterEmployeeRequest.java
+            ├── current: Long (分页当前页)
+            ├── size: Long (分页大小)
+            ├── searchText: String (搜索: 姓名/编码)
+            ├── employeeStatus: String (在职状态)
+            ├── organizationId: Long (部门ID)
+            ├── excludeEmployeeCodeList: Set<String>
+            ├── excludeEmployeeIdList: Set<Long>
+            ├── searchBeginTime: String
+            └── searchEndTime: String
+```
+
+### Response DTO位置
+```
+coffee-liberica-end/
+└── business/liberica-business-master/master-api/
+    └── src/main/java/com/newpeak/liberica/master/api/pojo/response/
+        └── MasterEmployeeResponse.java
+            ├── employeeId: Long
+            ├── employeeCode: String
+            ├── employeeName: String
+            ├── employeeNo: String
+            ├── employeePhone: String
+            ├── employeeEmail: String
+            ├── employeeSex: SexEnum
+            ├── organizationId: Long
+            ├── orgName: String
+            ├── positionId: String
+            ├── positionName: String
+            ├── statusFlag: Integer (1=enable, 2=disable)
+            ├── createTime: String
+            └── updateTime: String
+```
+
+### 分页包装器
+```
+cn.stylefeng.roses.kernel.db.api.pojo.page.PageResult
+    ├── total: long
+    ├── size: long
+    ├── current: long
+    └── records: List<MasterEmployeeResponse>
+```
+
+## 2.3 CLI参数设计
+
+### 命令结构
+```
+barista liberica employees list [options]
+```
+
+### 全局选项
+| 选项 | 类型 | 说明 |
+|------|------|------|
+| `--env` | string | 目标环境(dev\|test\|prod-cn\|prod-jp) |
+| `--tenant` | string | 租户代码 |
+| `--json` | boolean | JSON输出 |
+
+### 命令选项
+| 选项 | 短选项 | 类型 | 必填 | 默认值 | 说明 | 对应DTO字段 |
+|------|--------|------|------|--------|------|-------------|
+| --page | -p | number | ⬜ | 1 | 页码 | current |
+| --size | -s | number | ⬜ | 20 | 每页条数 | size |
+| --status | — | string | ⬜ | - | 在职状态 | employeeStatus |
+| --org-id | — | number | ⬜ | - | 部门ID | organizationId |
+| --search | — | string | ⬜ | - | 搜索关键词(姓名/编码) | searchText |
+
+## 2.4 字段映射表
+
+| CLI参数 | DTO字段 | 类型转换 | 验证规则 |
+|---------|---------|----------|----------|
+| --page / -p | current | number→Long | >= 1 |
+| --size / -s | size | number→Long | 1-100 |
+| --status | employeeStatus | 直接传递 | 枚举验证 |
+| --org-id | organizationId | string→Long | - |
+| --search | searchText | 直接传递 | - |
+
+## 2.5 错误码引用
+
+### ExceptionEnum位置
+```
+coffee-liberica-end/
+└── business/liberica-business-master/master-api/
+    └── src/main/java/com/newpeak/liberica/master/api/exception/enums/
+        └── EmployeeExceptionEnum.java
+            ├── MASTER_EMPLOYEE_NOT_EXISTED("01001150001", "查询结果不存在")
+            ├── MASTER_EMPLOYEE_NAME_VALIDATE_NOT_EXIST_ERROR("01001150009", "指定{}不存在")
+            └── MASTER_EMPLOYEE_IMPORT_DATA_EMPTY("01001150010", "职员导入数据为空")
+```
+
+### 已知错误码
+| 错误码 | 错误消息 | 触发条件 |
+|--------|----------|----------|
+| 01001150001 | 查询结果不存在 | 条件查询无匹配结果（通常返回空列表而非报错） |
+
+## 2.6 权限检查
+
+| 检查项 | 位置 | 说明 |
+|--------|------|------|
+| 注解 | `@GetResource(path = "/page")` | 无 requiredPermission（无需权限码） |
+
+**注意**：list 和 page 接口在 Controller 层无需权限校验，数据范围通过 tenantId 隔离。
+
+## 2.7 实现要点
+
+1. **分页默认值**：page=1, size=20
+2. **搜索行为**：searchText 同时匹配 employeeName 和 employeeCode（模糊查询）
+3. **无结果处理**：返回空列表，不抛出异常
+4. **tenantId来源**：来自 X-TENANT-ID header
+5. **输出格式**：表格形式展示，分页信息在底部显示
+
+## 2.8 示例用法
+
+```bash
+# 默认分页
+barista liberica employees list
+
+# 指定页码和每页条数
+barista liberica employees list --page 2 --size 50
+
+# 按部门筛选
+barista liberica employees list --org-id 1001
+
+# 按在职状态筛选
+barista liberica employees list --status IN_SERVICE
+
+# 关键词搜索
+barista liberica employees list --search "张三"
+
+# 组合筛选
+barista liberica employees list --page 1 --size 10 --org-id 1001 --status IN_SERVICE
+
+# JSON 输出（便于脚本处理）
+barista liberica employees list --page 1 --size 20 --json
+```