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,63 @@
+// Package identity 定义注册、self.*、对话密码授权、停用与删除级联的接口。
+package identity
+
+import (
+	"context"
+	"errors"
+
+	"git.asio.asia/nixevol/NixMsg/internal/protocol"
+)
+
+// ErrNotImplemented 表示假实现未提供业务能力。
+var ErrNotImplemented = errors.New("identity: not implemented")
+
+// RegisterRequest 对应 POST /api/client/register 与后台开通的公共字段。
+type RegisterRequest struct {
+	RegistrationCode string
+	ID               string
+	LoginPassword    string
+	Name             string
+	TalkPassword     string
+	Remark           string
+	DefaultDelayMs   int64
+	Source           string // admin | self
+	RemoteIP         string
+}
+
+// RegisterResult 是注册/开通结果。
+type RegisterResult struct {
+	ID            string
+	LoginPassword string // 仅当请求留空由服务器生成时非空
+}
+
+// SelfInfo 是 self.get 返回。
+type SelfInfo struct {
+	ID              string `json:"id"`
+	Name            string `json:"name"`
+	DefaultDelayMs  int64  `json:"default_delay_ms"`
+	TalkPasswordSet bool   `json:"talk_password_set"`
+}
+
+// Service 是身份子系统契约。
+type Service interface {
+	// Register 处理自助注册或供管理开通复用（第 6.9 节）。
+	Register(ctx context.Context, req RegisterRequest) (RegisterResult, error)
+
+	SelfGet(ctx context.Context, endpointID string) (SelfInfo, error)
+	SelfUpdate(ctx context.Context, endpointID string, req *protocol.SelfUpdate) error
+	SelfSetTalkPassword(ctx context.Context, endpointID string, talkPassword string) error
+	SelfChangeLoginPassword(ctx context.Context, endpointID string, oldPassword, newPassword string) (sessionToken string, err error)
+	SelfLogout(ctx context.Context, endpointID string) error
+
+	// UnlockTalk 校验并写入对话密码授权（第 6.6 节 unlock）。
+	UnlockTalk(ctx context.Context, senderID, targetID, talkPassword string) error
+	// HasTalkGrant 查询发送方对目标是否有有效授权。
+	HasTalkGrant(ctx context.Context, senderID, targetID string) (bool, error)
+
+	// Disable 停用端并作废相关消息/令牌（第 7.6 节）。
+	Disable(ctx context.Context, endpointID string) error
+	// Enable 重新启用。
+	Enable(ctx context.Context, endpointID string) error
+	// Delete 删除端并做级联清理。
+	Delete(ctx context.Context, endpointID string) error
+}