feat: 补齐模块接口契约与管理 API 文档

2026-09-30 06:36:28 +08:00
parent dd5a331db2
commit 22c56d1f35
23 changed files with 1782 additions and 3 deletions
@@ -0,0 +1,73 @@
+// Package group 定义 DEVELOPMENT 第 6.7 节群操作的接口。
+package group
+
+import (
+	"context"
+	"errors"
+
+	"git.asio.asia/nixevol/NixMsg/internal/protocol"
+)
+
+// ErrNotImplemented 表示假实现未提供业务能力。
+var ErrNotImplemented = errors.New("group: not implemented")
+
+// MemberFail 是建群/加人时部分失败的项。
+type MemberFail struct {
+	ID   string `json:"id"`
+	Code string `json:"code"`
+}
+
+// CreateResult 是建群结果。
+type CreateResult struct {
+	ID      string       `json:"id"`
+	Name    string       `json:"name"`
+	OwnerID string       `json:"owner_id"`
+	Failed  []MemberFail `json:"failed,omitempty"`
+}
+
+// AddResult 是加人结果。
+type AddResult struct {
+	Failed []MemberFail `json:"failed,omitempty"`
+}
+
+// ListItem 是 group.list 一项。
+type ListItem struct {
+	ID          string `json:"id"`
+	Name        string `json:"name"`
+	OwnerID     string `json:"owner_id"`
+	MemberCount int    `json:"member_count"`
+}
+
+// MemberItem 是 group.get 成员项。
+type MemberItem struct {
+	ID     string `json:"id"`
+	Name   string `json:"name"`
+	Online bool   `json:"online"`
+}
+
+// GetResult 是群详情。
+type GetResult struct {
+	ID         string       `json:"id"`
+	Name       string       `json:"name"`
+	OwnerID    string       `json:"owner_id"`
+	Members    []MemberItem `json:"members"`
+	NextCursor string       `json:"next_cursor,omitempty"`
+}
+
+// Service 是群子系统契约（第 6.7 节）。
+type Service interface {
+	Create(ctx context.Context, actorID string, req *protocol.GroupCreate) (CreateResult, error)
+	Add(ctx context.Context, actorID string, req *protocol.GroupAdd) (AddResult, error)
+	Remove(ctx context.Context, actorID string, req *protocol.GroupRemove) error
+	Leave(ctx context.Context, actorID string, req *protocol.GroupLeave) error
+	Transfer(ctx context.Context, actorID string, req *protocol.GroupTransfer) error
+	Rename(ctx context.Context, actorID string, req *protocol.GroupRename) error
+	Dissolve(ctx context.Context, actorID string, req *protocol.GroupDissolve) error
+	List(ctx context.Context, actorID string, req *protocol.GroupList) (items []ListItem, nextCursor string, err error)
+	Get(ctx context.Context, actorID string, req *protocol.GroupGet) (GetResult, error)
+
+	// AdminCreate 后台建群（不要求对话密码）。
+	AdminCreate(ctx context.Context, name string, ownerID string, memberIDs []string) (CreateResult, error)
+	// AdminAddMembers 后台加人。
+	AdminAddMembers(ctx context.Context, groupID string, memberIDs []string) (AddResult, error)
+}