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

internal/app/presence/service.go

@@ -0,0 +1,53 @@
+// Package presence 定义在线查询、目录与上下线订阅的接口。
+package presence
+
+import (
+	"context"
+	"errors"
+
+	"git.asio.asia/nixevol/NixMsg/internal/app/port"
+	"git.asio.asia/nixevol/NixMsg/internal/protocol"
+)
+
+// ErrNotImplemented 表示假实现未提供业务能力。
+var ErrNotImplemented = errors.New("presence: not implemented")
+
+// StatusItem 是 presence.get 单项。
+type StatusItem struct {
+	ID      string `json:"id"`
+	Online  bool   `json:"online"`
+	SinceMs int64  `json:"since_ms"`
+	// NotFound 为 true 时该项对应未知编号（协议用 not_found 表达，实现可汇总）。
+	NotFound bool `json:"-"`
+}
+
+// DirectoryItem 是目录一项。
+type DirectoryItem struct {
+	ID              string `json:"id"`
+	Name            string `json:"name"`
+	Online          bool   `json:"online"`
+	OnlineSinceMs   *int64 `json:"online_since_ms"`
+	OfflineSinceMs  *int64 `json:"offline_since_ms"`
+	TalkPasswordSet bool   `json:"talk_password_set"`
+}
+
+// Service 是在线与目录子系统契约（第 6.5 节）。
+type Service interface {
+	// Get 查询若干编号在线状态。
+	Get(ctx context.Context, ids []string) ([]StatusItem, error)
+	// Directory 分页目录。
+	Directory(ctx context.Context, req *protocol.DirectoryList) (items []DirectoryItem, nextCursor string, err error)
+	// Watch 覆盖本连接的上下线订阅；断线由 ClearWatch 清空。
+	Watch(ctx context.Context, connID port.ConnID, endpointID string, req *protocol.PresenceWatch) error
+	// ClearWatch 在连接断开时清空订阅。
+	ClearWatch(connID port.ConnID)
+
+	// SetOnline 握手完成时标记在线并通知订阅者。
+	SetOnline(ctx context.Context, endpointID string, connID port.ConnID, atMs int64) error
+	// SetOffline 当前连接断开时标记离线并通知订阅者。
+	SetOffline(ctx context.Context, endpointID string, connID port.ConnID, atMs int64) error
+	// IsOnline 查询端是否有已握手连接。
+	IsOnline(endpointID string) bool
+	// CurrentConn 返回端的当前连接代号；无则空。
+	CurrentConn(endpointID string) (port.ConnID, bool)
+}

internal/app/presence/service_test.go

@@ -0,0 +1,23 @@
+package presence
+
+import (
+	"context"
+	"testing"
+)
+
+func TestStubGetOffline(t *testing.T) {
+	s := NewStub()
+	items, err := s.Get(context.Background(), []string{"a", "b"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(items) != 2 || items[0].Online || items[1].Online {
+		t.Fatalf("%+v", items)
+	}
+}
+
+func TestStubIsOnlineFalse(t *testing.T) {
+	if NewStub().IsOnline("x") {
+		t.Fatal("expected offline")
+	}
+}

internal/app/presence/stub.go

@@ -0,0 +1,41 @@
+package presence
+
+import (
+	"context"
+
+	"git.asio.asia/nixevol/NixMsg/internal/app/port"
+	"git.asio.asia/nixevol/NixMsg/internal/protocol"
+)
+
+// Stub 是测试用假实现：全部视为离线。
+type Stub struct{}
+
+func NewStub() *Stub { return &Stub{} }
+
+func (s *Stub) Get(_ context.Context, ids []string) ([]StatusItem, error) {
+	out := make([]StatusItem, 0, len(ids))
+	for _, id := range ids {
+		out = append(out, StatusItem{ID: id, Online: false, SinceMs: 0})
+	}
+	return out, nil
+}
+
+func (s *Stub) Directory(context.Context, *protocol.DirectoryList) ([]DirectoryItem, string, error) {
+	return nil, "", nil
+}
+
+func (s *Stub) Watch(context.Context, port.ConnID, string, *protocol.PresenceWatch) error {
+	return nil
+}
+
+func (s *Stub) ClearWatch(port.ConnID) {}
+
+func (s *Stub) SetOnline(context.Context, string, port.ConnID, int64) error { return nil }
+
+func (s *Stub) SetOffline(context.Context, string, port.ConnID, int64) error { return nil }
+
+func (s *Stub) IsOnline(string) bool { return false }
+
+func (s *Stub) CurrentConn(string) (port.ConnID, bool) { return "", false }
+
+var _ Service = (*Stub)(nil)