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

internal/app/group/service.go

@@ -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)
+}

internal/app/group/service_test.go

@@ -0,0 +1,25 @@
+package group
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"git.asio.asia/nixevol/NixMsg/internal/protocol"
+)
+
+func TestStubCreateNotImplemented(t *testing.T) {
+	s := NewStub()
+	_, err := s.Create(context.Background(), "a", &protocol.GroupCreate{Name: "g"})
+	if !errors.Is(err, ErrNotImplemented) {
+		t.Fatalf("got %v", err)
+	}
+}
+
+func TestStubListEmpty(t *testing.T) {
+	s := NewStub()
+	items, cursor, err := s.List(context.Background(), "a", &protocol.GroupList{})
+	if err != nil || len(items) != 0 || cursor != "" {
+		t.Fatalf("items=%v cursor=%q err=%v", items, cursor, err)
+	}
+}

internal/app/group/stub.go

@@ -0,0 +1,58 @@
+package group
+
+import (
+	"context"
+
+	"git.asio.asia/nixevol/NixMsg/internal/protocol"
+)
+
+// Stub 是测试用假实现。
+type Stub struct{}
+
+func NewStub() *Stub { return &Stub{} }
+
+func (s *Stub) Create(context.Context, string, *protocol.GroupCreate) (CreateResult, error) {
+	return CreateResult{}, ErrNotImplemented
+}
+
+func (s *Stub) Add(context.Context, string, *protocol.GroupAdd) (AddResult, error) {
+	return AddResult{}, ErrNotImplemented
+}
+
+func (s *Stub) Remove(context.Context, string, *protocol.GroupRemove) error {
+	return ErrNotImplemented
+}
+
+func (s *Stub) Leave(context.Context, string, *protocol.GroupLeave) error {
+	return ErrNotImplemented
+}
+
+func (s *Stub) Transfer(context.Context, string, *protocol.GroupTransfer) error {
+	return ErrNotImplemented
+}
+
+func (s *Stub) Rename(context.Context, string, *protocol.GroupRename) error {
+	return ErrNotImplemented
+}
+
+func (s *Stub) Dissolve(context.Context, string, *protocol.GroupDissolve) error {
+	return ErrNotImplemented
+}
+
+func (s *Stub) List(context.Context, string, *protocol.GroupList) ([]ListItem, string, error) {
+	return nil, "", nil
+}
+
+func (s *Stub) Get(context.Context, string, *protocol.GroupGet) (GetResult, error) {
+	return GetResult{}, ErrNotImplemented
+}
+
+func (s *Stub) AdminCreate(context.Context, string, string, []string) (CreateResult, error) {
+	return CreateResult{}, ErrNotImplemented
+}
+
+func (s *Stub) AdminAddMembers(context.Context, string, []string) (AddResult, error) {
+	return AddResult{}, ErrNotImplemented
+}
+
+var _ Service = (*Stub)(nil)