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

internal/app/message/service.go

@@ -0,0 +1,54 @@
+// Package message 定义消息提交、分发、推送、确认、撤回、回执、清理与启动恢复的接口。
+package message
+
+import (
+	"context"
+	"errors"
+
+	"git.asio.asia/nixevol/NixMsg/internal/app/port"
+	"git.asio.asia/nixevol/NixMsg/internal/protocol"
+)
+
+// ErrNotImplemented 表示假实现未提供业务能力。
+var ErrNotImplemented = errors.New("message: not implemented")
+
+// SubmitResult 是发送提交的结果（对应 send 的 resp data）。
+type SubmitResult struct {
+	ID       string
+	SendAtMs int64
+	State    string // scheduled | dispatched | ...
+}
+
+// AckResult 是确认结果。
+type AckResult struct {
+	Result string // accepted | recalled | expired | dropped | rejected 等最终态
+}
+
+// Service 是消息子系统对外契约。方法签名供 M 线实现；T0.4 不写状态机。
+type Service interface {
+	// Submit 处理端发送请求（第 7.3 节）。
+	Submit(ctx context.Context, senderID string, conn port.ConnInfo, req *protocol.Send) (SubmitResult, error)
+	// Ack 处理确认（第 7.6 节）。
+	Ack(ctx context.Context, endpointID string, req *protocol.Ack) (AckResult, error)
+	// Recall 处理撤回。
+	Recall(ctx context.Context, senderID string, req *protocol.Recall) (protocol.RecallData, error)
+	// Status 查询自己发出的消息状态。
+	Status(ctx context.Context, senderID string, req *protocol.Status) (any, error)
+	// ReceiptAck 确认回执已收下。
+	ReceiptAck(ctx context.Context, endpointID string, req *protocol.ReceiptAck) error
+
+	// DispatchDue 分发已到点的 scheduled 消息（第 7.4 节）；由调度循环调用。
+	DispatchDue(ctx context.Context, nowMs int64, limit int) (dispatched int, err error)
+	// PushPending 向已握手连接推送 pending 投递与回执（第 7.5 节）。
+	PushPending(ctx context.Context, endpointID string, connID port.ConnID) error
+	// OnPublishDropped 下行未写入发送队列时，清推送标记并安排重推。
+	OnPublishDropped(ctx context.Context, endpointID string, connID port.ConnID, payload []byte) error
+
+	// CleanupOnce 执行一轮过期投递与记录清理（第 7.5 / 7.6 节）。
+	CleanupOnce(ctx context.Context, nowMs int64) error
+	// RecoverOnStart 启动恢复：清残留 pushed_conn、宽限、补发定时等（第 7.8 节）。
+	RecoverOnStart(ctx context.Context) error
+
+	// WakePush 唤醒某端推送循环（提交/分发后由内部或其它模块调用）。
+	WakePush(endpointID string)
+}

internal/app/message/service_test.go

@@ -0,0 +1,25 @@
+package message
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"git.asio.asia/nixevol/NixMsg/internal/app/port"
+	"git.asio.asia/nixevol/NixMsg/internal/protocol"
+)
+
+func TestStubSubmitNotImplemented(t *testing.T) {
+	s := NewStub()
+	_, err := s.Submit(context.Background(), "a", port.ConnInfo{}, &protocol.Send{})
+	if !errors.Is(err, ErrNotImplemented) {
+		t.Fatalf("got %v", err)
+	}
+}
+
+func TestStubRecoverNoop(t *testing.T) {
+	s := NewStub()
+	if err := s.RecoverOnStart(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+}

internal/app/message/stub.go

@@ -0,0 +1,53 @@
+package message
+
+import (
+	"context"
+
+	"git.asio.asia/nixevol/NixMsg/internal/app/port"
+	"git.asio.asia/nixevol/NixMsg/internal/protocol"
+)
+
+// Stub 是测试用假实现：方法返回 ErrNotImplemented 或固定空结果。
+type Stub struct{}
+
+func NewStub() *Stub { return &Stub{} }
+
+func (s *Stub) Submit(context.Context, string, port.ConnInfo, *protocol.Send) (SubmitResult, error) {
+	return SubmitResult{}, ErrNotImplemented
+}
+
+func (s *Stub) Ack(context.Context, string, *protocol.Ack) (AckResult, error) {
+	return AckResult{}, ErrNotImplemented
+}
+
+func (s *Stub) Recall(context.Context, string, *protocol.Recall) (protocol.RecallData, error) {
+	return protocol.RecallData{}, ErrNotImplemented
+}
+
+func (s *Stub) Status(context.Context, string, *protocol.Status) (any, error) {
+	return nil, ErrNotImplemented
+}
+
+func (s *Stub) ReceiptAck(context.Context, string, *protocol.ReceiptAck) error {
+	return ErrNotImplemented
+}
+
+func (s *Stub) DispatchDue(context.Context, int64, int) (int, error) {
+	return 0, nil
+}
+
+func (s *Stub) PushPending(context.Context, string, port.ConnID) error {
+	return nil
+}
+
+func (s *Stub) OnPublishDropped(context.Context, string, port.ConnID, []byte) error {
+	return nil
+}
+
+func (s *Stub) CleanupOnce(context.Context, int64) error { return nil }
+
+func (s *Stub) RecoverOnStart(context.Context) error { return nil }
+
+func (s *Stub) WakePush(string) {}
+
+var _ Service = (*Stub)(nil)