# PM 看板管理

> **前置条件：** 先阅读 [`../../gitlink-shared/SKILL.md`](../../../gitlink-shared/SKILL.md) 了解认证、全局参数和安全规则。
> **注意**：PM 功能需要项目开启 PM 模块，并通过项目 ID 访问。

GitLink PM 看板功能提供项目任务的可视化管理，支持任务的拖拽、状态管理和团队协作。

## 命令

```bash
# 查看项目看板
gitlink-cli api GET /pm/dashboards --query 'project_id=123'

# 查看当前仓库的项目 ID
gitlink-cli repo +info --format json | jq '.data.project_id'

# 组合命令：自动获取项目 ID 并查看看板
PROJECT_ID=$(gitlink-cli repo +info --format json | jq -r '.data.project_id')
gitlink-cli api GET /pm/dashboards --query "project_id=$PROJECT_ID"
```

## 参数

| 参数 | 必填 | 说明 |
|------|------|------|
| `project_id` | **是** | 项目 ID（通过 `repo +info` 获取） |
| `--owner` | 否* | 仓库所有者（自动从 git remote 解析） |
| `--repo` | 否* | 仓库名称（自动从 git remote 解析） |
| `--format` | 否 | 输出格式: `json`/`table`/`yaml` |
| `--debug` | 否 | 启用调试输出 |

> *如果在 GitLink 仓库目录下执行，`--owner` 和 `--repo` 可自动推断。

## API

```
GET /api/pm/dashboards?project_id={project_id}
```

**响应示例：**

```json
{
  "ok": true,
  "data": {
    "dashboards": [
      {
        "id": 1,
        "name": "开发看板",
        "description": "主开发任务看板",
        "project_id": 123,
        "columns": [
          {
            "id": 1,
            "name": "待处理",
            "position": 1,
            "issue_count": 5
          },
          {
            "id": 2,
            "name": "进行中",
            "position": 2,
            "issue_count": 3
          },
          {
            "id": 3,
            "name": "已完成",
            "position": 3,
            "issue_count": 8
          }
        ],
        "issues": [
          {
            "id": 456,
            "subject": "实现用户认证功能",
            "status_id": 1,
            "priority_id": 2,
            "assigned_to": "developer1",
            "column_id": 2,
            "position": 1
          }
        ]
      }
    ],
    "total_count": 1
  }
}
```

## Workflow

1. **Get Project ID** using `repo +info`.
2. **Execute** `gitlink-cli api GET /pm/dashboards --query 'project_id=<id>'`.
3. **Display** kanban board information.

> [!NOTE]
> This is a **Read Operation** — no confirmation needed.

## Use Cases

- **任务可视化**：直观查看项目任务分布
- **进度跟踪**：实时监控任务进展情况
- **资源分配**：查看团队成员的工作负载
- **流程管理**：管理任务的流转和状态变更

## Kanban Board Structure

典型看板结构：

```
┌─────────────┬─────────────┬─────────────┐
│  待处理      │   进行中     │   已完成     │
│  [5 tasks]  │  [3 tasks]  │  [8 tasks]  │
├─────────────┼─────────────┼─────────────┤
│ Task 1      │ Task 6      │ Task 11     │
│ Task 2      │ Task 7      │ Task 12     │
│ Task 3      │ Task 8      │ Task 13     │
│ Task 4      │ Task 9      │ Task 14     │
│ Task 5      │ Task 10     │ Task 15     │
└─────────────┴─────────────┴─────────────┘
```

## Common Operations

看板常用操作：

### 查看任务分布
```bash
# 查看各列的任务数量
gitlink-cli api GET /pm/dashboards --query 'project_id=123' --format json | \
  jq '.data.dashboards[0].columns[] | {name: .name, count: .issue_count}'
```

### 查看特定任务
```bash
# 查看"进行中"的任务
gitlink-cli api GET /pm/dashboards --query 'project_id=123' --format json | \
  jq '.data.dashboards[0].issues[] | select(.column_id==2)'
```

### 统计工作负载
```bash
# 按人员统计任务数量
gitlink-cli api GET /pm/dashboards --query 'project_id=123' --format json | \
  jq '.data.dashboards[0].issues[] | group_by(.assigned_to) | map({assigned_to: .[0].assigned_to, count: length})'
```

## Task Management

任务管理最佳实践：

1. **列管理**：合理设置任务列（如：待处理、进行中、已完成）
2. **限制数量**：对"进行中"列设置 WIP 限制
3. **定期清理**：及时移动已完成任务到相应列
4. **优先级标记**：使用标签和优先级标识重要任务

## Analysis Examples

看板数据分析示例：

```bash
# 1. 获取项目 ID
PROJECT_ID=$(gitlink-cli repo +info --format json | jq -r '.data.project_id')

# 2. 查看完整看板数据
gitlink-cli api GET /pm/dashboards --query "project_id=$PROJECT_ID" --format json

# 3. 分析任务瓶颈（找出任务最多的列）
gitlink-cli api GET /pm/dashboards --query "project_id=$PROJECT_ID" --format json | \
  jq '.data.dashboards[0].columns | sort_by(.issue_count) | reverse | .[0]'

# 4. 计算完成率
gitlink-cli api GET /pm/dashboards --query "project_id=$PROJECT_ID" --format json | \
  jq '[.data.dashboards[0].columns[] | select(.name=="已完成")] | .[0].issue_count /
     [.data.dashboards[0].columns[].issue_count] | add * 100'
```

## Tips

- 看板数据可以帮助识别项目瓶颈
- 定期查看看板可以保持项目进度的可视化
- 结合 Issue 操作可以实现完整的任务管理流程
- 使用 JSON 格式输出便于自动化分析

## Integration with Other Features

与其他功能集成：

```bash
# 看板 + Issue 操作
# 1. 查看看板中的任务
gitlink-cli api GET /pm/dashboards --query 'project_id=123' --format json

# 2. 查看特定任务详情
gitlink-cli issue +view --issue 456

# 3. 更新任务状态
gitlink-cli issue +update --issue 456 --status_id 3
```

## Error Handling

常见错误及解决方案：

| 错误 | 原因 | 解决方案 |
|------|------|----------|
| `400` | PM 模块未开启 | 联系项目管理员开启 PM 模块 |
| `404` | 项目不存在 | 检查 project_id 是否正确 |
| `403` | 权限不足 | 确认有查看该项目的权限 |
| `404` | 看板不存在 | 该项目可能没有配置看板 |

## Prerequisites

使用 PM 功能的前置条件：

1. **PM 模块开启**：项目需要开启 PM 功能模块
2. **有效项目 ID**：需要正确的项目 ID
3. **访问权限**：需要该项目的访问权限
4. **看板配置**：项目需要有配置的看板

## Setup Workflow

PM 功能设置流程：

```bash
# 1. 检查项目是否开启 PM
gitlink-cli repo +info --format json | jq '.data.has_pm'

# 2. 获取项目 ID
gitlink-cli repo +info --format json | jq '.data.project_id'

# 3. 查看看板配置
gitlink-cli api GET /pm/dashboards --query 'project_id=123'

# 4. 如需配置看板，通过 GitLink 网页端操作
# https://www.gitlink.org.cn/{owner}/{repo}/project_modules
```

## Team Collaboration

团队协作建议：

1. **定期更新**：团队成员定期更新任务状态
2. **明确规范**：制定看板使用规范和列定义
3. **WIP 限制**：设置进行中任务的数量限制
4. **定期回顾**：定期回顾看板数据，优化流程

## References

- [pm-sprint](pm-sprint.md) — Sprint 管理
- [pm-report](pm-report.md) — 周报生成
- [gitlink-pm](../SKILL.md) — 项目管理总览
- [gitlink-shared](../../gitlink-shared/SKILL.md) — 认证和全局参数
- [repo +info](../../gitlink-repo/references/repo-info.md) — 获取仓库信息
