@newpeak/barista-cli 0.1.8 → 0.1.10

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

@@ -0,0 +1,182 @@
+# barista liberica teams issues list
+
+分页查询团队问题列表。
+
+## 2.1 命令元数据
+
+| 字段 | 值 |
+|------|-----|
+| 完整命令 | `barista liberica teams issues list` |
+| 功能描述 | 分页查询团队问题列表 |
+| HTTP方法 | GET |
+| 是否需要认证 | ✅ 是 |
+| 是否支持dry-run | ⬜ 否 |
+
+## 2.2 后端接口引用
+
+### Controller位置
+```
+coffee-liberica-end/
+└── facade/liberica-facade-enterprise/
+    └── src/main/java/com/newpeak/liberica/facade/enterprise/controller/team/
+        └── EnterpriseTeamIssueController.java
+            └── page(@GetResource(path = "/page"))
+                └── public ResponseData<PageResult<TeamIssueResponse>> page(
+                        @RequestHeader("X-TENANT-ID") Long tenantId,
+                        @ParameterObject TeamIssueQueryRequest teamIssueQueryRequest
+                    )
+```
+
+### Request DTO位置
+```
+coffee-liberica-end/
+└── business/liberica-business-team/team-api/
+    └── src/main/java/com/newpeak/liberica/team/api/pojo/request/
+        └── TeamIssueQueryRequest.java
+            ├── pageNo: Long (分页当前页，0-based)
+            ├── pageSize: Long (分页大小)
+            ├── teamIssueStatus: String (问题状态)
+            ├── issueType: String (问题类型)
+            ├── priority: String (优先级)
+            ├── projectId: Long (所属项目ID)
+            ├── issueTitle: String (问题标题，模糊搜索)
+            ├── teamIssueCode: String (问题编码)
+            ├── reporterName: String (报告人名称)
+            └── reportDate: Date (报告日期)
+```
+
+### 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
+            ├── reportDate: Date
+            └── createTime: String
+```
+
+### 分页包装器
+```
+cn.stylefeng.roses.kernel.db.api.pojo.page.PageResult
+    ├── totalRows: long
+    ├── pageSize: long
+    ├── pageNo: long
+    └── rows: List<TeamIssueResponse>
+```
+
+## 2.3 CLI参数设计
+
+### 命令结构
+```
+barista liberica teams issues list [options]
+```
+
+### Usage
+```bash
+barista liberica teams issues list
+barista liberica teams issues list --page 2 --size 50
+```
+
+### 全局选项
+| 选项 | 类型 | 说明 |
+|------|------|------|
+| `--env` | string | 目标环境(dev\|test\|prod-cn\|prod-jp) |
+| `--tenant` | string | 租户代码 |
+| `--json` | boolean | JSON输出 |
+
+### 命令选项
+| 选项 | 短选项 | 类型 | 必填 | 默认值 | 说明 | 对应DTO字段 |
+|------|--------|------|------|--------|------|-------------|
+| --page | -p | number | ⬜ | 1 | 页码（1-based） | pageNo |
+| --size | -s | number | ⬜ | 20 | 每页条数 | pageSize |
+| --status | — | string | ⬜ | - | 按状态筛选（OPEN/IN_PROGRESS/RESOLVED/CLOSED） | teamIssueStatus |
+| --type | -t | string | ⬜ | - | 按类型筛选（BUG/REQUIREMENT/QUESTION） | issueType |
+| --priority | — | string | ⬜ | - | 按优先级筛选（LOW/MEDIUM/HIGH/URGENT） | priority |
+| --project-id | — | string | ⬜ | - | 按项目ID筛选 | projectId |
+| --title | — | string | ⬜ | - | 按标题模糊搜索 | issueTitle |
+
+## 2.4 字段映射表
+
+| CLI参数 | DTO字段 | 类型转换 | 验证规则 |
+|---------|---------|----------|----------|
+| --page / -p | pageNo | number→Long, CLI page - 1 | >= 0 |
+| --size / -s | pageSize | number→Long | > 0 |
+| --status | teamIssueStatus | 直接传递 | OPEN, IN_PROGRESS, RESOLVED, CLOSED |
+| --type / -t | issueType | 直接传递 | BUG, REQUIREMENT, QUESTION |
+| --priority | priority | 直接传递 | LOW, MEDIUM, HIGH, URGENT |
+| --project-id | projectId | string→Long | - |
+| --title | issueTitle | 直接传递 | max=500 |
+
+## 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", "团队问题不存在")
+```
+
+### 已知错误码
+| 错误码 | 错误消息 | 触发条件 |
+|--------|----------|----------|
+| 01001958001 | 团队问题不存在 | 详情/编辑/删除时ID不存在 |
+
+## 2.6 权限检查
+
+| 检查项 | 位置 | 说明 |
+|--------|------|------|
+| 注解 | `@GetResource(path = "/page")` | 无 requiredPermission（列表查询无需权限码） |
+
+**注意**：list 和 page 接口在 Controller 层无需权限校验，数据范围通过 tenantId 隔离。
+
+## 2.7 实现要点
+
+1. **分页默认值**：page=1, size=20
+2. **分页转换**：CLI 使用 1-based 页码，API 使用 0-based，转换公式 `pageNo = options.page - 1`
+3. **响应字段**：后端返回 `rows`、`totalRows`、`pageNo`、`pageSize`，不使用 `records` 或 `total`
+4. **ID 类型处理**：`teamIssueId`、`projectId` 等 ID 字段后端使用 Long (BigInteger)，CLI 使用 string 避免精度丢失
+5. **无结果处理**：返回空列表，不抛出异常
+6. **输出格式**：表格形式展示 ID、Code、Title、Type、Status、Priority、Reporter、Project
+
+## 2.8 示例用法
+
+```bash
+# 默认分页
+barista liberica teams issues list
+
+# 指定页码和每页条数
+barista liberica teams issues list --page 2 --size 50
+
+# 按状态筛选
+barista liberica teams issues list --status OPEN
+
+# 按类型筛选
+barista liberica teams issues list --type BUG
+
+# 按优先级筛选
+barista liberica teams issues list --priority HIGH
+
+# 按项目ID筛选
+barista liberica teams issues list --project-id 123456789
+
+# 按标题搜索
+barista liberica teams issues list --title "登录失败"
+
+# 组合筛选
+barista liberica teams issues list --status OPEN --type BUG --priority HIGH
+
+# JSON 输出
+barista liberica teams issues list --json
+```

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

@@ -0,0 +1,341 @@
+# 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).