@newpeak/barista-cli 0.1.8 → 0.1.10

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

@@ -0,0 +1,212 @@
+# barista liberica teams issues create
+
+创建团队问题。
+
+## 2.1 命令元数据
+
+| 字段 | 值 |
+|------|-----|
+| 完整命令 | `barista liberica teams issues create` |
+| 功能描述 | 创建新的团队问题（Bug、需求或问题） |
+| 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
+            └── add(@PostResource(path = "/add", requiredPermission = true, requirePermissionCode = TeamIssuePermissionConstants.ADD_TEAM_ISSUE))
+                └── public ResponseData<TeamIssueResponse> add(
+                        @RequestHeader("X-TENANT-ID") Long tenantId,
+                        @RequestBody @Validated(BaseRequest.add.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
+            ├── 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)
+            ├── reporterTenantId: Long
+            ├── 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
+            └── createTime: String
+```
+
+## 2.3 CLI参数设计
+
+### 命令结构
+```
+barista liberica teams issues create [options]
+```
+
+### Usage
+```bash
+barista liberica teams issues create --title "示例" --desc "描述" --type BUG --project-id 1 --project-code "P1" --project-name "项目"
+```
+
+### 全局选项
+| 选项 | 类型 | 说明 |
+|------|------|------|
+| `--env` | string | 目标环境(dev\|test\|prod-cn\|prod-jp) |
+| `--tenant` | string | 租户代码 |
+| `--dry-run` | boolean | 预览模式（不实际调用API） |
+| `--json` | boolean | JSON输出 |
+
+### 命令选项
+| 选项 | 短选项 | 类型 | 必填 | 默认值 | 说明 | 对应DTO字段 |
+|------|--------|------|------|--------|------|-------------|
+| --title | -t | string | ✅ | - | 问题标题 | issueTitle |
+| --desc | -d | string | ✅ | - | 问题描述 | issueDesc |
+| --type | -y | string | ✅ | - | 问题类型（BUG/REQUIREMENT/QUESTION） | issueType |
+| --project-id | — | string | ✅ | - | 所属项目ID | projectId |
+| --project-code | — | string | ✅ | - | 所属项目代号 | projectCode |
+| --project-name | — | string | ✅ | - | 所属项目名称 | projectName |
+| --priority | -p | string | ⬜ | MEDIUM | 优先级（LOW/MEDIUM/HIGH/URGENT） | priority |
+| --status | -s | string | ⬜ | OPEN | 问题状态（OPEN/IN_PROGRESS/RESOLVED/CLOSED） | teamIssueStatus |
+| --assign-to | -a | string | ⬜ | - | 负责人ID列表，逗号分隔 | assignTo |
+| --tags | — | string | ⬜ | - | 标签列表，逗号分隔 | tags |
+| --json | -j | boolean | ⬜ | false | JSON格式输出 | - |
+
+## 2.4 字段映射表
+
+| CLI参数 | DTO字段 | 类型转换 | 验证规则 |
+|---------|---------|----------|----------|
+| --title / -t | issueTitle | 直接传递 | @NotBlank, max=500 |
+| --desc / -d | issueDesc | 直接传递 | @NotNull |
+| --type / -y | issueType | 直接传递 | BUG, REQUIREMENT, QUESTION |
+| --project-id | projectId | string→Long | @NotNull |
+| --project-code | projectCode | 直接传递 | @NotBlank, max=50 |
+| --project-name | projectName | 直接传递 | @NotBlank, max=200 |
+| --priority / -p | priority | 直接传递 | LOW, MEDIUM, HIGH, URGENT |
+| --status / -s | teamIssueStatus | 直接传递 | OPEN, IN_PROGRESS, RESOLVED, CLOSED |
+| --assign-to / -a | assignTo | string→JSON数组 | @NotNull，逗号分隔用户ID |
+| --tags | tags | string→JSON数组 | 逗号分隔标签 |
+
+**自动填充字段（不通过CLI参数）：**
+| 字段 | 来源 |
+|------|------|
+| tenantId | 后端从 X-TENANT-ID header 注入 |
+| reporterAccount | 当前认证用户上下文自动填充 |
+| reporterName | 当前认证用户上下文自动填充 |
+| reporterEmail | 当前认证用户上下文自动填充 |
+| reporterTenantId | 当前认证用户上下文自动填充 |
+| reportDate | 自动填充当前系统日期 |
+| teamIssueCode | 为空时后端自动生成编码 |
+
+## 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 | 团队问题不存在 | copy/edit 时引用的原问题不存在 |
+
+## 2.6 权限检查
+
+| 检查项 | 位置 | 说明 |
+|--------|------|------|
+| PermissionConstants | `TeamIssuePermissionConstants.ADD_TEAM_ISSUE` | Controller层 `@PostResource(requirePermissionCode = "ADD_TEAM_ISSUE")` |
+
+## 2.7 实现要点
+
+1. **必填字段**：`--title`、`--desc`、`--type`、`--project-id`、`--project-code`、`--project-name` 必须提供
+2. **默认值**：`--priority` 默认 `MEDIUM`，`--status` 默认 `OPEN`，`--reportDate` 自动填充当前日期
+3. **Reporter 自动填充**：`reporterAccount`、`reporterName`、`reporterEmail` 从当前认证用户上下文获取
+4. **assignTo / tags 序列化**：逗号分隔的字符串需要在 CLI 内部转换为 JSON 数组格式再发送到后端
+5. **Dry-run 支持**：使用 `--dry-run` 时构造请求体但不发送，显示预览信息
+6. **tenantId 来源**：来自 X-TENANT-ID header，不通过请求体传递
+7. **无 X-TENANT-ID Header**：CLI 不手动添加该 header，租户信息由后端从 JWT 中提取
+
+## 2.8 示例用法
+
+```bash
+# 最小参数创建
+barista liberica teams issues create \
+  --title "登录页面样式异常" \
+  --desc "在移动端浏览器中，登录按钮被遮挡" \
+  --type BUG \
+  --project-id 123456789 \
+  --project-code "ERP" \
+  --project-name "ERP系统"
+
+# 完整参数创建
+barista liberica teams issues create \
+  --title "新增报表导出功能" \
+  --desc "支持将销售报表导出为 Excel 格式" \
+  --type REQUIREMENT \
+  --project-id 123456789 \
+  --project-code "ERP" \
+  --project-name "ERP系统" \
+  --priority HIGH \
+  --status OPEN \
+  --assign-to "111,222,333" \
+  --tags "销售,报表,高优先级"
+
+# Dry-run 预览
+barista liberica teams issues create \
+  --title "测试问题" \
+  --desc "测试描述" \
+  --type QUESTION \
+  --project-id 123456789 \
+  --project-code "TEST" \
+  --project-name "测试项目" \
+  --dry-run
+
+# JSON 输出
+barista liberica teams issues create \
+  --title "测试问题" \
+  --desc "测试描述" \
+  --type BUG \
+  --project-id 123456789 \
+  --project-code "TEST" \
+  --project-name "测试项目" \
+  --json
+```

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