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