@newpeak/barista-cli 0.1.9 → 0.1.10

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

@@ -0,0 +1,179 @@
+# barista liberica teams issues delete
+
+删除团队问题。
+
+## 2.1 命令元数据
+
+| 字段 | 值 |
+|------|-----|
+| 完整命令 | `barista liberica teams issues delete <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
+            └── delete(@PostResource(path = "/delete", requiredPermission = true, requirePermissionCode = TeamIssuePermissionConstants.DEL_TEAM_ISSUE))
+                └── public ResponseData<?> delete(
+                        @RequestHeader("X-TENANT-ID") Long tenantId,
+                        @RequestBody @Validated(BaseRequest.delete.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 delete)
+            └── tenantId: Long
+```
+
+**删除请求体结构：**
+```json
+{
+  "teamIssueId": 123456789
+}
+```
+
+### 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
+```
+
+## 2.3 CLI参数设计
+
+### 命令结构
+```
+barista liberica teams issues delete <issue-id> [options]
+```
+
+### Usage
+```bash
+barista liberica teams issues delete 123456789
+barista liberica teams issues delete 123456789 --force
+```
+
+### 全局选项
+| 选项 | 类型 | 说明 |
+|------|------|------|
+| `--env` | string | 目标环境(dev\|test\|prod-cn\|prod-jp) |
+| `--tenant` | string | 租户代码 |
+| `--json` | boolean | JSON输出 |
+
+### 位置参数
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| issue-id | string | ✅ | 要删除的问题ID |
+
+### 命令选项
+| 选项 | 短选项 | 类型 | 必填 | 默认值 | 说明 | 对应DTO字段 |
+|------|--------|------|------|--------|------|-------------|
+| --force | -f | boolean | ⬜ | false | 跳过确认直接删除 | - |
+| --json | -j | boolean | ⬜ | false | JSON格式输出 | - |
+
+## 2.4 字段映射表
+
+| CLI参数 | DTO字段 | 类型转换 | 验证规则 |
+|---------|---------|----------|----------|
+| issue-id (位置参数) | teamIssueId | string→Long | @NotNull |
+
+## 2.5 确认流程
+
+删除操作默认启用dry-run行为，需要用户显式确认：
+
+### 默认行为（无--force）
+```bash
+$ barista liberica teams issues delete 123456789
+
+⚠️  Delete Team Issue
+
+  Issue ID: 123456789
+  Title: 登录页面样式异常
+
+Add --force to confirm deletion
+```
+
+### 强制删除（带--force）
+```bash
+$ barista liberica teams issues delete 123456789 --force
+
+✓ Issue "登录页面样式异常" (ID: 123456789) deleted
+```
+
+## 2.6 错误码引用
+
+### 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
+            └── del(TeamIssueRequest request)
+                └── 检查团队问题是否存在
+                    └── throw new TeamServiceException(TeamIssueExceptionEnum.TEAM_ISSUE_NOT_EXIST)
+```
+
+### 已知错误码
+| 错误码 | 错误消息 | 触发条件 |
+|--------|----------|----------|
+| 01001958001 | 团队问题不存在 | 删除的 issue-id 不存在或已被删除 |
+
+## 2.7 权限检查
+
+| 检查项 | 位置 | 说明 |
+|--------|------|------|
+| PermissionConstants | `TeamIssuePermissionConstants.DEL_TEAM_ISSUE` | Controller层 `@PostResource(requirePermissionCode = "DEL_TEAM_ISSUE")` |
+
+## 2.8 实现要点
+
+1. **必填参数**：`issue-id` 作为位置参数必须提供
+2. **Dry-run 默认开启**：不带 `--force` 时只显示提示信息，不调用删除 API，exit(0)
+3. **强制删除**：添加 `--force` 后调用 `/delete` API 执行实际删除
+4. **ID 类型处理**：后端使用 Long (BigInteger)，CLI 使用 string 避免精度丢失
+5. **权限要求**：需要 `DEL_TEAM_ISSUE` 权限
+6. **无 X-TENANT-ID Header**：CLI 不手动添加该 header，租户信息由后端从 JWT 中提取
+
+## 2.9 示例用法
+
+```bash
+# 预览删除（默认行为，不实际删除）
+barista liberica teams issues delete 123456789
+
+# 强制删除
+barista liberica teams issues delete 123456789 --force
+
+# 指定环境删除
+barista liberica teams issues delete 123456789 --env test --force
+
+# JSON 输出预览
+barista liberica teams issues delete 123456789 --json
+
+# JSON 输出并强制删除
+barista liberica teams issues delete 123456789 --force --json
+```

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

@@ -0,0 +1,167 @@
+# barista liberica teams issues get
+
+查询团队问题详情。
+
+## 2.1 命令元数据
+
+| 字段 | 值 |
+|------|-----|
+| 完整命令 | `barista liberica teams issues get <issue-id>` |
+| 功能描述 | 查询单个团队问题详情 |
+| 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
+            └── detail(@GetResource(path = "/detail"))
+                └── public ResponseData<TeamIssueResponse> detail(
+                        @RequestHeader("X-TENANT-ID") Long tenantId,
+                        @ParameterObject @Validated(BaseRequest.detail.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 detail)
+            └── tenantId: Long
+```
+
+**请求参数结构：**
+```
+GET /api/enterprise/team/issue/detail?teamIssueId={id}
+```
+
+### 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
+            ├── issueTitleTranslations: JSON
+            ├── issueType: String
+            ├── issueDesc: String
+            ├── issueDescTranslations: JSON
+            ├── solution: String
+            ├── solutionTranslations: JSON
+            ├── projectId: Long
+            ├── projectCode: String
+            ├── projectName: String
+            ├── reporterAccount: String
+            ├── reporterName: String
+            ├── reporterEmail: String
+            ├── reporterTenantId: Long
+            ├── reportDate: Date
+            ├── assignTo: JSON
+            ├── teamIssueStatus: String
+            ├── priority: String
+            ├── resolutionTime: Instant
+            ├── closeTime: Instant
+            ├── tags: JSON
+            ├── refId: String
+            ├── createTime: String
+            └── updateTime: String
+```
+
+## 2.3 CLI参数设计
+
+### 命令结构
+```
+barista liberica teams issues get <issue-id> [options]
+```
+
+### Usage
+```bash
+barista liberica teams issues get 123456789
+barista liberica teams issues get 123456789 --json
+```
+
+### 全局选项
+| 选项 | 类型 | 说明 |
+|------|------|------|
+| `--env` | string | 目标环境(dev\|test\|prod-cn\|prod-jp) |
+| `--tenant` | string | 租户代码 |
+| `--json` | boolean | JSON输出 |
+
+### 位置参数
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| issue-id | string | ✅ | 问题ID |
+
+### 命令选项
+| 选项 | 短选项 | 类型 | 必填 | 默认值 | 说明 | 对应DTO字段 |
+|------|--------|------|------|--------|------|-------------|
+| --json | -j | boolean | ⬜ | false | JSON格式输出 | - |
+
+## 2.4 字段映射表
+
+| CLI参数 | DTO字段 | 类型转换 | 验证规则 |
+|---------|---------|----------|----------|
+| issue-id (位置参数) | teamIssueId | string→Long | @NotNull |
+
+## 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
+            └── detail(TeamIssueRequest request)
+                └── 检查团队问题是否存在
+                    └── throw new TeamServiceException(TeamIssueExceptionEnum.TEAM_ISSUE_NOT_EXIST)
+```
+
+### 已知错误码
+| 错误码 | 错误消息 | 触发条件 |
+|--------|----------|----------|
+| 01001958001 | 团队问题不存在 | 查询的 issue-id 不存在或已被删除 |
+
+## 2.6 权限检查
+
+| 检查项 | 位置 | 说明 |
+|--------|------|------|
+| 注解 | `@GetResource(path = "/detail")` | 无 requiredPermission（详情查询无需权限码） |
+
+## 2.7 实现要点
+
+1. **必填参数**：`issue-id` 作为位置参数必须提供
+2. **API 调用方式**：通过 URL 查询参数传递 `teamIssueId`，如 `/detail?teamIssueId={id}`
+3. **ID 类型处理**：后端使用 Long (BigInteger)，CLI 使用 string 避免精度丢失
+4. **输出格式**：默认以键值对形式展示问题详情；`--json` 时输出完整响应 JSON
+5. **错误处理**：如果返回 `!response.success`，输出错误信息并 `process.exit(1)`
+
+## 2.8 示例用法
+
+```bash
+# 查询详情
+barista liberica teams issues get 123456789
+
+# JSON 输出
+barista liberica teams issues get 123456789 --json
+
+# 指定环境
+barista liberica teams issues get 123456789 --env test
+```

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
+```