diff --git a/doc/changes/pm-shortcut.md b/doc/changes/pm-shortcut.md new file mode 100644 index 0000000..4d0a747 --- /dev/null +++ b/doc/changes/pm-shortcut.md @@ -0,0 +1,18 @@ +# PM (项目管理) shortcut + +新增 `pm` Shortcut 组,封装 GitLink 项目管理相关只读接口,补齐仓库协作元数据的命令化访问: + +- `pm +dashboards` — 查看项目仪表盘数据 +- `pm +sprints` — 查看 Sprint 任务列表 +- `pm +weekly` — 查看周报任务 +- `pm +tags` — 查看项目 Issue 标签 +- `pm +pipelines` — 查看项目 CI/CD 流水线列表 +- `pm +runs` — 查看项目 Action 运行记录 + +实现要点: + +- 全部为只读(GET)命令,通过 Raw API 访问项目管理后端,统一 `owner/repo` 自动解析与 `--format json|table|yaml` 输出。 +- 面向「项目经理 / 科研课题负责人」视角:一条命令拿到仪表盘、Sprint、周报、流水线运行等聚合视图,无需在 Web 上多次跳转。 +- 与 `gitlink-pm` Skill 配套,供 AI Agent 做项目健康巡检与进度跟踪。 + +背景:项目管理数据此前散落在多个 Web 页面,无命令行入口。`pm` 组将其收敛为 6 条命令,是子任务三「项目一键初始化 / 进度跟踪」与子任务四「科研进度智能跟踪与预警」的基础数据层。关联 PR #12。 diff --git a/doc/commands/pm.md b/doc/commands/pm.md new file mode 100644 index 0000000..009726a --- /dev/null +++ b/doc/commands/pm.md @@ -0,0 +1,49 @@ +# pm — 项目管理命令 + +> 关联 Issue: #12 | PR: #9 + +## 概述 + +pm 模块提供 GitLink 项目管理相关的命令,包括仪表盘、Sprint 任务、周报、标签、流水线和 Action 运行记录的查看。 + +## 命令列表 + +### pm +dashboards +- **用途**: 查看项目仪表盘数据 +- **API**: GET /pm/dashboards?project_id=\ +- **参数**: --project (必填) 项目 ID +- **示例**: `gitlink-cli pm +dashboards --project 123` + +### pm +sprints +- **用途**: 查看 Sprint 任务列表 +- **API**: GET /pm/sprint_issues?project_id=\ +- **参数**: --project (必填) 项目 ID +- **示例**: `gitlink-cli pm +sprints --project 123` + +### pm +weekly +- **用途**: 查看周报任务 +- **API**: GET /pm/weekly_issues?project_id=\ +- **参数**: --project (必填) 项目 ID +- **示例**: `gitlink-cli pm +weekly --project 123` + +### pm +tags +- **用途**: 查看项目 Issue 标签 +- **API**: GET /pm/issue_tags?project_id=\ +- **参数**: --project (必填) 项目 ID +- **示例**: `gitlink-cli pm +tags --project 123` + +### pm +pipelines +- **用途**: 查看项目 CI/CD 流水线列表 +- **API**: GET /pm/pipelines?project_id=\ +- **参数**: --project (必填) 项目 ID +- **示例**: `gitlink-cli pm +pipelines --project 123` + +### pm +runs +- **用途**: 查看项目 Action 运行记录 +- **API**: GET /pm/action_runs?project_id=\ +- **参数**: --project (必填) 项目 ID +- **示例**: `gitlink-cli pm +runs --project 123` + +## 向后兼容性 + +无破坏性变更。所有命令通过 pm 域组 + 前缀添加。 diff --git a/shortcuts/pm/pm.go b/shortcuts/pm/pm.go new file mode 100644 index 0000000..991a4e4 --- /dev/null +++ b/shortcuts/pm/pm.go @@ -0,0 +1,137 @@ +package pm + +import ( + "net/url" + + "github.com/gitlink-org/gitlink-cli/shortcuts/common" +) + +// Shortcuts returns project management shortcuts for GitLink. +// +// The pm domain provides commands for viewing dashboards, sprints, +// weekly issues, tags, pipelines, and action runs associated with +// a project. +func Shortcuts() []*common.Shortcut { + return []*common.Shortcut{ + { + Name: "dashboards", + Description: "查看项目仪表盘数据", + Flags: []common.Flag{ + {Name: "project", Usage: "项目 ID", Required: true}, + }, + Run: func(ctx *common.RuntimeContext) error { + project, err := ctx.RequireArg("project") + if err != nil { + return err + } + q := url.Values{} + q.Set("project_id", project) + env, err := ctx.CallAPIWithQuery("GET", "/pm/dashboards", q) + if err != nil { + return err + } + return ctx.Output(env) + }, + }, + { + Name: "sprints", + Description: "查看 Sprint 任务列表", + Flags: []common.Flag{ + {Name: "project", Usage: "项目 ID", Required: true}, + }, + Run: func(ctx *common.RuntimeContext) error { + project, err := ctx.RequireArg("project") + if err != nil { + return err + } + q := url.Values{} + q.Set("project_id", project) + env, err := ctx.CallAPIWithQuery("GET", "/pm/sprint_issues", q) + if err != nil { + return err + } + return ctx.Output(env) + }, + }, + { + Name: "weekly", + Description: "查看周报任务", + Flags: []common.Flag{ + {Name: "project", Usage: "项目 ID", Required: true}, + }, + Run: func(ctx *common.RuntimeContext) error { + project, err := ctx.RequireArg("project") + if err != nil { + return err + } + q := url.Values{} + q.Set("project_id", project) + env, err := ctx.CallAPIWithQuery("GET", "/pm/weekly_issues", q) + if err != nil { + return err + } + return ctx.Output(env) + }, + }, + { + Name: "tags", + Description: "查看项目 Issue 标签", + Flags: []common.Flag{ + {Name: "project", Usage: "项目 ID", Required: true}, + }, + Run: func(ctx *common.RuntimeContext) error { + project, err := ctx.RequireArg("project") + if err != nil { + return err + } + q := url.Values{} + q.Set("project_id", project) + env, err := ctx.CallAPIWithQuery("GET", "/pm/issue_tags", q) + if err != nil { + return err + } + return ctx.Output(env) + }, + }, + { + Name: "pipelines", + Description: "查看项目 CI/CD 流水线列表", + Flags: []common.Flag{ + {Name: "project", Usage: "项目 ID", Required: true}, + }, + Run: func(ctx *common.RuntimeContext) error { + project, err := ctx.RequireArg("project") + if err != nil { + return err + } + q := url.Values{} + q.Set("project_id", project) + env, err := ctx.CallAPIWithQuery("GET", "/pm/pipelines", q) + if err != nil { + return err + } + return ctx.Output(env) + }, + }, + { + Name: "runs", + Description: "查看项目 Action 运行记录", + Flags: []common.Flag{ + {Name: "project", Usage: "项目 ID", Required: true}, + }, + Run: func(ctx *common.RuntimeContext) error { + project, err := ctx.RequireArg("project") + if err != nil { + return err + } + q := url.Values{} + q.Set("project_id", project) + env, err := ctx.CallAPIWithQuery("GET", "/pm/action_runs", q) + if err != nil { + return err + } + return ctx.Output(env) + }, + }, + } +} diff --git a/shortcuts/pm/pm_test.go b/shortcuts/pm/pm_test.go new file mode 100644 index 0000000..781d09f --- /dev/null +++ b/shortcuts/pm/pm_test.go @@ -0,0 +1,220 @@ +package pm + +import ( + "encoding/json" + "net/http" + "net/http/httptest" + "strings" + "testing" + + "github.com/gitlink-org/gitlink-cli/internal/client" + "github.com/gitlink-org/gitlink-cli/shortcuts/common" +) + +func TestPmDashboards(t *testing.T) { + tests := []struct { + name string + mockStatus int + mockBody string + wantErr bool + errContains string + }{ + {"正常返回", 200, `{"dashboards": []}`, false, ""}, + {"API 404", 404, `{"error": "not found"}`, true, "404"}, + {"返回 HTML", 200, `Login`, true, "HTML"}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if r.Method != "GET" { + t.Errorf("expected GET, got %s", r.Method) + } + if !strings.Contains(r.URL.Path, "/pm/dashboards") { + t.Errorf("expected path containing /pm/dashboards, got %s", r.URL.Path) + } + if got := r.URL.Query().Get("project_id"); got != "123" { + t.Errorf("expected project_id=123, got %s", got) + } + w.WriteHeader(tt.mockStatus) + w.Write([]byte(tt.mockBody)) + })) + defer server.Close() + + shortcut := findPmShortcut(t, "dashboards") + ctx := &common.RuntimeContext{ + Client: &client.Client{HTTP: server.Client(), BaseURL: server.URL}, + Owner: "test", Repo: "test", Format: "json", + Args: map[string]string{"project": "123"}, + } + err := shortcut.Run(ctx) + + if tt.wantErr && err == nil { + t.Fatal("期望错误但为 nil") + } + if !tt.wantErr && err != nil { + t.Fatalf("不期望错误: %v", err) + } + if tt.wantErr && tt.errContains != "" && err != nil { + if !strings.Contains(err.Error(), tt.errContains) { + t.Errorf("错误应包含 %q: %s", tt.errContains, err.Error()) + } + } + }) + } +} + +func TestPmSprints(t *testing.T) { + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if r.Method != "GET" { + t.Errorf("expected GET, got %s", r.Method) + } + if !strings.Contains(r.URL.Path, "/pm/sprint_issues") { + t.Errorf("expected path containing /pm/sprint_issues, got %s", r.URL.Path) + } + w.WriteHeader(200) + w.Write([]byte(`{"sprint_issues": []}`)) + })) + defer server.Close() + + shortcut := findPmShortcut(t, "sprints") + ctx := &common.RuntimeContext{ + Client: &client.Client{HTTP: server.Client(), BaseURL: server.URL}, + Owner: "test", Repo: "test", Format: "json", + Args: map[string]string{"project": "456"}, + } + if err := shortcut.Run(ctx); err != nil { + t.Fatalf("sprints shortcut failed: %v", err) + } +} + +func TestPmWeekly(t *testing.T) { + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if !strings.Contains(r.URL.Path, "/pm/weekly_issues") { + t.Errorf("expected path containing /pm/weekly_issues, got %s", r.URL.Path) + } + w.WriteHeader(200) + w.Write([]byte(`{"weekly_issues": []}`)) + })) + defer server.Close() + + shortcut := findPmShortcut(t, "weekly") + ctx := &common.RuntimeContext{ + Client: &client.Client{HTTP: server.Client(), BaseURL: server.URL}, + Owner: "test", Repo: "test", Format: "json", + Args: map[string]string{"project": "789"}, + } + if err := shortcut.Run(ctx); err != nil { + t.Fatalf("weekly shortcut failed: %v", err) + } +} + +func TestPmTags(t *testing.T) { + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if !strings.Contains(r.URL.Path, "/pm/issue_tags") { + t.Errorf("expected path containing /pm/issue_tags, got %s", r.URL.Path) + } + w.WriteHeader(200) + w.Write([]byte(`{"issue_tags": []}`)) + })) + defer server.Close() + + shortcut := findPmShortcut(t, "tags") + ctx := &common.RuntimeContext{ + Client: &client.Client{HTTP: server.Client(), BaseURL: server.URL}, + Owner: "test", Repo: "test", Format: "json", + Args: map[string]string{"project": "100"}, + } + if err := shortcut.Run(ctx); err != nil { + t.Fatalf("tags shortcut failed: %v", err) + } +} + +func TestPmPipelines(t *testing.T) { + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if !strings.Contains(r.URL.Path, "/pm/pipelines") { + t.Errorf("expected path containing /pm/pipelines, got %s", r.URL.Path) + } + w.WriteHeader(200) + w.Write([]byte(`{"pipelines": []}`)) + })) + defer server.Close() + + shortcut := findPmShortcut(t, "pipelines") + ctx := &common.RuntimeContext{ + Client: &client.Client{HTTP: server.Client(), BaseURL: server.URL}, + Owner: "test", Repo: "test", Format: "json", + Args: map[string]string{"project": "200"}, + } + if err := shortcut.Run(ctx); err != nil { + t.Fatalf("pipelines shortcut failed: %v", err) + } +} + +func TestPmRuns(t *testing.T) { + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if !strings.Contains(r.URL.Path, "/pm/action_runs") { + t.Errorf("expected path containing /pm/action_runs, got %s", r.URL.Path) + } + w.WriteHeader(200) + w.Write([]byte(`{"action_runs": []}`)) + })) + defer server.Close() + + shortcut := findPmShortcut(t, "runs") + ctx := &common.RuntimeContext{ + Client: &client.Client{HTTP: server.Client(), BaseURL: server.URL}, + Owner: "test", Repo: "test", Format: "json", + Args: map[string]string{"project": "300"}, + } + if err := shortcut.Run(ctx); err != nil { + t.Fatalf("runs shortcut failed: %v", err) + } +} + +func TestPmMissingProject(t *testing.T) { + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + t.Fatal("should not call API when --project is missing") + })) + defer server.Close() + + shortcut := findPmShortcut(t, "dashboards") + ctx := &common.RuntimeContext{ + Client: &client.Client{HTTP: server.Client(), BaseURL: server.URL}, + Owner: "test", Repo: "test", Format: "json", + Args: map[string]string{}, + } + err := shortcut.Run(ctx) + if err == nil { + t.Fatal("expected error when --project is missing") + } +} + +func findPmShortcut(t *testing.T, name string) *common.Shortcut { + t.Helper() + for _, shortcut := range Shortcuts() { + if shortcut.Name == name { + return shortcut + } + } + t.Fatalf("shortcut %q not found", name) + return nil +} + +func assertPmRequest(t *testing.T, r *http.Request, method, pathPrefix string) { + t.Helper() + if r.Method != method { + t.Fatalf("got method %s, want %s", r.Method, method) + } + if !strings.HasPrefix(r.URL.Path, pathPrefix) { + t.Fatalf("got path %s, want prefix %s", r.URL.Path, pathPrefix) + } +} + +func decodePmJSON(t *testing.T, r *http.Request) map[string]interface{} { + t.Helper() + var payload map[string]interface{} + if err := json.NewDecoder(r.Body).Decode(&payload); err != nil { + t.Fatalf("failed to decode request body: %v", err) + } + return payload +} diff --git a/shortcuts/register.go b/shortcuts/register.go index 1fedc7e..0868fd8 100644 --- a/shortcuts/register.go +++ b/shortcuts/register.go @@ -18,6 +18,7 @@ import ( "github.com/gitlink-org/gitlink-cli/shortcuts/milestone" "github.com/gitlink-org/gitlink-cli/shortcuts/org" "github.com/gitlink-org/gitlink-cli/shortcuts/pipeline" + "github.com/gitlink-org/gitlink-cli/shortcuts/pm" "github.com/gitlink-org/gitlink-cli/shortcuts/pr" "github.com/gitlink-org/gitlink-cli/shortcuts/profile" "github.com/gitlink-org/gitlink-cli/shortcuts/release" @@ -43,6 +44,7 @@ func RegisterAll(root *cobra.Command, translators ...*i18n.Translator) { "member": member.Shortcuts(), "milestone": milestone.Shortcuts(), "pipeline": pipeline.Shortcuts(), + "pm": pm.Shortcuts(), "pr": pr.Shortcuts(tr), "profile": profile.Shortcuts(tr), "release": release.Shortcuts(tr), @@ -68,6 +70,7 @@ func RegisterAll(root *cobra.Command, translators ...*i18n.Translator) { "member": "Repository member operations", "milestone": "Milestone operations", "pipeline": "Pipeline operations", + "pm": "Project management operations", "pr": tr.T("cmd.pr.short"), "profile": tr.T("cmd.profile.short"), "release": tr.T("cmd.release.short"),