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