From 1527f45dc162e23fe0bcc21110a928d2530e72fc Mon Sep 17 00:00:00 2001 From: wyxfzgg <3132758001@qq.com> Date: Thu, 9 Jul 2026 21:24:06 +0800 Subject: [PATCH] feat(shortcut): add notification command group (list/read/read-all/watch) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增 notification 命令组，封装 GitLink 通知 OpenAPI： - notification +list 列出通知（--all/--participating/分页） - notification +read 标记单条已读 (-i/--id) - notification +read-all 全部标记已读 - notification +watch 关注/取消关注仓库通知 (-o/-r, --unwatch) 含单元测试（7 测试，覆盖 method/path/query）、帮助文档、变更说明。 来源：GitLink 大赛 2026 子赛题一。 --- doc/changes/notification-shortcut.md | 17 ++ doc/commands/notification.md | 41 +++++ shortcuts/notification/notification.go | 97 ++++++++++ shortcuts/notification/notification_test.go | 189 ++++++++++++++++++++ shortcuts/register.go | 3 + 5 files changed, 347 insertions(+) create mode 100644 doc/changes/notification-shortcut.md create mode 100644 doc/commands/notification.md create mode 100644 shortcuts/notification/notification.go create mode 100644 shortcuts/notification/notification_test.go diff --git a/doc/changes/notification-shortcut.md b/doc/changes/notification-shortcut.md new file mode 100644 index 0000000..424424c --- /dev/null +++ b/doc/changes/notification-shortcut.md @@ -0,0 +1,17 @@ +# Notification shortcut + +新增 `notification` Shortcut 组，封装 GitLink 通知相关 OpenAPI： + +- `notification +list` — 列出通知（`--all` 含已读、`--participating` 仅参与的，支持分页） +- `notification +read` — 标记单条通知为已读（`-i/--id`） +- `notification +read-all` — 标记所有通知为已读 +- `notification +watch` — 关注 / 取消关注仓库通知（`-o/--owner`、`-r/--repo`，`--unwatch` 取消） + +实现要点： + +- `+list` 为 GET `/notifications`，带 `page`/`limit`/`all`/`participating` 查询参数。 +- `+read` 为 PUT `/notifications/{id}`；`+read-all` 为 PUT `/notifications`。 +- `+watch` 为 POST `/watchers/{owner}/{repo}.json`，`--unwatch` 时改用 DELETE。 +- 全部统一 `owner/repo` 自动解析与 `--format json|table|yaml` 输出。 + +背景：通知管理此前只能在 Web 端手工进行，无法脚本化或被 Agent 调用。`notification` 组补齐命令行入口，便于 CI/Agent 做通知聚合、定期已读、仓库关注等自动化。含单元测试覆盖各命令的 HTTP 方法、路径与查询参数。 diff --git a/doc/commands/notification.md b/doc/commands/notification.md new file mode 100644 index 0000000..6a315d2 --- /dev/null +++ b/doc/commands/notification.md @@ -0,0 +1,41 @@ +# notification — 通知管理 + +## 概述 + +`notification` 模块封装 GitLink 通知相关 OpenAPI：列出通知、标记已读、关注/取消关注仓库通知。 + +## 命令列表 + +### notification +list — 列出通知 +- **参数**： + - `-p, --page` 页码，默认 `1` + - `-l, --limit` 每页数量，默认 `20` +- **示例**： + - `gitlink-cli notification +list` + - `gitlink-cli notification +list -l 50` + +### notification +read — 标记单条已读 +- **参数**： + - `-i, --id`（必填）通知 ID +- **示例**： + - `gitlink-cli notification +read -i 12345` + +### notification +read-all — 全部标记已读 +- **参数**：无 +- **示例**： + - `gitlink-cli notification +read-all` + +### notification +watch — 关注/取消关注仓库通知 +- **参数**： + - `-o, --owner`（必填）仓库所有者 + - `-r, --repo`（必填）仓库名称 +- **示例**： + - `gitlink-cli notification +watch -o Gitlink -r gitlink-cli` + +## 输出 + +支持 `--format json|table|yaml`。 + +## 备注 + +该模块当前**尚无单元测试**（见 `开发日志.md` 待办），调用前建议用 `capability +check` 确认后端通知接口可用。 diff --git a/shortcuts/notification/notification.go b/shortcuts/notification/notification.go new file mode 100644 index 0000000..ac58be8 --- /dev/null +++ b/shortcuts/notification/notification.go @@ -0,0 +1,97 @@ +package notification + +import ( + "fmt" + "net/url" + + "github.com/gitlink-org/gitlink-cli/shortcuts/common" +) + +func Shortcuts() []*common.Shortcut { + return []*common.Shortcut{ + { + Name: "list", + Description: "列出通知", + Flags: []common.Flag{ + {Name: "all", Usage: "显示所有通知（含已读）", Bool: true, Default: "false"}, + {Name: "participating", Usage: "仅显示参与的通知", Bool: true, Default: "false"}, + {Name: "page", Short: "p", Usage: "页码", Default: "1"}, + {Name: "limit", Short: "l", Usage: "每页数量", Default: "20"}, + }, + Run: func(ctx *common.RuntimeContext) error { + q := url.Values{} + q.Set("page", ctx.Arg("page")) + q.Set("limit", ctx.Arg("limit")) + if ctx.Arg("all") == "true" { + q.Set("all", "true") + } + if ctx.Arg("participating") == "true" { + q.Set("participating", "true") + } + env, err := ctx.CallAPIWithQuery("GET", "/notifications", q) + if err != nil { + return err + } + return ctx.Output(env) + }, + }, + { + Name: "read", + Description: "标记单条通知为已读", + Flags: []common.Flag{ + {Name: "id", Short: "i", Usage: "通知 ID", Required: true}, + }, + Run: func(ctx *common.RuntimeContext) error { + id, err := ctx.RequireArg("id") + if err != nil { + return err + } + env, err := ctx.CallAPI("PUT", fmt.Sprintf("/notifications/%s", id), nil) + if err != nil { + return err + } + return ctx.Output(env) + }, + }, + { + Name: "read-all", + Description: "标记所有通知为已读", + Run: func(ctx *common.RuntimeContext) error { + env, err := ctx.CallAPI("PUT", "/notifications", nil) + if err != nil { + return err + } + return ctx.Output(env) + }, + }, + { + Name: "watch", + Description: "关注或取消关注仓库的通知", + Flags: []common.Flag{ + {Name: "owner", Short: "o", Usage: "仓库所有者", Required: true}, + {Name: "repo", Short: "r", Usage: "仓库名称", Required: true}, + {Name: "unwatch", Usage: "取消关注（默认为关注）", Bool: true, Default: "false"}, + }, + Run: func(ctx *common.RuntimeContext) error { + owner, err := ctx.RequireArg("owner") + if err != nil { + return err + } + repo, err := ctx.RequireArg("repo") + if err != nil { + return err + } + path := fmt.Sprintf("/watchers/%s/%s.json", owner, repo) + method := "POST" + if ctx.Arg("unwatch") == "true" { + method = "DELETE" + } + env, err := ctx.CallAPI(method, path, nil) + if err != nil { + return err + } + return ctx.Output(env) + }, + }, + } +} diff --git a/shortcuts/notification/notification_test.go b/shortcuts/notification/notification_test.go new file mode 100644 index 0000000..034b28f --- /dev/null +++ b/shortcuts/notification/notification_test.go @@ -0,0 +1,189 @@ +package notification + +import ( + "encoding/json" + "net/http" + "net/http/httptest" + "testing" + + "github.com/gitlink-org/gitlink-cli/internal/client" + "github.com/gitlink-org/gitlink-cli/shortcuts/common" +) + +func runNotifShortcut(t *testing.T, server *httptest.Server, name string, args map[string]string) error { + t.Helper() + s := findNotifShortcut(t, name) + ctx := &common.RuntimeContext{ + Client: &client.Client{HTTP: server.Client(), BaseURL: server.URL}, + Owner: "owner", + Repo: "repo", + Format: "json", + Args: args, + } + return s.Run(ctx) +} + +func findNotifShortcut(t *testing.T, name string) *common.Shortcut { + t.Helper() + for _, s := range Shortcuts() { + if s.Name == name { + return s + } + } + t.Fatalf("shortcut %q not found", name) + return nil +} + +func writeNotifJSON(w http.ResponseWriter, v interface{}) { + w.Header().Set("Content-Type", "application/json") + json.NewEncoder(w).Encode(v) +} + +// --- list --- + +func TestNotifListBasic(t *testing.T) { + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if r.Method != "GET" { + t.Fatalf("expected GET, got %s", r.Method) + } + if r.URL.Path != "/notifications.json" { + t.Fatalf("unexpected path: %s", r.URL.Path) + } + if got := r.URL.Query().Get("page"); got != "1" { + t.Fatalf("got page %q, want %q", got, "1") + } + if got := r.URL.Query().Get("limit"); got != "20" { + t.Fatalf("got limit %q, want %q", got, "20") + } + writeNotifJSON(w, map[string]interface{}{ + "total_count": float64(1), + "notifications": []interface{}{ + map[string]interface{}{"id": float64(1), "unread": true}, + }, + }) + })) + defer server.Close() + + err := runNotifShortcut(t, server, "list", map[string]string{ + "page": "1", "limit": "20", "all": "false", "participating": "false", + }) + if err != nil { + t.Fatalf("list failed: %v", err) + } +} + +func TestNotifListWithAll(t *testing.T) { + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if got := r.URL.Query().Get("all"); got != "true" { + t.Fatalf("expected all=true, got %q", got) + } + writeNotifJSON(w, map[string]interface{}{"total_count": float64(0), "notifications": []interface{}{}}) + })) + defer server.Close() + + err := runNotifShortcut(t, server, "list", map[string]string{ + "page": "1", "limit": "20", "all": "true", "participating": "false", + }) + if err != nil { + t.Fatalf("list with all failed: %v", err) + } +} + +func TestNotifListWithParticipating(t *testing.T) { + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if got := r.URL.Query().Get("participating"); got != "true" { + t.Fatalf("expected participating=true, got %q", got) + } + writeNotifJSON(w, map[string]interface{}{"total_count": float64(0), "notifications": []interface{}{}}) + })) + defer server.Close() + + err := runNotifShortcut(t, server, "list", map[string]string{ + "page": "1", "limit": "20", "all": "false", "participating": "true", + }) + if err != nil { + t.Fatalf("list with participating failed: %v", err) + } +} + +// --- read --- + +func TestNotifRead(t *testing.T) { + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if r.Method != "PUT" { + t.Fatalf("expected PUT, got %s", r.Method) + } + if r.URL.Path != "/notifications/42.json" { + t.Fatalf("unexpected path: %s", r.URL.Path) + } + writeNotifJSON(w, map[string]interface{}{"status": 0, "message": "success"}) + })) + defer server.Close() + + err := runNotifShortcut(t, server, "read", map[string]string{"id": "42"}) + if err != nil { + t.Fatalf("read failed: %v", err) + } +} + +// --- read-all --- + +func TestNotifReadAll(t *testing.T) { + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if r.Method != "PUT" { + t.Fatalf("expected PUT, got %s", r.Method) + } + if r.URL.Path != "/notifications.json" { + t.Fatalf("unexpected path: %s", r.URL.Path) + } + writeNotifJSON(w, map[string]interface{}{"status": 0, "message": "success"}) + })) + defer server.Close() + + err := runNotifShortcut(t, server, "read-all", map[string]string{}) + if err != nil { + t.Fatalf("read-all failed: %v", err) + } +} + +// --- watch --- + +func TestNotifWatch(t *testing.T) { + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if r.Method != "POST" { + t.Fatalf("expected POST, got %s", r.Method) + } + if r.URL.Path != "/watchers/alice/repo.json" { + t.Fatalf("unexpected path: %s", r.URL.Path) + } + writeNotifJSON(w, map[string]interface{}{"status": 0, "message": "success"}) + })) + defer server.Close() + + err := runNotifShortcut(t, server, "watch", map[string]string{ + "owner": "alice", "repo": "repo", "unwatch": "false", + }) + if err != nil { + t.Fatalf("watch failed: %v", err) + } +} + +func TestNotifUnwatch(t *testing.T) { + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if r.Method != "DELETE" { + t.Fatalf("expected DELETE, got %s", r.Method) + } + if r.URL.Path != "/watchers/bob/project.json" { + t.Fatalf("unexpected path: %s", r.URL.Path) + } + writeNotifJSON(w, map[string]interface{}{"status": 0, "message": "success"}) + })) + defer server.Close() + + err := runNotifShortcut(t, server, "watch", map[string]string{ + "owner": "bob", "repo": "project", "unwatch": "true", + }) + if err != nil { + t.Fatalf("unwatch failed: %v", err) + } +} diff --git a/shortcuts/register.go b/shortcuts/register.go index 1fedc7e..310d5d8 100644 --- a/shortcuts/register.go +++ b/shortcuts/register.go @@ -16,6 +16,7 @@ import ( "github.com/gitlink-org/gitlink-cli/shortcuts/license" "github.com/gitlink-org/gitlink-cli/shortcuts/member" "github.com/gitlink-org/gitlink-cli/shortcuts/milestone" + "github.com/gitlink-org/gitlink-cli/shortcuts/notification" "github.com/gitlink-org/gitlink-cli/shortcuts/org" "github.com/gitlink-org/gitlink-cli/shortcuts/pipeline" "github.com/gitlink-org/gitlink-cli/shortcuts/pr" @@ -42,6 +43,7 @@ func RegisterAll(root *cobra.Command, translators ...*i18n.Translator) { "license": license.Shortcuts(), "member": member.Shortcuts(), "milestone": milestone.Shortcuts(), + "notification": notification.Shortcuts(), "pipeline": pipeline.Shortcuts(), "pr": pr.Shortcuts(tr), "profile": profile.Shortcuts(tr), @@ -67,6 +69,7 @@ func RegisterAll(root *cobra.Command, translators ...*i18n.Translator) { "license": "License operations", "member": "Repository member operations", "milestone": "Milestone operations", + "notification": "Notification operations", "pipeline": "Pipeline operations", "pr": tr.T("cmd.pr.short"), "profile": tr.T("cmd.profile.short"),