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