@newpeak/barista-cli 0.1.11 → 0.1.12

package/docs/commands/liberica/teams/issues/tests-design.md

@@ -1,341 +0,0 @@
-# Team Issue Commands - Unit Test Design
-
-This document defines the unit test scenarios for all Team Issue commands in `barista liberica teams issues`.
-
-**Reference implementations:** `src/commands/liberica/teams/issues/*.ts`
-
-**Reference test patterns:** `tests/unit/commands/liberica/warehouses/*.test.ts`
-
-**Target test files (Wave 3):**
-- `tests/unit/commands/liberica/teams/issues/list.test.ts`
-- `tests/unit/commands/liberica/teams/issues/get.test.ts`
-- `tests/unit/commands/liberica/teams/issues/create.test.ts`
-- `tests/unit/commands/liberica/teams/issues/update.test.ts`
-- `tests/unit/commands/liberica/teams/issues/delete.test.ts`
-- `tests/unit/commands/liberica/teams/issues/close.test.ts`
-
----
-
-## Shared Mock Setup
-
-All tests should use the standard Vitest mock pattern from warehouse tests.
-
-```typescript
-import { describe, it, expect, beforeEach, vi } from 'vitest';
-
-vi.mock('chalk', () => ({
-  default: {
-    bold: vi.fn((text) => text),
-    green: vi.fn((text) => text),
-    red: vi.fn((text) => text),
-    gray: vi.fn((text) => text),
-    cyan: vi.fn((text) => text),
-    yellow: vi.fn((text) => text),
-    blue: vi.fn((text) => text),
-  },
-}));
-
-vi.mock('../../../../../../src/core/config/manager.js', () => ({
-  configManager: {
-    getCurrentContext: vi.fn(() => ({
-      environment: 'dev' as const,
-      service: 'liberica' as const,
-      tenant: 'test-tenant',
-    })),
-  },
-}));
-
-vi.mock('../../../../../../src/core/auth/token-manager.js', () => ({
-  tokenManager: {
-    getToken: vi.fn(() => Promise.resolve('test-token')),
-  },
-}));
-```
-
----
-
-## 1. `list` Command
-
-**File:** `src/commands/liberica/teams/issues/list.ts`
-
-**API method:** `apiClient.listTeamIssues(environment, tenant, params)`
-
-### Test Scenarios
-
-#### 1.1 Normal flow - valid input returns expected output
-- Mock `apiClient.listTeamIssues` to return a `TeamIssueListResponse` with 2 rows.
-- Parse `['node', 'test', '--page', '2', '--size', '10']`.
-- Assert `apiClient.listTeamIssues` was called with `pageNo: 1`, `pageSize: 10`.
-- Assert console output contains both issue titles and reporter names.
-
-#### 1.2 Missing required parameters - shows helpful error
-- No required parameters exist for `list`. This scenario becomes:
-- Parse with no options (`['node', 'test']`).
-- Assert default `pageNo: 0`, `pageSize: 20` is sent.
-- Assert output is still rendered gracefully (no crash).
-
-#### 1.3 Invalid parameter values - validates and reports
-- Parse `['node', 'test', '--page', 'abc']`.
-- `parseInt('abc')` yields `NaN`, resulting in `pageNo: NaN`.
-- Assert command handles this without throwing an unhandled exception (current implementation passes raw `NaN` to API).
-- Test passes invalid `--status` value `PENDING`.
-- Assert API is called with the raw string (filter validation is server-side).
-
-#### 1.4 Dry-run mode - not applicable
-- `list` is a read-only command and does not support `--dry-run`.
-- This test should verify that `--dry-run` is ignored or treated as unknown option.
-
-#### 1.5 Error response handling - API errors displayed correctly
-- Mock `apiClient.listTeamIssues` to return `{ success: false, error: { code: 'QUERY_FAILED', message: '查询失败' } }`.
-- Assert `process.exit(1)` is triggered and `console.error` contains the error message and code.
-
-#### 1.6 JSON output mode
-- Mock success response with 1 row.
-- Parse with `--json`.
-- Assert output is valid JSON containing `success: true`, `items`, and `pagination`.
-
-#### 1.7 Empty results handling
-- Mock success response with empty `rows` array.
-- Assert human-readable output contains "No team issues found".
-- For `--json`, assert `items: []` and `totalRows: 0`.
-
----
-
-## 2. `get` Command
-
-**File:** `src/commands/liberica/teams/issues/get.ts`
-
-**API method:** `apiClient.getTeamIssue(environment, tenant, issueId)`
-
-### Test Scenarios
-
-#### 2.1 Normal flow - valid input returns expected output
-- Mock `apiClient.getTeamIssue` to return a full `TeamIssue` object.
-- Parse `['node', 'test', '123456789']`.
-- Assert `apiClient.getTeamIssue` called with issue ID `'123456789'`.
-- Assert console output contains `issueTitle`, `teamIssueStatus`, `priority`, `reporterName`.
-
-#### 2.2 Missing required parameters - shows helpful error
-- Parse `['node', 'test', '']` (empty issue ID).
-- Assert `console.error` contains "Issue ID is required" and `process.exit(1)`.
-
-#### 2.3 Invalid parameter values - validates and reports
-- Parse `['node', 'test', '   ']` (whitespace-only issue ID).
-- Assert same error as empty ID: "Issue ID is required".
-
-#### 2.4 Dry-run mode - not applicable
-- `get` is read-only and does not support `--dry-run`.
-- Verify `--dry-run` is not a recognized option.
-
-#### 2.5 Error response handling - API errors displayed correctly
-- Mock `apiClient.getTeamIssue` to return `{ success: false, error: { code: 'TEAM_ISSUE_NOT_EXIST', message: '团队问题不存在' } }`.
-- Assert `console.error` contains the message and code, followed by `process.exit(1)`.
-
-#### 2.6 JSON output mode
-- Mock success response.
-- Parse `['node', 'test', '123', '--json']`.
-- Assert output is valid JSON with `success: true` and full `data` object.
-
-#### 2.7 Null data handling
-- Mock `{ success: true, data: null }`.
-- Assert output shows "Issue not found" and exits with code 1.
-
----
-
-## 3. `create` Command
-
-**File:** `src/commands/liberica/teams/issues/create.ts`
-
-**API method:** `apiClient.createTeamIssue(environment, tenant, request)`
-
-### Test Scenarios
-
-#### 3.1 Normal flow - valid input returns expected output
-- Parse with all required fields: `--title`, `--desc`, `--type`, `--project-id`, `--project-code`, `--project-name`.
-- Mock `apiClient.createTeamIssue` to return `{ success: true, data: { teamIssueId: '123', ... } }`.
-- Assert API called with correct payload including `reportDate` as ISO string.
-- Assert success message contains "Team issue created successfully" and the returned issue ID.
-
-#### 3.2 Missing required parameters - shows helpful error
-- Parse without `--title`.
-- Assert `console.error` (or `console.log` for JSON) contains "--title is required" and exits with code 1.
-- Repeat individually for `--desc`, `--type`, `--project-id`, `--project-code`, `--project-name`.
-
-#### 3.3 Invalid parameter values - validates and reports
-- Parse with `--type INVALID_TYPE`.
-- Assert error message lists valid values: `BUG, REQUIREMENT, QUESTION`.
-- Parse with `--priority INVALID`.
-- Assert error message lists valid values: `LOW, MEDIUM, HIGH, URGENT`.
-- Parse with `--status INVALID`.
-- Assert error message lists valid values: `OPEN, IN_PROGRESS, RESOLVED, CLOSED`.
-
-#### 3.4 Dry-run mode - shows preview without executing
-- Parse with all required fields plus `--dry-run`.
-- Assert `apiClient.createTeamIssue` is **not** called.
-- Assert console output contains "Dry-Run Mode" and previews the issue fields.
-- Repeat with `--dry-run --json` and assert JSON output contains `dryRun: true`.
-
-#### 3.5 Error response handling - API errors displayed correctly
-- Mock API to return `{ success: false, error: { code: 'CREATE_FAILED', message: '创建失败' } }`.
-- Assert `console.error` contains the message and code, then `process.exit(1)`.
-- Test JSON mode: assert output is `{ success: false, error: { code, message } }`.
-
-#### 3.6 Comma-separated array parsing
-- Parse with `--assign-to 'user1,user2'` and `--tags 'bug,critical'`.
-- Assert payload contains `assignTo: ['user1', 'user2']` and `tags: ['bug', 'critical']`.
-
-#### 3.7 JSON output on success
-- Mock success response.
-- Parse with `--json`.
-- Assert output JSON contains `success: true` and created issue data.
-
----
-
-## 4. `update` Command
-
-**File:** `src/commands/liberica/teams/issues/update.ts`
-
-**API method:** `apiClient.updateTeamIssue(environment, tenant, request)`
-
-### Test Scenarios
-
-#### 4.1 Normal flow - valid input returns expected output
-- Parse `['node', 'test', '123', '--title', 'Updated Title']`.
-- Mock `apiClient.updateTeamIssue` to return `{ success: true, data: { ... } }`.
-- Assert API called with `{ teamIssueId: '123', issueTitle: 'Updated Title' }`.
-- Assert success message "Team issue updated successfully".
-
-#### 4.2 Missing required parameters - shows helpful error
-- Parse `['node', 'test', '123']` with no update fields.
-- Assert `console.error` contains "No fields to update" and exits with code 1.
-
-#### 4.3 Invalid parameter values - validates and reports
-- Parse with `--type INVALID_TYPE`.
-- Assert the command still passes the raw value to the API (current implementation does not validate on update).
-- Note: because the command does not validate enums on update, the test documents this behavior.
-
-#### 4.4 Dry-run mode - not applicable
-- `update` does not currently support `--dry-run`.
-- Verify `--dry-run` is not a recognized option.
-
-#### 4.5 Error response handling - API errors displayed correctly
-- Mock API to return `{ success: false, error: { code: 'UPDATE_FAILED', message: '更新失败' } }`.
-- Assert `console.error` contains the message in plain mode.
-- Assert JSON mode returns `{ success: false, error: ... }` and exits with code 1.
-
-#### 4.6 Comma-separated array parsing
-- Parse with `--assign-to 'user1, user2'` and `--tags 'tag1, tag2'`.
-- Assert API payload contains trimmed arrays.
-
-#### 4.7 JSON output on success
-- Mock success response.
-- Parse with `--json`.
-- Assert output is valid JSON with `success: true` and `data`.
-
-#### 4.8 Unexpected exception handling
-- Mock `apiClient.updateTeamIssue` to throw `new Error('Network failure')`.
-- Assert `console.error` contains "Network failure" and `process.exit(1)`.
-- Test JSON mode returns `{ success: false, error: { message: 'Network failure' } }`.
-
----
-
-## 5. `delete` Command
-
-**File:** `src/commands/liberica/teams/issues/delete.ts`
-
-**API method:** `apiClient.deleteTeamIssue(environment, tenant, issueId)`
-
-### Test Scenarios
-
-#### 5.1 Normal flow - valid input returns expected output
-- Parse `['node', 'test', '123', '--force']`.
-- Mock `apiClient.deleteTeamIssue` to return `{ success: true, data: { teamIssueId: '123' } }`.
-- Assert API called with issue ID `'123'`.
-- Assert success message contains "Issue 123 deleted".
-
-#### 5.2 Missing required parameters - shows helpful error
-- Parse `['node', 'test', '']` (empty issue ID).
-- Assert `console.error` contains "Issue ID is required" and exits with code 1.
-
-#### 5.3 Invalid parameter values - validates and reports
-- Parse `['node', 'test', '   ']` (whitespace-only issue ID).
-- Assert same error: "Issue ID is required".
-
-#### 5.4 Dry-run mode - shows preview without executing
-- Parse `['node', 'test', '123', '--dry-run']`.
-- Assert `apiClient.deleteTeamIssue` is **not** called.
-- Assert console output contains "Delete Issue (Dry Run)" and issue ID.
-- Repeat with `--dry-run --json` and assert JSON contains `dryRun: true`.
-
-#### 5.5 Error response handling - API errors displayed correctly
-- Mock API to return `{ success: false, error: { code: 'DELETE_FAILED', message: '删除失败' } }`.
-- Assert `console.error` contains the message and exits with code 1.
-
-#### 5.6 Missing `--force` handling
-- Parse `['node', 'test', '123']` without `--force`.
-- Assert command prints warning "Add --force to confirm deletion" and exits with code 0 (not 1).
-- Assert `apiClient.deleteTeamIssue` is **not** called.
-
-#### 5.7 JSON output on success
-- Parse `['node', 'test', '123', '--force', '--json']`.
-- Mock success response.
-- Assert output JSON contains `success: true` and `issueId`.
-
----
-
-## 6. `close` Command
-
-**File:** `src/commands/liberica/teams/issues/close.ts`
-
-**API method:** `apiClient.updateTeamIssue(environment, tenant, request)`
-
-### Test Scenarios
-
-#### 6.1 Normal flow - valid input returns expected output
-- Parse `['node', 'test', '123']`.
-- Mock `apiClient.updateTeamIssue` to return `{ success: true, data: { teamIssueId: '123', teamIssueStatus: 'CLOSED' } }`.
-- Assert API called with `{ teamIssueId: '123', teamIssueStatus: 'CLOSED' }`.
-- Assert success message contains "Issue 123 closed successfully".
-
-#### 6.2 Missing required parameters - shows helpful error
-- Parse `['node', 'test', '']` (empty issue ID).
-- Assert `console.error` contains "Issue ID is required" and exits with code 1.
-
-#### 6.3 Invalid parameter values - validates and reports
-- Parse `['node', 'test', '   ']` (whitespace-only issue ID).
-- Assert same error: "Issue ID is required".
-
-#### 6.4 Dry-run mode - not applicable
-- `close` does not currently support `--dry-run`.
-- Verify `--dry-run` is not a recognized option.
-
-#### 6.5 Error response handling - API errors displayed correctly
-- Mock API to return `{ success: false, error: { code: 'CLOSE_FAILED', message: '关闭失败' } }`.
-- Assert `console.error` contains the message in plain mode.
-- Assert JSON mode returns `{ success: false, error: ... }` and exits with code 1.
-
-#### 6.6 JSON output on success
-- Parse `['node', 'test', '123', '--json']`.
-- Mock success response.
-- Assert output is valid JSON with `success: true` and `data`.
-
-#### 6.7 Unexpected exception handling
-- Mock `apiClient.updateTeamIssue` to throw `new Error('Connection timeout')`.
-- Assert `console.error` contains "Connection timeout" and `process.exit(1)`.
-- Test JSON mode returns `{ success: false, error: { message: 'Connection timeout' } }`.
-
----
-
-## Summary Table
-
-| Command | Normal Flow | Missing Params | Invalid Values | Dry-Run | Error Response | Extra Scenarios |
-|---------|-------------|----------------|----------------|---------|----------------|-----------------|
-| `list`  | 1.1         | 1.2            | 1.3            | N/A     | 1.5            | JSON, empty results |
-| `get`   | 2.1         | 2.2            | 2.3            | N/A     | 2.5            | JSON, null data |
-| `create`| 3.1         | 3.2            | 3.3            | 3.4     | 3.5            | Arrays, JSON |
-| `update`| 4.1         | 4.2            | 4.3            | N/A     | 4.5            | Arrays, JSON, exceptions |
-| `delete`| 5.1         | 5.2            | 5.3            | 5.4     | 5.5            | Force check, JSON |
-| `close` | 6.1         | 6.2            | 6.3            | N/A     | 6.5            | JSON, exceptions |
-
-Total minimum scenarios: 30 (5 per command).
-Total documented scenarios: 38 (includes edge cases and output-format tests).

package/docs/commands/liberica/teams/issues/update.md

@@ -1,202 +0,0 @@
-# barista liberica teams issues update
-
-更新团队问题。
-
-## 2.1 命令元数据
-
-| 字段 | 值 |
-|------|-----|
-| 完整命令 | `barista liberica teams issues update <issue-id>` |
-| 功能描述 | 更新已有团队问题的字段信息 |
-| HTTP方法 | POST |
-| 是否需要认证 | ✅ 是 |
-| 是否支持dry-run | ✅ 是 |
-
-## 2.2 后端接口引用
-
-### Controller位置
-```
-coffee-liberica-end/
-└── facade/liberica-facade-enterprise/
-    └── src/main/java/com/newpeak/liberica/facade/enterprise/controller/team/
-        └── EnterpriseTeamIssueController.java
-            └── edit(@PostResource(path = "/edit", requiredPermission = true, requirePermissionCode = TeamIssuePermissionConstants.EDIT_TEAM_ISSUE))
-                └── public ResponseData<? extends TeamIssueResponse> edit(
-                        @RequestHeader("X-TENANT-ID") Long tenantId,
-                        @RequestBody @Validated(BaseRequest.edit.class) TeamIssueRequest teamIssueRequest
-                    )
-```
-
-### Request DTO位置
-```
-coffee-liberica-end/
-└── business/liberica-business-team/team-api/
-    └── src/main/java/com/newpeak/liberica/team/api/pojo/request/
-        └── TeamIssueRequest.java
-            ├── teamIssueId: Long (@NotNull on edit)
-            ├── teamIssueCode: String (max=255)
-            ├── issueTitle: String (@NotBlank, max=500)
-            ├── issueType: String (max=20)
-            ├── issueDesc: String (@NotNull)
-            ├── projectId: Long (@NotNull)
-            ├── projectCode: String (@NotBlank, max=50)
-            ├── projectName: String (@NotBlank, max=200)
-            ├── reporterAccount: String (max=255)
-            ├── reporterName: String (@NotBlank, max=100)
-            ├── reporterEmail: String (@NotBlank, max=200)
-            ├── reportDate: Date
-            ├── assignTo: JSON (@NotNull)
-            ├── teamIssueStatus: String (@NotBlank, max=20)
-            ├── priority: String (@NotBlank, max=20)
-            ├── solution: String
-            ├── tags: JSON
-            └── refId: String (max=255)
-```
-
-### Response DTO位置
-```
-coffee-liberica-end/
-└── business/liberica-business-team/team-api/
-    └── src/main/java/com/newpeak/liberica/team/api/pojo/response/
-        └── TeamIssueResponse.java
-            ├── teamIssueId: Long
-            ├── teamIssueCode: String
-            ├── issueTitle: String
-            ├── issueType: String
-            ├── teamIssueStatus: String
-            ├── priority: String
-            ├── reporterName: String
-            ├── projectId: Long
-            ├── projectCode: String
-            ├── projectName: String
-            └── updateTime: String
-```
-
-## 2.3 CLI参数设计
-
-### 命令结构
-```
-barista liberica teams issues update <issue-id> [options]
-```
-
-### Usage
-```bash
-barista liberica teams issues update 123456789 --title "新标题"
-barista liberica teams issues update 123456789 --status CLOSED
-```
-
-### 全局选项
-| 选项 | 类型 | 说明 |
-|------|------|------|
-| `--env` | string | 目标环境(dev\|test\|prod-cn\|prod-jp) |
-| `--tenant` | string | 租户代码 |
-| `--dry-run` | boolean | 预览模式（不实际调用API） |
-| `--json` | boolean | JSON输出 |
-
-### 位置参数
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| issue-id | string | ✅ | 要更新的问题ID |
-
-### 命令选项
-| 选项 | 短选项 | 类型 | 必填 | 默认值 | 说明 | 对应DTO字段 |
-|------|--------|------|------|--------|------|-------------|
-| --title | -t | string | ⬜ | - | 问题标题 | issueTitle |
-| --desc | -d | string | ⬜ | - | 问题描述 | issueDesc |
-| --type | -y | string | ⬜ | - | 问题类型（BUG/REQUIREMENT/QUESTION） | issueType |
-| --status | -s | string | ⬜ | - | 问题状态（OPEN/IN_PROGRESS/RESOLVED/CLOSED） | teamIssueStatus |
-| --priority | -p | string | ⬜ | - | 优先级（LOW/MEDIUM/HIGH/URGENT） | priority |
-| --project-id | — | string | ⬜ | - | 所属项目ID | projectId |
-| --project-code | — | string | ⬜ | - | 所属项目代号 | projectCode |
-| --project-name | — | string | ⬜ | - | 所属项目名称 | projectName |
-| --assign-to | -a | string | ⬜ | - | 负责人ID列表，逗号分隔 | assignTo |
-| --tags | — | string | ⬜ | - | 标签列表，逗号分隔 | tags |
-| --json | -j | boolean | ⬜ | false | JSON格式输出 | - |
-
-## 2.4 字段映射表
-
-| CLI参数 | DTO字段 | 类型转换 | 验证规则 |
-|---------|---------|----------|----------|
-| issue-id (位置参数) | teamIssueId | string→Long | @NotNull |
-| --title / -t | issueTitle | 直接传递 | @NotBlank, max=500 |
-| --desc / -d | issueDesc | 直接传递 | @NotNull |
-| --type / -y | issueType | 直接传递 | BUG, REQUIREMENT, QUESTION |
-| --status / -s | teamIssueStatus | 直接传递 | OPEN, IN_PROGRESS, RESOLVED, CLOSED |
-| --priority / -p | priority | 直接传递 | LOW, MEDIUM, HIGH, URGENT |
-| --project-id | projectId | string→Long | @NotNull |
-| --project-code | projectCode | 直接传递 | @NotBlank, max=50 |
-| --project-name | projectName | 直接传递 | @NotBlank, max=200 |
-| --assign-to / -a | assignTo | string→JSON数组 | @NotNull |
-| --tags | tags | string→JSON数组 | 逗号分隔标签 |
-
-## 2.5 错误码引用
-
-### ExceptionEnum位置
-```
-coffee-liberica-end/
-└── business/liberica-business-team/team-api/
-    └── src/main/java/com/newpeak/liberica/team/api/exception/enums/
-        └── TeamIssueExceptionEnum.java
-            └── TEAM_ISSUE_NOT_EXIST("01001958001", "团队问题不存在")
-```
-
-### Service层业务校验
-```
-coffee-liberica-end/
-└── business/liberica-business-team/team-business/
-    └── src/main/java/com/newpeak/liberica/team/modular/business/
-        └── TeamIssueBusiness.java
-            └── edit(TeamIssueRequest request)
-                └── 检查团队问题是否存在
-                    └── throw new TeamServiceException(TeamIssueExceptionEnum.TEAM_ISSUE_NOT_EXIST)
-```
-
-### 已知错误码
-| 错误码 | 错误消息 | 触发条件 |
-|--------|----------|----------|
-| 01001958001 | 团队问题不存在 | 更新的 issue-id 不存在或已被删除 |
-
-## 2.6 权限检查
-
-| 检查项 | 位置 | 说明 |
-|--------|------|------|
-| PermissionConstants | `TeamIssuePermissionConstants.EDIT_TEAM_ISSUE` | Controller层 `@PostResource(requirePermissionCode = "EDIT_TEAM_ISSUE")` |
-
-## 2.7 实现要点
-
-1. **必填参数**：`issue-id` 作为位置参数必须提供
-2. **部分更新**：只传入的选项才会被包含在请求体中，未传入的字段保持原值
-3. **assignTo / tags 序列化**：逗号分隔的字符串需要在 CLI 内部转换为 JSON 数组格式
-4. **Dry-run 支持**：使用 `--dry-run` 时构造请求体但不发送，显示预览信息
-5. **状态流转**：不在 CLI 层做状态机校验，直接透传给后端
-6. **ID 类型处理**：`teamIssueId`、`projectId` 后端使用 Long (BigInteger)，CLI 使用 string 避免精度丢失
-7. **无 X-TENANT-ID Header**：CLI 不手动添加该 header，租户信息由后端从 JWT 中提取
-
-## 2.8 示例用法
-
-```bash
-# 更新标题
-barista liberica teams issues update 123456789 --title "修正后的标题"
-
-# 更新状态和优先级
-barista liberica teams issues update 123456789 \
-  --status IN_PROGRESS \
-  --priority HIGH
-
-# 更新指派人和标签
-barista liberica teams issues update 123456789 \
-  --assign-to "111,222" \
-  --tags "前端,紧急"
-
-# 更新项目信息
-barista liberica teams issues update 123456789 \
-  --project-id 987654321 \
-  --project-code "CRM" \
-  --project-name "CRM系统"
-
-# Dry-run 预览
-barista liberica teams issues update 123456789 --title "测试更新" --dry-run
-
-# JSON 输出
-barista liberica teams issues update 123456789 --title "测试更新" --json
-```