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

internal/app/identity/service.go

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

internal/app/identity/service_test.go

@@ -0,0 +1,23 @@
+package identity
+
+import (
+	"context"
+	"errors"
+	"testing"
+)
+
+func TestStubRegisterNotImplemented(t *testing.T) {
+	s := NewStub()
+	_, err := s.Register(context.Background(), RegisterRequest{Source: "self"})
+	if !errors.Is(err, ErrNotImplemented) {
+		t.Fatalf("got %v", err)
+	}
+}
+
+func TestStubHasTalkGrantFalse(t *testing.T) {
+	s := NewStub()
+	ok, err := s.HasTalkGrant(context.Background(), "a", "b")
+	if err != nil || ok {
+		t.Fatalf("ok=%v err=%v", ok, err)
+	}
+}

internal/app/identity/stub.go

@@ -0,0 +1,48 @@
+package identity
+
+import (
+	"context"
+
+	"git.asio.asia/nixevol/NixMsg/internal/protocol"
+)
+
+// Stub 是测试用假实现。
+type Stub struct{}
+
+func NewStub() *Stub { return &Stub{} }
+
+func (s *Stub) Register(context.Context, RegisterRequest) (RegisterResult, error) {
+	return RegisterResult{}, ErrNotImplemented
+}
+
+func (s *Stub) SelfGet(context.Context, string) (SelfInfo, error) {
+	return SelfInfo{}, ErrNotImplemented
+}
+
+func (s *Stub) SelfUpdate(context.Context, string, *protocol.SelfUpdate) error {
+	return ErrNotImplemented
+}
+
+func (s *Stub) SelfSetTalkPassword(context.Context, string, string) error {
+	return ErrNotImplemented
+}
+
+func (s *Stub) SelfChangeLoginPassword(context.Context, string, string, string) (string, error) {
+	return "", ErrNotImplemented
+}
+
+func (s *Stub) SelfLogout(context.Context, string) error { return ErrNotImplemented }
+
+func (s *Stub) UnlockTalk(context.Context, string, string, string) error {
+	return ErrNotImplemented
+}
+
+func (s *Stub) HasTalkGrant(context.Context, string, string) (bool, error) {
+	return false, nil
+}
+
+func (s *Stub) Disable(context.Context, string) error { return ErrNotImplemented }
+func (s *Stub) Enable(context.Context, string) error  { return ErrNotImplemented }
+func (s *Stub) Delete(context.Context, string) error  { return ErrNotImplemented }
+
+var _ Service = (*Stub)(nil)