Metadata-Version: 2.4
Name: zt-devops-cli
Version: 0.2.5
Summary: DevOps 平台迭代管理 CLI
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: playwright>=1.40.0
Requires-Dist: requests>=2.31.0
Requires-Dist: click>=8.1.0
Requires-Dist: pyyaml>=6.0

# DevOps CLI

蓝鲸 DevOps（ZTN）平台迭代、任务、缺陷等能力的命令行工具。

## 打包

```bash
uv pip install --upgrade build twine
uv build
uv publish
```

## 安装

**源码安装**

```bash
pip install -e .
```

**pip / pipx 安装**

```bash
pipx install zt-devops-cli
```

## 使用

### 全局选项

根命令 `zt-devops-cli` 支持：

| 选项 | 说明 |
|------|------|
| `-p` / `--project` | 默认项目 ID；**仅对子命令里 `-p` 为可选的命令**生效，解析顺序为「子命令 `-p` → 根命令 `-p` → `config.yaml` 的 `default_project`」 |
| `-o` / `--output` | `json`（默认）或 `human`；列表类在 `human` 下为表格，部分写操作在 `human` 下仅输出简短成功信息 |

**注意（Click 解析）**：若子命令将 `-p` / `--project` 标为必填（如 `bug list`、`task list`、`bug create`、缺陷流转等），则必须在**该子命令后**再写一遍 `-p`，根命令上的 `-p` 不会自动填入子命令参数。

示例（`sprint list` 的 `-p` 可选，可用根级 `-p`）：

```bash
zt-devops-cli -o human -p k64352 sprint list
```

示例（`bug list` 的 `-p` 为子命令必填，须写在 `bug list` 之后）：

```bash
zt-devops-cli -o human bug list -p b9f157 --num 1 --size 20
```

### 登录

首次或 cookie 失效时会走浏览器登录流程；成功后将 cookie 写入本地缓存。

```bash
zt-devops-cli login
```

需要弹出窗口手动登录时（无环境变量自动填表时）：

```bash
zt-devops-cli login --headed
```

无头自动登录依赖环境变量 `ZT_SSO_USERNAME`、`ZT_SSO_PASSWORD`（见 `auth` 模块说明）。

### 项目管理

```bash
zt-devops-cli project list
```

### ZTeam 项目

```bash
zt-devops-cli zteam-project list --project f39507
```

### 迭代管理

**迭代列表**

```bash
zt-devops-cli sprint list --project k64352
# 或与根命令 -p 组合（本子命令 -p 可选）
zt-devops-cli -p k64352 sprint list
```

**迭代提测列表**

```bash
zt-devops-cli sprint test-list --project b9f157 \
  --search "BSC_V26.701.01" \
  --num 1 \
  --size 10
```

可选筛选：`--result`、`--create-user`、`--create-time`、`--principal`、`--obj-id`（均可重复传入）。

**创建迭代**

```bash
zt-devops-cli sprint create --project k64352 \
  --title "迭代名称" \
  --start-date 2026-04-04 \
  --end-date 2026-05-30 \
  --purpose "迭代目标"
```

日期可用简写：`-s` / `--start-date`、`-e` / `--end-date`。可选：`--test-start`、`--test-end`。

**启用 / 删除 / 完成迭代**

```bash
zt-devops-cli sprint start --project k64352 -i <sprint-id>
zt-devops-cli sprint delete --project k64352 -i <sprint-id>
zt-devops-cli sprint done --project k64352 -i <sprint-id>
```

`-i` 即 `--sprint-id`。`delete` / `done` 会交互确认。

### 任务管理

**查询任务列表（TASK）**

子命令上 `-p` **必填**。另须 `--start-date`、`--end-date`。可选：`--creator`、`--num`、`--size`、`--remember` / `--no-remember`（默认 `--no-remember`）。

```bash
zt-devops-cli task list -p f39507 \
  --start-date 2026-04-01 \
  --end-date 2026-04-30 \
  --creator zt07905
```

**创建任务（TASK）**

子命令上 `-p` **必填**。另须 `-t` / `--title`、`--owner`、`--estimate-start`、`--estimate-end`、`--zteam-project-id`（平台项目 ID 来自 `project list`，ZTeam 项目 ID 来自 `zteam-project list`）。

```bash
zt-devops-cli task create \
  -p "<project-id>" \
  --title "<任务标题>" \
  --owner zt07905 \
  --estimate-start 2026-04-01 \
  --estimate-end 2026-04-30 \
  --zteam-project-id "<zteam-project-id>"
```

可选：`--model-type-id`、`--priority`、`--editor-type`、`--desc`、`--parent-id`、`--demand-classify`、`--origin-hours`、`--remain-hours`；扩展字段使用 `--field fieldId=value`（可多次）。

### 缺陷管理

**查询缺陷列表（BUG）**

子命令上 `-p` **必填**。与页面表格筛选相近。常用可选：`--num`、`--size`、`--remember` / `--no-remember`（默认 `--no-remember`）、`--operator`（逗号分隔多账号）、`--zteam-project`、`--owner-field` / `--owner`、`--state`（状态 ID，可先执行 `bug get-states`）、`--creator`、`--create-date` 或 `--create-start` + `--create-end`（二者须同时出现）。

```bash
zt-devops-cli bug list -p b9f157 \
  --num 1 \
  --size 20
```

**查询缺陷「状态」可选项**

```bash
zt-devops-cli bug get-states -p b9f157
```

默认 `--all`；若与页面不一致可尝试 `--no-all`。

**查询缺陷「发现阶段」可选项**

```bash
zt-devops-cli bug get-discovery-phases -p b9f157
```

默认 `--no-all`（与缺陷表 twBug 一致）。模板不同时可传 `--field-id`。若与页面不一致可试 `--all`。

**查询缺陷「解决方法」可选项**

```bash
zt-devops-cli bug get-solution-methods -p b9f157
```

默认 `--no-all`。可选 `--field-id`。

**查询缺陷「类型」可选项**

```bash
zt-devops-cli bug get-types -p b9f157
```

默认 `--no-all`。可选 `--field-id`。

**创建缺陷（BUG）**

对应 `POST .../issue/{project}`。`--owner` 同时写入经办人与缺陷责任人；迭代、ZTeam、严重程度、类型、发现阶段、解决方法等使用代码内固定 `fieldId`（与团队抓包一致）。若你们项目字段不同，需改源码中的 `instance_values` 映射。

| 选项 | 说明 |
|------|------|
| `-p` / `--project` | 项目 ID（子命令必填） |
| `--zteam-project-id` | ZTeam 项目 ID |
| `--sprint-id` | 关联迭代 ID；可不关联时传空字符串 `""` |
| `-t` / `--title` | 标题 |
| `--severity` / `--type` / `--discovery-phase` | 与表单选项的 **value** 一致（非中文展示名） |
| `--solution-method` | 可选；解决方法字段的 value |
| `--owner` | 账号 |
| `--priority` | 默认 `CENTRAL` |
| `--desc` / `--desc-editor-type` | 描述 HTML 与编辑器类型，默认带四段模板 |
| `--parent-id`、`--model-type-id`、`--demand-classify` | 可选或保持默认 |

```bash
zt-devops-cli bug create -p b9f157 \
  --zteam-project-id 15678224 \
  --sprint-id 3129a9cd7315457eb2963bfe19919e72 \
  -t "缺陷标题示例" \
  --owner zt07905 \
  --severity 9Clfj3I8fR \
  --type bgEHPFOjFt \
  --discovery-phase vENjmMhXMC
```

**缺陷工作流（接受 / 已解决 / 已验证 / 关闭 / 重新打开 / 拒绝）**

均调用 `POST .../issue_direction/{project}/next`。各动作对应的 `nextNodeId` 写死在 `api.BUG_DIRECTION_NEXT_NODE_IDS`（与某项目浏览器抓包一致）；若你们项目工作流节点不同，需改源码中该表。

子命令参数（Click 下均为**该子命令**上的必填项）：

- **`-i` / `--bug-id`**：缺陷 ID。
- **`-p` / `--project`**：项目 ID（须在子命令上显式传入，勿依赖仅写在根命令上的 `-p`）。
- **`--operator`**：经办人账号，英文逗号分隔多个。
- **`--comment`**：可选，流转备注（富文本 HTML，例如 `'<p>说明</p>'`）。

```bash
zt-devops-cli bug accept -p b9f157 -i <bug-id> --operator zt07905 --comment '<p>说明</p>'
zt-devops-cli bug resolve -p b9f157 -i <bug-id> --operator zt07905
zt-devops-cli bug verify -p b9f157 -i <bug-id> --operator zt07905,user02
zt-devops-cli bug close -p b9f157 -i <bug-id> --operator zt07905
zt-devops-cli bug reopen -p b9f157 -i <bug-id> --operator zt07905
zt-devops-cli bug reject -p b9f157 -i <bug-id> --operator zt07905
```

在 `~/.zt-devops-cli/config.yaml` 中可写默认项目（便于省略**允许默认合并**的子命令上的 `-p`）：

```yaml
default_project: b9f157
```

**删除缺陷**

```bash
zt-devops-cli bug delete -p b9f157 -i <bug-id>
zt-devops-cli bug delete -p b9f157 -i <bug-id> -y
```

`-y` / `--yes` 跳过交互确认。

### 需求 / 工作项

**查询自定义字段下拉可选项**

子命令上 `-p`、`--field-id`、`--classify` 均为必填。用于按字段与工作项类型拉取与页面 `issue_field_value/.../option/{fieldId}` 一致的选项列表（`classify` 与页面一致，如 `BUG`、`TASK`、`STORY`）。

```bash
zt-devops-cli issue field-options -p b9f157 \
  --field-id <fieldId> \
  --classify BUG
```

`--all` / `--no-all`：是否对应页面 `all` 参数（默认 `--no-all`）。

**需求状态流转（issue direction）**

基于 `POST .../issue_direction/{project}/next`，已内置以下动作：

- `issue tested`：需求已提测
- `issue testing`：需求测试中
- `issue pending-acceptance`：需求待验收
- `issue pending-release`：需求待发布
- `issue delivered`：需求已交付

公共参数：

- `-p` / `--project`：项目 ID（子命令必填）
- `-i` / `--issue-id`：需求 ID
- `--operator`：经办人账号，多个用英文逗号分隔
- `--comment`：可选备注（支持 HTML）
- `--field fieldId=value`：可选流转字段，可重复传入

```bash
zt-devops-cli issue tested -p f39507 -i <issue-id> --operator SPACE_ADMIN
zt-devops-cli issue testing -p f39507 -i <issue-id> --operator SPACE_ADMIN
zt-devops-cli issue pending-acceptance -p f39507 -i <issue-id> --operator SPACE_ADMIN
zt-devops-cli issue pending-release -p f39507 -i <issue-id> --operator SPACE_ADMIN
zt-devops-cli issue delivered -p f39507 -i <issue-id> --operator SPACE_ADMIN
```

**任务状态流转（task direction）**

已内置：

- `task processing`：任务处理中
- `task done`：任务已完成

```bash
zt-devops-cli task processing -p f39507 -i <task-id> --operator zt07905 \
  --field 684f26d36cd747f68dde32104a701956=09268ad9302844ab8916069d7bb380dd

zt-devops-cli task done -p f39507 -i <task-id> --operator zt07905
```

## 配置

- Cookie 缓存：`~/.zt-devops-cli/cookies.json`
- 配置文件：`~/.zt-devops-cli/config.yaml`（常用键：`default_project`，解析时等同「根命令 `-p`」参与合并；另支持 `browser_channel`，默认 `chromium`）
