DNF90 服务端与启动器完整源码（含 GM 工具功能增强）

服务端（Go）：
- GM 塞背包/带属性装备发放：在线角色推送 op14 增量物品行，背包实时刷新，无需回角色选择界面
- GM 改金币/改等级：去掉在线拒绝，落库后推送 op14 钱包/op37 等级状态，在线实时刷新
- 等级端点统一切换到新版 GMSetCharacterLevel（自带在线刷新）
- 无限/锁死疲劳模式 + 燃烧疲劳：每房间消耗 2 点、打怪与通关经验双倍
- 燃烧疲劳开关时给所有在线角色推送系统提示（op12 mode 0）
- 深渊史诗掉率：GM 全局倍率 + 城镇增益药剂窗口倍率，真实接入掉落结算

启动器（Python/JS）：
- 标题栏自绘、窗口 1204x717、禁止拖拽改大小、仅最小化/关闭
- GM 工具：疲劳与燃烧、深渊史诗掉率、拍卖行上架（单一定价对齐）
- 拍卖行上架前端对齐服务端单一价格语义，修复 400 报错

server/internal/runtime/notice/admin.go

@@ -0,0 +1,406 @@
+package notice
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+
+	"longheng.io/server/internal/platform/admincmd"
+	"longheng.io/server/internal/platform/httpx"
+)
+
+var ErrAdminMuxRequired = errors.New("notice admin mux is required")
+
+const maxNoticeJSONBytes = 1 << 20
+
+type AdminOptions struct {
+	Prefix       string
+	Wrap         func(http.HandlerFunc) http.HandlerFunc
+	MutateWrap   func(string, http.HandlerFunc) http.HandlerFunc
+	CommandHooks AdminCommandHooks
+}
+
+type AdminCommandHooks struct {
+	Submit               func(*http.Request, string, string, string, any) (admincmd.Receipt, bool, bool, error)
+	MarkSucceeded        func(context.Context, admincmd.Receipt) admincmd.Receipt
+	MarkFailed           func(context.Context, admincmd.Receipt, error)
+	WriteError           func(http.ResponseWriter, error) bool
+	WriteDuplicate       func(http.ResponseWriter, admincmd.Receipt)
+	WriteJSONWithReceipt func(http.ResponseWriter, int, map[string]any, admincmd.Receipt)
+}
+
+func RegisterAdminRoutes(mux *http.ServeMux, service Service, options AdminOptions) error {
+	if mux == nil {
+		return ErrAdminMuxRequired
+	}
+	prefix := normalizeAdminPrefix(options.Prefix)
+	wrap := options.Wrap
+	if wrap == nil {
+		wrap = func(next http.HandlerFunc) http.HandlerFunc { return next }
+	}
+	mutateWrap := options.MutateWrap
+	if mutateWrap == nil {
+		mutateWrap = func(_ string, next http.HandlerFunc) http.HandlerFunc {
+			return wrap(next)
+		}
+	}
+	mux.HandleFunc(prefix, wrap(SnapshotHandler(service)))
+	mux.HandleFunc(prefix+"/snapshot", wrap(SnapshotHandler(service)))
+	mux.HandleFunc(prefix+"/publish", mutateWrap(httpx.AdminOperationID(http.MethodPost, prefix+"/publish"), PublishHandlerWithCommands(service, options.CommandHooks)))
+	mux.HandleFunc(prefix+"/acknowledge", mutateWrap(httpx.AdminOperationID(http.MethodPost, prefix+"/acknowledge"), AckHandlerCommands(service, options.CommandHooks)))
+	mux.HandleFunc(prefix+"/delete", mutateWrap(httpx.AdminOperationID(http.MethodPost, prefix+"/delete"), DeleteHandlerWithCommands(service, options.CommandHooks)))
+	mux.HandleFunc(prefix+"/account", wrap(AccountHandler(service)))
+	mux.HandleFunc(prefix+"/announcements", wrap(AnnouncementsHandler(service)))
+	return nil
+}
+
+func SnapshotHandler(service Service) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodGet {
+			writeMethodNA(w, http.MethodGet)
+			return
+		}
+		snapshot, err := service.Snapshot(r.Context())
+		if err != nil {
+			writeNoticeError(w, err)
+			return
+		}
+		httpx.WriteJSON(w, http.StatusOK, snapshot)
+	}
+}
+
+func PublishHandler(service Service) http.HandlerFunc {
+	return PublishHandlerWithCommands(service, AdminCommandHooks{})
+}
+
+func PublishHandlerWithCommands(service Service, commands AdminCommandHooks) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodPost {
+			writeMethodNA(w, http.MethodPost)
+			return
+		}
+		var request PublishRequest
+		if err := decodeNoticeJSON(w, r, &request); err != nil {
+			httpx.WriteJSON(w, http.StatusBadRequest, map[string]string{"error": err.Error()})
+			return
+		}
+		receipt, duplicate, submitted, err := submitNoticeCmd(commands, r, "logic.notice.publish", firstNonEmpty(request.Notice.ID, "notice"), "notice publish", request)
+		if writeNoticeCmdErr(commands, w, err) {
+			return
+		}
+		if submitted && duplicate {
+			writeCmdDuplicate(commands, w, receipt)
+			return
+		}
+		if submitted {
+			request.AdminCommand = nil
+		}
+		result, err := service.Publish(r.Context(), request)
+		if err != nil {
+			if submitted {
+				markNoticeCmdFail(commands, r.Context(), receipt, err)
+			}
+			writeNoticeError(w, err)
+			return
+		}
+		if submitted {
+			receipt = markNoticeCmdOK(commands, r.Context(), receipt)
+			writeNoticeReceipt(commands, w, http.StatusOK, noticeResponseMap(result), receipt)
+			return
+		}
+		httpx.WriteJSON(w, http.StatusOK, result)
+	}
+}
+
+func AcknowledgeHandler(service Service) http.HandlerFunc {
+	return AckHandlerCommands(service, AdminCommandHooks{})
+}
+
+func AckHandlerCommands(service Service, commands AdminCommandHooks) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodPost {
+			writeMethodNA(w, http.MethodPost)
+			return
+		}
+		var request AcknowledgeRequest
+		if err := decodeNoticeJSON(w, r, &request); err != nil {
+			httpx.WriteJSON(w, http.StatusBadRequest, map[string]string{"error": err.Error()})
+			return
+		}
+		target := request.DeliveryID
+		if target == "" {
+			target = strings.TrimSpace(request.NoticeID + ":" + request.AccountID)
+		}
+		receipt, duplicateCommand, submitted, err := submitNoticeCmd(commands, r, "logic.notice.acknowledge", target, "notice acknowledge", request)
+		if writeNoticeCmdErr(commands, w, err) {
+			return
+		}
+		if submitted && duplicateCommand {
+			writeCmdDuplicate(commands, w, receipt)
+			return
+		}
+		delivery, duplicate, err := service.Acknowledge(r.Context(), request)
+		if err != nil {
+			if submitted {
+				markNoticeCmdFail(commands, r.Context(), receipt, err)
+			}
+			writeNoticeError(w, err)
+			return
+		}
+		response := map[string]any{
+			"delivery":  delivery,
+			"duplicate": duplicate,
+		}
+		if submitted {
+			receipt = markNoticeCmdOK(commands, r.Context(), receipt)
+			writeNoticeReceipt(commands, w, http.StatusOK, response, receipt)
+			return
+		}
+		httpx.WriteJSON(w, http.StatusOK, response)
+	}
+}
+
+func DeleteHandler(service Service) http.HandlerFunc {
+	return DeleteHandlerWithCommands(service, AdminCommandHooks{})
+}
+
+func DeleteHandlerWithCommands(service Service, commands AdminCommandHooks) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodPost {
+			writeMethodNA(w, http.MethodPost)
+			return
+		}
+		var request DeleteRequest
+		if err := decodeNoticeJSON(w, r, &request); err != nil {
+			httpx.WriteJSON(w, http.StatusBadRequest, map[string]string{"error": err.Error()})
+			return
+		}
+		target := strings.Join(request.DeliveryIDs, ",")
+		if target == "" {
+			target = strings.TrimSpace(request.NoticeID + ":" + request.AccountID)
+		}
+		receipt, duplicateCommand, submitted, err := submitNoticeCmd(commands, r, "logic.notice.delete", target, "notice delete", request)
+		if writeNoticeCmdErr(commands, w, err) {
+			return
+		}
+		if submitted && duplicateCommand {
+			writeCmdDuplicate(commands, w, receipt)
+			return
+		}
+		result, err := service.Delete(r.Context(), request)
+		if err != nil {
+			if submitted {
+				markNoticeCmdFail(commands, r.Context(), receipt, err)
+			}
+			writeNoticeError(w, err)
+			return
+		}
+		response := map[string]any{"result": result}
+		if submitted {
+			receipt = markNoticeCmdOK(commands, r.Context(), receipt)
+			writeNoticeReceipt(commands, w, http.StatusOK, response, receipt)
+			return
+		}
+		httpx.WriteJSON(w, http.StatusOK, response)
+	}
+}
+
+func submitNoticeCmd(commands AdminCommandHooks, r *http.Request, operation, target, reason string, params any) (admincmd.Receipt, bool, bool, error) {
+	if commands.Submit == nil {
+		return admincmd.Receipt{}, false, false, nil
+	}
+	return commands.Submit(r, operation, target, reason, params)
+}
+
+// decodeNoticeJSON 统一限制管理端写请求的大小、字段和单文档格式。
+func decodeNoticeJSON(w http.ResponseWriter, r *http.Request, out any) error {
+	return httpx.DecodeStrictJSON(w, r, maxNoticeJSONBytes, out)
+}
+
+func markNoticeCmdOK(commands AdminCommandHooks, ctx context.Context, receipt admincmd.Receipt) admincmd.Receipt {
+	if commands.MarkSucceeded == nil || receipt.ID == "" {
+		return receipt
+	}
+	return commands.MarkSucceeded(ctx, receipt)
+}
+
+func markNoticeCmdFail(commands AdminCommandHooks, ctx context.Context, receipt admincmd.Receipt, err error) {
+	if commands.MarkFailed == nil || receipt.ID == "" || err == nil {
+		return
+	}
+	commands.MarkFailed(ctx, receipt, err)
+}
+
+func writeNoticeCmdErr(commands AdminCommandHooks, w http.ResponseWriter, err error) bool {
+	if err == nil {
+		return false
+	}
+	if commands.WriteError != nil {
+		return commands.WriteError(w, err)
+	}
+	writeNoticeError(w, err)
+	return true
+}
+
+func writeCmdDuplicate(commands AdminCommandHooks, w http.ResponseWriter, receipt admincmd.Receipt) {
+	if commands.WriteDuplicate != nil {
+		commands.WriteDuplicate(w, receipt)
+		return
+	}
+	if receipt.ID != "" {
+		w.Header().Set(httpx.AdminReceiptHeader, receipt.ID)
+	}
+	httpx.WriteJSON(w, http.StatusOK, map[string]any{
+		"status":        "duplicate",
+		"admin_receipt": receipt,
+	})
+}
+
+func writeNoticeReceipt(commands AdminCommandHooks, w http.ResponseWriter, status int, response map[string]any, receipt admincmd.Receipt) {
+	if commands.WriteJSONWithReceipt != nil {
+		commands.WriteJSONWithReceipt(w, status, response, receipt)
+		return
+	}
+	if response == nil {
+		response = make(map[string]any)
+	}
+	if receipt.ID != "" {
+		w.Header().Set(httpx.AdminReceiptHeader, receipt.ID)
+		response["admin_receipt"] = receipt
+	}
+	httpx.WriteJSON(w, status, response)
+}
+
+func noticeResponseMap(value any) map[string]any {
+	data, err := json.Marshal(value)
+	if err != nil {
+		return map[string]any{"marshal_error": err.Error()}
+	}
+	var out map[string]any
+	if err := json.Unmarshal(data, &out); err != nil {
+		return map[string]any{"marshal_error": err.Error()}
+	}
+	return out
+}
+
+func AccountHandler(service Service) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodGet {
+			writeMethodNA(w, http.MethodGet)
+			return
+		}
+		query := Query{
+			AccountID: r.URL.Query().Get("account_id"),
+			ShardID:   r.URL.Query().Get("shard_id"),
+			Cursor:    r.URL.Query().Get("cursor"),
+		}
+		if limit, err := parseQueryInt(r.URL.Query().Get("limit")); err != nil {
+			httpx.WriteJSON(w, http.StatusBadRequest, map[string]string{"error": err.Error()})
+			return
+		} else {
+			query.Limit = limit
+		}
+		now, err := parseQueryTime(r.URL.Query().Get("now"))
+		if err != nil {
+			httpx.WriteJSON(w, http.StatusBadRequest, map[string]string{"error": err.Error()})
+			return
+		}
+		query.Now = now
+		result, err := service.ListPageForAccount(r.Context(), query)
+		if err != nil {
+			writeNoticeError(w, err)
+			return
+		}
+		httpx.WriteJSON(w, http.StatusOK, result)
+	}
+}
+
+func AnnouncementsHandler(service Service) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodGet {
+			writeMethodNA(w, http.MethodGet)
+			return
+		}
+		query := Query{
+			ShardID: r.URL.Query().Get("shard_id"),
+		}
+		now, err := parseQueryTime(r.URL.Query().Get("now"))
+		if err != nil {
+			httpx.WriteJSON(w, http.StatusBadRequest, map[string]string{"error": err.Error()})
+			return
+		}
+		query.Now = now
+		items, err := service.ActiveAnnouncements(r.Context(), query)
+		if err != nil {
+			writeNoticeError(w, err)
+			return
+		}
+		httpx.WriteJSON(w, http.StatusOK, map[string]any{"items": items})
+	}
+}
+
+func writeNoticeError(w http.ResponseWriter, err error) {
+	status := http.StatusBadRequest
+	if errors.Is(err, ErrStoreRequired) {
+		status = http.StatusServiceUnavailable
+	}
+	if errors.Is(err, ErrNoticeNotFound) || errors.Is(err, ErrDeliveryNotFound) {
+		status = http.StatusNotFound
+	}
+	if errors.Is(err, ErrIdempotencyConflict) {
+		status = http.StatusConflict
+	}
+	httpx.WriteJSON(w, status, map[string]string{"error": err.Error()})
+}
+
+func writeMethodNA(w http.ResponseWriter, methods ...string) {
+	w.Header().Set("Allow", strings.Join(methods, ", "))
+	httpx.WriteJSON(w, http.StatusMethodNotAllowed, map[string]string{"error": "method not allowed"})
+}
+
+func parseQueryTime(value string) (time.Time, error) {
+	value = strings.TrimSpace(value)
+	if value == "" {
+		return time.Time{}, nil
+	}
+	parsed, err := time.Parse(time.RFC3339, value)
+	if err != nil {
+		return time.Time{}, fmt.Errorf("invalid now query time: %w", err)
+	}
+	return parsed.UTC(), nil
+}
+
+func parseQueryInt(value string) (int, error) {
+	value = strings.TrimSpace(value)
+	if value == "" {
+		return 0, nil
+	}
+	out, err := strconv.Atoi(value)
+	if err != nil {
+		return 0, fmt.Errorf("invalid limit query value: %w", err)
+	}
+	if out < 0 {
+		return 0, fmt.Errorf("invalid limit query value: %d", out)
+	}
+	return out, nil
+}
+
+func normalizeAdminPrefix(prefix string) string {
+	prefix = strings.TrimSpace(prefix)
+	if prefix == "" {
+		return "/debug/notice"
+	}
+	if !strings.HasPrefix(prefix, "/") {
+		prefix = "/" + prefix
+	}
+	prefix = strings.TrimRight(prefix, "/")
+	if prefix == "" {
+		return "/debug/notice"
+	}
+	return prefix
+}

server/internal/runtime/notice/async_publisher.go

@@ -0,0 +1,303 @@
+package notice
+
+import (
+	"context"
+	"errors"
+	"sync"
+	"sync/atomic"
+	"time"
+)
+
+const (
+	liveQueueMax      = 4096
+	liveFlushTimeout  = 3 * time.Second
+	liveRetryInterval = 200 * time.Millisecond
+)
+
+var (
+	errLiveClosed = errors.New("notice live publisher queue is closed")
+	errLiveFull   = errors.New("notice live publisher queue is full")
+)
+
+// AsyncLivePublisher 把公告在线推送移出发布热路径。
+// Store 和 EventLog 仍由 Service.Publish 同步完成，后台只处理可丢弃的 live fanout。
+type AsyncLivePublisher struct {
+	next    LivePublisher
+	max     int
+	timeout time.Duration
+
+	mu        sync.Mutex
+	pending   []PublishResult
+	closed    bool
+	flushing  bool
+	flushDone chan struct{}
+	errs      uint64
+
+	wake chan struct{}
+	stop chan struct{}
+	done chan struct{}
+	once sync.Once
+}
+
+// NewAsyncLivePublisher 创建异步 live publisher。
+func NewAsyncLivePublisher(next LivePublisher) *AsyncLivePublisher {
+	publisher := &AsyncLivePublisher{
+		next:    next,
+		max:     liveQueueMax,
+		timeout: liveFlushTimeout,
+		wake:    make(chan struct{}, 1),
+		stop:    make(chan struct{}),
+		done:    make(chan struct{}),
+	}
+	go publisher.run()
+	return publisher
+}
+
+// WrapAsyncLivePublisher 按需把同步 live publisher 包成异步队列。
+func WrapAsyncLivePublisher(publisher LivePublisher) LivePublisher {
+	switch publisher.(type) {
+	case nil, *AsyncLivePublisher:
+		return publisher
+	default:
+		return NewAsyncLivePublisher(publisher)
+	}
+}
+
+// PublishNotice 只做入队，后台 worker 负责真正推送。
+func (p *AsyncLivePublisher) PublishNotice(ctx context.Context, result PublishResult) error {
+	if p == nil || p.next == nil {
+		return ErrLivePublisherMissing
+	}
+	if err := ctxErr(ctx); err != nil {
+		return err
+	}
+	result = clonePublishResult(result)
+
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	if p.closed {
+		return errLiveClosed
+	}
+	if len(p.pending) >= p.max {
+		atomic.AddUint64(&p.errs, 1)
+		return errLiveFull
+	}
+	p.pending = append(p.pending, result)
+	p.wakeLocked()
+	return nil
+}
+
+// Flush 同步排空当前待推送队列，主要给测试、管理面和服务停止使用。
+func (p *AsyncLivePublisher) Flush(ctx context.Context) error {
+	if p == nil || p.next == nil {
+		return ErrLivePublisherMissing
+	}
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	for {
+		batch, wait := p.beginFlush()
+		if wait != nil {
+			if err := waitLiveFlush(ctx, wait); err != nil {
+				return err
+			}
+			continue
+		}
+		if len(batch) == 0 {
+			return nil
+		}
+		if err := p.writeBatch(ctx, batch); err != nil {
+			return err
+		}
+	}
+}
+
+// Close 停止后台 worker，并在返回前尽量排空 live 队列。
+func (p *AsyncLivePublisher) Close(ctx context.Context) error {
+	if p == nil {
+		return nil
+	}
+	closeCtx, cancel := p.closeContext(ctx)
+	defer cancel()
+	p.once.Do(func() {
+		p.mu.Lock()
+		p.closed = true
+		p.mu.Unlock()
+		close(p.stop)
+	})
+	select {
+	case <-p.done:
+	case <-closeCtx.Done():
+		return closeCtx.Err()
+	}
+	return errors.Join(p.Flush(closeCtx), closeLivePublisher(closeCtx, p.next))
+}
+
+func (p *AsyncLivePublisher) closeContext(ctx context.Context) (context.Context, context.CancelFunc) {
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	if _, ok := ctx.Deadline(); ok {
+		return ctx, func() {}
+	}
+	timeout := liveFlushTimeout
+	if p.timeout > 0 {
+		timeout = p.timeout
+	}
+	return context.WithTimeout(ctx, timeout)
+}
+
+// Errors 返回后台 live fanout 失败次数。
+func (p *AsyncLivePublisher) Errors() uint64 {
+	if p == nil {
+		return 0
+	}
+	return atomic.LoadUint64(&p.errs)
+}
+
+func (p *AsyncLivePublisher) run() {
+	defer close(p.done)
+	retry := time.NewTimer(time.Hour)
+	stopLiveTimer(retry)
+	var retryC <-chan time.Time
+	defer stopLiveTimer(retry)
+	for {
+		select {
+		case <-p.wake:
+			if err := p.flushBackground(); err != nil {
+				resetLiveTimer(retry, liveRetryInterval)
+				retryC = retry.C
+			} else {
+				retryC = nil
+			}
+		case <-retryC:
+			retryC = nil
+			if err := p.flushBackground(); err != nil {
+				resetLiveTimer(retry, liveRetryInterval)
+				retryC = retry.C
+			}
+		case <-p.stop:
+			return
+		}
+	}
+}
+
+func (p *AsyncLivePublisher) flushBackground() error {
+	timeout := p.timeout
+	if timeout <= 0 {
+		timeout = liveFlushTimeout
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), timeout)
+	err := p.Flush(ctx)
+	cancel()
+	return err
+}
+
+func (p *AsyncLivePublisher) beginFlush() ([]PublishResult, <-chan struct{}) {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	if p.flushing {
+		return nil, p.flushDone
+	}
+	if len(p.pending) == 0 {
+		return nil, nil
+	}
+	batch := clonePublishResults(p.pending)
+	p.pending = nil
+	p.flushing = true
+	p.flushDone = make(chan struct{})
+	return batch, nil
+}
+
+func (p *AsyncLivePublisher) writeBatch(ctx context.Context, batch []PublishResult) error {
+	for idx, result := range batch {
+		if err := ctxErr(ctx); err != nil {
+			p.finishFlush(batch[idx:], err)
+			return err
+		}
+		if err := p.next.PublishNotice(ctx, result); err != nil {
+			atomic.AddUint64(&p.errs, 1)
+			p.finishFlush(batch[idx:], err)
+			return err
+		}
+	}
+	p.finishFlush(nil, nil)
+	return nil
+}
+
+func (p *AsyncLivePublisher) finishFlush(failed []PublishResult, _ error) {
+	p.mu.Lock()
+	if len(failed) > 0 {
+		restored := clonePublishResults(failed)
+		restored = append(restored, p.pending...)
+		p.pending = restored
+	}
+	done := p.flushDone
+	p.flushing = false
+	p.flushDone = nil
+	p.mu.Unlock()
+	if done != nil {
+		close(done)
+	}
+}
+
+func (p *AsyncLivePublisher) wakeLocked() {
+	select {
+	case p.wake <- struct{}{}:
+	default:
+	}
+}
+
+func clonePublishResults(in []PublishResult) []PublishResult {
+	if len(in) == 0 {
+		return nil
+	}
+	out := make([]PublishResult, len(in))
+	for idx, result := range in {
+		out[idx] = clonePublishResult(result)
+	}
+	return out
+}
+
+func waitLiveFlush(ctx context.Context, done <-chan struct{}) error {
+	select {
+	case <-done:
+		return nil
+	case <-ctx.Done():
+		return ctx.Err()
+	}
+}
+
+func closeLivePublisher(ctx context.Context, publisher LivePublisher) error {
+	if closer, ok := publisher.(interface {
+		Close(context.Context) error
+	}); ok {
+		return closer.Close(ctx)
+	}
+	if flusher, ok := publisher.(interface {
+		Flush(context.Context) error
+	}); ok {
+		return flusher.Flush(ctx)
+	}
+	return nil
+}
+
+func stopLiveTimer(timer *time.Timer) {
+	if timer == nil {
+		return
+	}
+	if !timer.Stop() {
+		select {
+		case <-timer.C:
+		default:
+		}
+	}
+}
+
+func resetLiveTimer(timer *time.Timer, d time.Duration) {
+	if d <= 0 {
+		d = liveRetryInterval
+	}
+	stopLiveTimer(timer)
+	timer.Reset(d)
+}

server/internal/runtime/notice/backend_kind.go

@@ -0,0 +1,11 @@
+package notice
+
+import "longheng.io/server/internal/platform/runtimeguard"
+
+func (*MemoryStore) BackendKind() runtimeguard.Backend {
+	return runtimeguard.BackendMemory
+}
+
+func (*SQLStore) BackendKind() runtimeguard.Backend {
+	return runtimeguard.BackendMySQL
+}

server/internal/runtime/notice/bus_publisher.go

@@ -0,0 +1,196 @@
+package notice
+
+import (
+	"context"
+	"errors"
+	"strings"
+
+	buskit "longheng.io/server/internal/platform/bus"
+	"longheng.io/server/pkg/contracts"
+	"longheng.io/server/pkg/protocol"
+)
+
+type BusPublisher struct {
+	Bus   buskit.Bus
+	Topic string
+}
+
+func NewBusPublisher(bus buskit.Bus) *BusPublisher {
+	return &BusPublisher{Bus: bus, Topic: contracts.TopicNoticePublished}
+}
+
+func (p *BusPublisher) PublishNotice(ctx context.Context, result PublishResult) error {
+	if err := ctxErr(ctx); err != nil {
+		return err
+	}
+	if p == nil || p.Bus == nil {
+		return ErrLivePublisherMissing
+	}
+	topic := strings.TrimSpace(p.Topic)
+	if topic == "" {
+		topic = contracts.TopicNoticePublished
+	}
+	return p.Bus.Publish(ctx, topic, noticePublishedEvent(result))
+}
+
+func noticePublishedEvent(result PublishResult) contracts.NoticePublished {
+	recipients := make([]string, 0, len(result.Deliveries))
+	deliveryIDs := make([]string, 0, len(result.Deliveries))
+	for _, delivery := range result.Deliveries {
+		recipients = append(recipients, delivery.AccountID)
+		deliveryIDs = append(deliveryIDs, delivery.ID)
+	}
+	return contracts.NoticePublished{
+		NoticeID:      result.Notice.ID,
+		Kind:          result.Notice.Kind,
+		Scope:         result.Notice.Scope,
+		ShardID:       result.Notice.ShardID,
+		Title:         result.Notice.Title,
+		Body:          result.Notice.Body,
+		AttachmentRef: result.Notice.AttachmentRef,
+		Recipients:    recipients,
+		DeliveryIDs:   deliveryIDs,
+		Meta:          cloneStringMap(result.Meta),
+		PublishedAt:   result.PublishedAt,
+	}
+}
+
+type GatewayPushEncoder func(PublishResult, Delivery) ([]byte, error)
+
+type PushPublisherOptions struct {
+	Bus                    buskit.Bus
+	Topic                  string
+	PacketID               int32
+	MsgID                  uint32
+	WireFormat             string
+	Encode                 GatewayPushEncoder
+	BroadcastAnnouncements bool
+}
+
+type GatewayPushPublisher struct {
+	options PushPublisherOptions
+}
+
+func NewGatewayPushPublisher(bus buskit.Bus) *GatewayPushPublisher {
+	return NewGatewayPushPublisherWithOptions(PushPublisherOptions{Bus: bus})
+}
+
+func NewGatewayPushPublisherWithOptions(options PushPublisherOptions) *GatewayPushPublisher {
+	if options.Topic == "" {
+		options.Topic = contracts.TopicGatewayPush
+	}
+	if options.PacketID == 0 {
+		options.PacketID = protocol.PacketIDContent
+	}
+	if options.MsgID == 0 {
+		options.MsgID = protocol.MessageNoticePush
+	}
+	if options.Encode == nil {
+		options.Encode = EncodeGatewayNoticePush
+	}
+	return &GatewayPushPublisher{options: options}
+}
+
+func (p *GatewayPushPublisher) PublishNotice(ctx context.Context, result PublishResult) error {
+	if err := ctxErr(ctx); err != nil {
+		return err
+	}
+	if p == nil || p.options.Bus == nil {
+		return ErrLivePublisherMissing
+	}
+	if result.Notice.Kind == KindAnnouncement && len(result.Deliveries) == 0 && p.options.BroadcastAnnouncements {
+		body, err := p.options.Encode(result, Delivery{})
+		if err != nil {
+			return err
+		}
+		return p.publish(ctx, contracts.GatewayPush{
+			Broadcast:  true,
+			PacketID:   p.options.PacketID,
+			MsgID:      p.options.MsgID,
+			WireFormat: p.options.WireFormat,
+			Body:       body,
+			Metadata:   gwNoticeMeta(result, Delivery{}),
+			Note:       "notice-announcement-push",
+			CreatedAt:  result.PublishedAt,
+		})
+	}
+	var errs []error
+	for _, delivery := range result.Deliveries {
+		body, err := p.options.Encode(result, delivery)
+		if err != nil {
+			errs = append(errs, err)
+			continue
+		}
+		err = p.publish(ctx, contracts.GatewayPush{
+			AccountID:  delivery.AccountID,
+			PacketID:   p.options.PacketID,
+			MsgID:      p.options.MsgID,
+			WireFormat: p.options.WireFormat,
+			Body:       body,
+			Metadata:   gwNoticeMeta(result, delivery),
+			Note:       "notice-direct-push",
+			CreatedAt:  result.PublishedAt,
+		})
+		if err != nil {
+			errs = append(errs, err)
+		}
+	}
+	return errors.Join(errs...)
+}
+
+func (p *GatewayPushPublisher) publish(ctx context.Context, push contracts.GatewayPush) error {
+	topic := strings.TrimSpace(p.options.Topic)
+	if topic == "" {
+		topic = contracts.TopicGatewayPush
+	}
+	return p.options.Bus.Publish(ctx, topic, push)
+}
+
+func EncodeGatewayNoticePush(result PublishResult, delivery Delivery) ([]byte, error) {
+	return protocol.EncodeNoticePush(protocol.NoticePush{
+		NoticeID:      result.Notice.ID,
+		DeliveryID:    delivery.ID,
+		Title:         result.Notice.Title,
+		Body:          result.Notice.Body,
+		AttachmentRef: result.Notice.AttachmentRef,
+		CreatedAt:     result.PublishedAt.Unix(),
+	}), nil
+}
+
+func gwNoticeMeta(result PublishResult, delivery Delivery) map[string]string {
+	meta := map[string]string{
+		"notice_id": result.Notice.ID,
+		"kind":      result.Notice.Kind,
+	}
+	if result.Notice.ShardID != "" {
+		meta["shard_id"] = result.Notice.ShardID
+	}
+	if delivery.ID != "" {
+		meta["delivery_id"] = delivery.ID
+	}
+	if delivery.AccountID != "" {
+		meta["account_id"] = delivery.AccountID
+	}
+	return meta
+}
+
+type FanoutPublisher struct {
+	Publishers []LivePublisher
+}
+
+func NewFanoutPublisher(publishers ...LivePublisher) FanoutPublisher {
+	return FanoutPublisher{Publishers: publishers}
+}
+
+func (p FanoutPublisher) PublishNotice(ctx context.Context, result PublishResult) error {
+	var errs []error
+	for _, publisher := range p.Publishers {
+		if publisher == nil {
+			continue
+		}
+		if err := publisher.PublishNotice(ctx, result); err != nil {
+			errs = append(errs, err)
+		}
+	}
+	return errors.Join(errs...)
+}

server/internal/runtime/notice/eventlog.go

@@ -0,0 +1,139 @@
+package notice
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"strconv"
+	"strings"
+	"time"
+
+	"longheng.io/server/internal/platform/eventlog"
+)
+
+const (
+	defaultPublishStream = "notice.publish"
+	defaultPubEventType  = "notice.published"
+)
+
+type publishEventPayload struct {
+	Notice         Notice            `json:"notice"`
+	Deliveries     []Delivery        `json:"deliveries,omitempty"`
+	IdempotencyKey string            `json:"idempotency_key"`
+	AdminReceiptID string            `json:"admin_receipt_id,omitempty"`
+	Meta           map[string]string `json:"meta,omitempty"`
+	PublishedAt    time.Time         `json:"published_at"`
+}
+
+func (s Service) lookupPublishEvent(ctx context.Context, request PublishRequest) (PublishResult, bool, error) {
+	if s.EventLog == nil {
+		return PublishResult{}, false, nil
+	}
+	event, ok, err := s.EventLog.GetByIdempotencyKey(ctx, publishEventKey(request.Notice.ID, request.IdempotencyKey))
+	if err != nil || !ok {
+		return PublishResult{}, false, err
+	}
+	result, err := publishResultEvent(event)
+	if err != nil {
+		return PublishResult{}, false, err
+	}
+	if publishReplayClash(result, request) {
+		return PublishResult{}, false, ErrIdempotencyConflict
+	}
+	result.Duplicate = true
+	return result, true, nil
+}
+
+func (s Service) appendPublishEvent(ctx context.Context, result PublishResult) error {
+	if s.EventLog == nil {
+		return nil
+	}
+	payload, err := json.Marshal(payloadFromResult(result))
+	if err != nil {
+		return err
+	}
+	_, err = s.EventLog.Append(ctx, eventlog.Event{
+		ID:             publishEventID(result.Notice.ID, result.IdempotencyKey),
+		Stream:         s.publishEventStream(),
+		Type:           s.publishEventType(),
+		AggregateID:    result.Notice.ID,
+		IdempotencyKey: publishEventKey(result.Notice.ID, result.IdempotencyKey),
+		Payload:        payload,
+		Headers: map[string]string{
+			"notice_id":        result.Notice.ID,
+			"kind":             result.Notice.Kind,
+			"recipient_count":  strconv.Itoa(len(result.Deliveries)),
+			"admin_receipt_id": result.AdminReceiptID,
+		},
+	})
+	if errors.Is(err, eventlog.ErrIdempotencyConflict) {
+		return ErrIdempotencyConflict
+	}
+	return err
+}
+
+func (s Service) publishEventStream() string {
+	if stream := strings.TrimSpace(s.EventLogStream); stream != "" {
+		return stream
+	}
+	return defaultPublishStream
+}
+
+func (s Service) publishEventType() string {
+	if typ := strings.TrimSpace(s.EventLogType); typ != "" {
+		return typ
+	}
+	return defaultPubEventType
+}
+
+func payloadFromResult(result PublishResult) publishEventPayload {
+	return publishEventPayload{
+		Notice:         cloneNotice(result.Notice),
+		Deliveries:     cloneDeliveries(result.Deliveries),
+		IdempotencyKey: result.IdempotencyKey,
+		AdminReceiptID: result.AdminReceiptID,
+		Meta:           cloneStringMap(result.Meta),
+		PublishedAt:    result.PublishedAt,
+	}
+}
+
+func publishResultEvent(event eventlog.Event) (PublishResult, error) {
+	var payload publishEventPayload
+	if err := json.Unmarshal(event.Payload, &payload); err != nil {
+		return PublishResult{}, err
+	}
+	return PublishResult{
+		Accepted:       true,
+		Notice:         cloneNotice(payload.Notice),
+		Deliveries:     cloneDeliveries(payload.Deliveries),
+		IdempotencyKey: firstNonEmpty(payload.IdempotencyKey, event.IdempotencyKey),
+		AdminReceiptID: payload.AdminReceiptID,
+		Meta:           cloneStringMap(payload.Meta),
+		PublishedAt:    payload.PublishedAt,
+	}, nil
+}
+
+func publishEventKey(noticeID, key string) string {
+	noticeID = strings.TrimSpace(noticeID)
+	key = strings.TrimSpace(key)
+	if noticeID == "" || key == "" {
+		return ""
+	}
+	return strings.Join([]string{"notice", "publish", "v1", encodeEventKeyPart(noticeID), encodeEventKeyPart(key)}, ":")
+}
+
+func encodeEventKeyPart(value string) string {
+	value = strings.TrimSpace(value)
+	if value == "" {
+		return "_"
+	}
+	return base64.RawURLEncoding.EncodeToString([]byte(value))
+}
+
+func publishEventID(noticeID, key string) string {
+	sum := sha256.Sum256([]byte(publishEventKey(noticeID, key)))
+	return "notice-publish-" + hex.EncodeToString(sum[:8])
+}

server/internal/runtime/notice/notice.go

@@ -0,0 +1,949 @@
+package notice
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"reflect"
+	"sort"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+
+	"longheng.io/server/internal/platform/admincmd"
+	"longheng.io/server/internal/platform/eventlog"
+)
+
+var (
+	ErrStoreRequired        = errors.New("notice store is required")
+	ErrNoticeIDRequired     = errors.New("notice id is required")
+	ErrNoticeContentEmpty   = errors.New("notice title or body is required")
+	ErrRecipientRequired    = errors.New("notice recipient is required")
+	ErrIdempotencyRequired  = errors.New("notice idempotency key is required")
+	ErrIdempotencyConflict  = errors.New("notice idempotency conflict")
+	ErrNoticeExists         = errors.New("notice already exists")
+	ErrNoticeNotFound       = errors.New("notice not found")
+	ErrDeliveryNotFound     = errors.New("notice delivery not found")
+	ErrNoticeInactive       = errors.New("notice is inactive")
+	ErrInvalidNotice        = errors.New("notice is invalid")
+	ErrInvalidNoticeKind    = errors.New("notice kind is invalid")
+	ErrInvalidNoticeRequest = errors.New("notice request is invalid")
+	ErrLivePublisherMissing = errors.New("notice live publisher is missing")
+)
+
+const (
+	KindDirect       = "direct"
+	KindAnnouncement = "announcement"
+
+	StatusPending      = "pending"
+	StatusAcknowledged = "acknowledged"
+	StatusDeleted      = "deleted"
+
+	defaultListLimit = 100
+	maxListLimit     = 100
+	rollbackTimeout  = 5 * time.Second
+)
+
+type Notice struct {
+	ID            string            `json:"id"`
+	Kind          string            `json:"kind"`
+	Scope         string            `json:"scope,omitempty"`
+	ShardID       string            `json:"shard_id,omitempty"`
+	Title         string            `json:"title,omitempty"`
+	Body          string            `json:"body,omitempty"`
+	AttachmentRef string            `json:"attachment_ref,omitempty"`
+	StartsAt      time.Time         `json:"starts_at,omitempty"`
+	EndsAt        time.Time         `json:"ends_at,omitempty"`
+	Disabled      bool              `json:"disabled,omitempty"`
+	Meta          map[string]string `json:"meta,omitempty"`
+}
+
+type PublishRequest struct {
+	Notice         Notice            `json:"notice"`
+	Recipients     []string          `json:"recipients,omitempty"`
+	IdempotencyKey string            `json:"idempotency_key"`
+	Meta           map[string]string `json:"meta,omitempty"`
+	AdminCommand   *admincmd.Command `json:"admin_command,omitempty"`
+}
+
+type PublishResult struct {
+	Accepted       bool              `json:"accepted"`
+	Duplicate      bool              `json:"duplicate,omitempty"`
+	Notice         Notice            `json:"notice"`
+	Deliveries     []Delivery        `json:"deliveries,omitempty"`
+	IdempotencyKey string            `json:"idempotency_key"`
+	AdminReceiptID string            `json:"admin_receipt_id,omitempty"`
+	Meta           map[string]string `json:"meta,omitempty"`
+	PublishedAt    time.Time         `json:"published_at"`
+	Live           LiveStatus        `json:"live,omitempty"`
+}
+
+type LiveStatus struct {
+	Attempted bool   `json:"attempted,omitempty"`
+	Delivered bool   `json:"delivered,omitempty"`
+	Error     string `json:"error,omitempty"`
+}
+
+type Delivery struct {
+	ID             string            `json:"id"`
+	NoticeID       string            `json:"notice_id"`
+	AccountID      string            `json:"account_id"`
+	ShardID        string            `json:"shard_id,omitempty"`
+	Status         string            `json:"status"`
+	AttachmentRef  string            `json:"attachment_ref,omitempty"`
+	IdempotencyKey string            `json:"idempotency_key,omitempty"`
+	Meta           map[string]string `json:"meta,omitempty"`
+	CreatedAt      time.Time         `json:"created_at"`
+	AcknowledgedAt time.Time         `json:"acknowledged_at,omitempty"`
+}
+
+type AcknowledgeRequest struct {
+	DeliveryID     string `json:"delivery_id,omitempty"`
+	NoticeID       string `json:"notice_id,omitempty"`
+	AccountID      string `json:"account_id,omitempty"`
+	IdempotencyKey string `json:"idempotency_key"`
+}
+
+type DeleteRequest struct {
+	DeliveryIDs []string `json:"delivery_ids,omitempty"`
+	NoticeID    string   `json:"notice_id,omitempty"`
+	AccountID   string   `json:"account_id,omitempty"`
+}
+
+type DeleteResult struct {
+	DeletedIDs []string `json:"deleted_ids,omitempty"`
+	MissingIDs []string `json:"missing_ids,omitempty"`
+}
+
+type Query struct {
+	AccountID string    `json:"account_id,omitempty"`
+	ShardID   string    `json:"shard_id,omitempty"`
+	Now       time.Time `json:"now,omitempty"`
+	Limit     int       `json:"limit,omitempty"`
+	Cursor    string    `json:"cursor,omitempty"`
+}
+
+type ListResult struct {
+	Items      []Delivery `json:"items"`
+	NextCursor string     `json:"next_cursor,omitempty"`
+}
+
+type Snapshot struct {
+	Notices         int            `json:"notices"`
+	Deliveries      int            `json:"deliveries"`
+	ByKind          map[string]int `json:"by_kind,omitempty"`
+	ByStatus        map[string]int `json:"by_status,omitempty"`
+	PublishKeys     int            `json:"publish_keys"`
+	AcknowledgeKeys int            `json:"acknowledge_keys"`
+}
+
+type Store interface {
+	Publish(context.Context, PublishRequest, time.Time) (PublishResult, error)
+	Acknowledge(context.Context, AcknowledgeRequest, time.Time) (Delivery, bool, error)
+	Delete(context.Context, DeleteRequest) (DeleteResult, error)
+	ListForAccount(context.Context, Query) ([]Delivery, error)
+	ActiveAnnouncements(context.Context, Query) ([]Notice, error)
+	Snapshot(context.Context) (Snapshot, error)
+}
+
+type LivePublisher interface {
+	PublishNotice(context.Context, PublishResult) error
+}
+
+type Service struct {
+	Store          Store
+	Publisher      LivePublisher
+	EventLog       *eventlog.Log
+	EventLogStream string
+	EventLogType   string
+	Now            func() time.Time
+}
+
+func (s Service) Publish(ctx context.Context, request PublishRequest) (PublishResult, error) {
+	if err := ctxErr(ctx); err != nil {
+		return PublishResult{}, err
+	}
+	if s.Store == nil {
+		return PublishResult{}, ErrStoreRequired
+	}
+	request = normPublishReq(request)
+	if err := validPublishReq(request); err != nil {
+		return PublishResult{}, err
+	}
+	if request.AdminCommand != nil {
+		command := *request.AdminCommand
+		command.Operation = firstNonEmpty(command.Operation, "notice.publish")
+		command.Scope = firstNonEmpty(command.Scope, "notice")
+		command.Target = firstNonEmpty(command.Target, request.Notice.ID)
+		command.Params = mergeCommandParams(command.Params, request)
+		if err := admincmd.Validate(command, admincmd.DangerousPolicy()); err != nil {
+			return PublishResult{}, err
+		}
+		receipt, err := admincmd.NewReceipt(command, "accepted", s.now())
+		if err != nil {
+			return PublishResult{}, err
+		}
+		request.AdminCommand = &command
+		request.Meta = mergeStringMap(request.Meta, map[string]string{"admin_receipt_id": receipt.ID})
+	}
+	if result, ok, err := s.lookupPublishEvent(ctx, request); err != nil || ok {
+		return result, err
+	}
+	result, err := s.Store.Publish(ctx, request, s.now())
+	if err != nil {
+		return result, err
+	}
+	if err := s.appendPublishEvent(ctx, result); err != nil {
+		return result, errors.Join(err, s.rollbackPublish(ctx, result))
+	}
+	if result.Duplicate || s.Publisher == nil {
+		return result, err
+	}
+	result.Live.Attempted = true
+	publishErr := s.Publisher.PublishNotice(ctx, result)
+	if publishErr != nil {
+		result.Live.Error = publishErr.Error()
+	} else {
+		result.Live.Delivered = true
+	}
+	return result, nil
+}
+
+type publishRollbackStore interface {
+	RollbackPublish(context.Context, PublishResult) error
+}
+
+func (s Service) rollbackPublish(ctx context.Context, result PublishResult) error {
+	if result.Duplicate || s.Store == nil {
+		return nil
+	}
+	store, ok := s.Store.(publishRollbackStore)
+	if !ok {
+		return nil
+	}
+	// 可靠性补偿不能继承已取消的请求 ctx，但要保留 trace/value 方便排障。
+	base := context.Background()
+	if ctx != nil {
+		base = context.WithoutCancel(ctx)
+	}
+	rollbackCtx, cancel := context.WithTimeout(base, rollbackTimeout)
+	defer cancel()
+	return store.RollbackPublish(rollbackCtx, result)
+}
+
+func (s Service) Acknowledge(ctx context.Context, request AcknowledgeRequest) (Delivery, bool, error) {
+	if err := ctxErr(ctx); err != nil {
+		return Delivery{}, false, err
+	}
+	if s.Store == nil {
+		return Delivery{}, false, ErrStoreRequired
+	}
+	request = normalizeAckRequest(request)
+	if request.IdempotencyKey == "" {
+		return Delivery{}, false, ErrIdempotencyRequired
+	}
+	if request.DeliveryID == "" && (request.NoticeID == "" || request.AccountID == "") {
+		return Delivery{}, false, ErrInvalidNoticeRequest
+	}
+	return s.Store.Acknowledge(ctx, request, s.now())
+}
+
+func (s Service) Delete(ctx context.Context, request DeleteRequest) (DeleteResult, error) {
+	if err := ctxErr(ctx); err != nil {
+		return DeleteResult{}, err
+	}
+	if s.Store == nil {
+		return DeleteResult{}, ErrStoreRequired
+	}
+	request = normDeleteReq(request)
+	return s.Store.Delete(ctx, request)
+}
+
+func (s Service) ListForAccount(ctx context.Context, query Query) ([]Delivery, error) {
+	if err := ctxErr(ctx); err != nil {
+		return nil, err
+	}
+	if s.Store == nil {
+		return nil, ErrStoreRequired
+	}
+	query.AccountID = strings.TrimSpace(query.AccountID)
+	query.ShardID = strings.TrimSpace(query.ShardID)
+	if query.AccountID == "" {
+		return nil, ErrRecipientRequired
+	}
+	if query.Now.IsZero() {
+		query.Now = s.now()
+	} else {
+		query.Now = query.Now.UTC()
+	}
+	return s.Store.ListForAccount(ctx, query)
+}
+
+func (s Service) ListPageForAccount(ctx context.Context, query Query) (ListResult, error) {
+	deliveries, err := s.ListForAccount(ctx, query)
+	if err != nil {
+		return ListResult{}, err
+	}
+	return paginateDeliveries(deliveries, query), nil
+}
+
+func (s Service) ActiveAnnouncements(ctx context.Context, query Query) ([]Notice, error) {
+	if err := ctxErr(ctx); err != nil {
+		return nil, err
+	}
+	if s.Store == nil {
+		return nil, ErrStoreRequired
+	}
+	query.ShardID = strings.TrimSpace(query.ShardID)
+	if query.Now.IsZero() {
+		query.Now = s.now()
+	} else {
+		query.Now = query.Now.UTC()
+	}
+	return s.Store.ActiveAnnouncements(ctx, query)
+}
+
+func (s Service) Snapshot(ctx context.Context) (Snapshot, error) {
+	if err := ctxErr(ctx); err != nil {
+		return Snapshot{}, err
+	}
+	if s.Store == nil {
+		return Snapshot{}, ErrStoreRequired
+	}
+	return s.Store.Snapshot(ctx)
+}
+
+func (s Service) now() time.Time {
+	if s.Now != nil {
+		return s.Now().UTC()
+	}
+	return time.Now().UTC()
+}
+
+type MemoryStore struct {
+	mu              sync.Mutex
+	notices         map[string]Notice
+	deliveries      map[string]Delivery
+	deliveriesByAcc map[string][]string
+	publishByKey    map[string]PublishResult
+	ackByKey        map[string]string
+}
+
+func NewMemoryStore() *MemoryStore {
+	return &MemoryStore{
+		notices:         make(map[string]Notice),
+		deliveries:      make(map[string]Delivery),
+		deliveriesByAcc: make(map[string][]string),
+		publishByKey:    make(map[string]PublishResult),
+		ackByKey:        make(map[string]string),
+	}
+}
+
+func (s *MemoryStore) Publish(ctx context.Context, request PublishRequest, now time.Time) (PublishResult, error) {
+	if err := ctxErr(ctx); err != nil {
+		return PublishResult{}, err
+	}
+	if s == nil {
+		return PublishResult{}, ErrStoreRequired
+	}
+	request = normPublishReq(request)
+	if err := validPublishReq(request); err != nil {
+		return PublishResult{}, err
+	}
+	now = normalizeNow(now)
+
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	lookupKey := publishLookupKey(request)
+	if existing, ok := s.publishByKey[lookupKey]; ok {
+		if publishReplayClash(existing, request) {
+			return PublishResult{}, ErrIdempotencyConflict
+		}
+		existing.Duplicate = true
+		return clonePublishResult(existing), nil
+	}
+	if _, exists := s.notices[request.Notice.ID]; exists {
+		return PublishResult{}, ErrNoticeExists
+	}
+
+	notice := request.Notice
+	s.notices[notice.ID] = cloneNotice(notice)
+	deliveries := make([]Delivery, 0, len(request.Recipients))
+	for _, accountID := range request.Recipients {
+		delivery := Delivery{
+			ID:             DeliveryID(notice.ID, accountID),
+			NoticeID:       notice.ID,
+			AccountID:      accountID,
+			ShardID:        notice.ShardID,
+			Status:         StatusPending,
+			AttachmentRef:  notice.AttachmentRef,
+			IdempotencyKey: request.IdempotencyKey,
+			Meta:           mergeStringMap(notice.Meta, request.Meta),
+			CreatedAt:      now,
+		}
+		if _, exists := s.deliveries[delivery.ID]; !exists {
+			s.deliveriesByAcc[accountID] = appendUnique(s.deliveriesByAcc[accountID], delivery.ID)
+		}
+		s.deliveries[delivery.ID] = cloneDelivery(delivery)
+		deliveries = append(deliveries, cloneDelivery(delivery))
+	}
+	sortDeliveries(deliveries)
+	result := PublishResult{
+		Accepted:       true,
+		Notice:         cloneNotice(notice),
+		Deliveries:     deliveries,
+		IdempotencyKey: request.IdempotencyKey,
+		AdminReceiptID: request.Meta["admin_receipt_id"],
+		Meta:           cloneStringMap(request.Meta),
+		PublishedAt:    now,
+	}
+	s.publishByKey[lookupKey] = clonePublishResult(result)
+	return clonePublishResult(result), nil
+}
+
+func (s *MemoryStore) RollbackPublish(ctx context.Context, result PublishResult) error {
+	if err := ctxErr(ctx); err != nil {
+		return err
+	}
+	if s == nil {
+		return ErrStoreRequired
+	}
+	if result.Notice.ID == "" || result.IdempotencyKey == "" {
+		return nil
+	}
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	lookupKey := publishLookupKey(PublishRequest{Notice: result.Notice, IdempotencyKey: result.IdempotencyKey})
+	existing, ok := s.publishByKey[lookupKey]
+	if !ok || existing.Notice.ID != result.Notice.ID {
+		return nil
+	}
+	delete(s.publishByKey, lookupKey)
+	rolledBackDeliveries := make(map[string]struct{}, len(result.Deliveries))
+	for _, delivery := range result.Deliveries {
+		rolledBackDeliveries[delivery.ID] = struct{}{}
+		delete(s.deliveries, delivery.ID)
+		s.deliveriesByAcc[delivery.AccountID] = removeString(s.deliveriesByAcc[delivery.AccountID], delivery.ID)
+		if len(s.deliveriesByAcc[delivery.AccountID]) == 0 {
+			delete(s.deliveriesByAcc, delivery.AccountID)
+		}
+	}
+	for key, deliveryID := range s.ackByKey {
+		if _, ok := rolledBackDeliveries[deliveryID]; ok {
+			delete(s.ackByKey, key)
+		}
+	}
+	delete(s.notices, result.Notice.ID)
+	return nil
+}
+
+func (s *MemoryStore) Acknowledge(ctx context.Context, request AcknowledgeRequest, now time.Time) (Delivery, bool, error) {
+	if err := ctxErr(ctx); err != nil {
+		return Delivery{}, false, err
+	}
+	if s == nil {
+		return Delivery{}, false, ErrStoreRequired
+	}
+	request = normalizeAckRequest(request)
+	if request.IdempotencyKey == "" {
+		return Delivery{}, false, ErrIdempotencyRequired
+	}
+	now = normalizeNow(now)
+
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	deliveryID := request.DeliveryID
+	if deliveryID == "" {
+		deliveryID = DeliveryID(request.NoticeID, request.AccountID)
+	}
+	lookupKey := acknowledgeLookupKey(deliveryID, request.IdempotencyKey)
+	if deliveryID == "" {
+		return Delivery{}, false, ErrInvalidNoticeRequest
+	}
+	if knownDeliveryID, ok := s.ackByKey[lookupKey]; ok {
+		deliveryID = knownDeliveryID
+		delivery, exists := s.deliveries[deliveryID]
+		if !exists {
+			return Delivery{}, true, ErrDeliveryNotFound
+		}
+		return cloneDelivery(delivery), true, nil
+	}
+	delivery, ok := s.deliveries[deliveryID]
+	if !ok {
+		return Delivery{}, false, ErrDeliveryNotFound
+	}
+	if delivery.Status == StatusDeleted {
+		return Delivery{}, false, ErrDeliveryNotFound
+	}
+	if delivery.Status == StatusAcknowledged {
+		s.ackByKey[lookupKey] = delivery.ID
+		return cloneDelivery(delivery), true, nil
+	}
+	delivery.Status = StatusAcknowledged
+	delivery.AcknowledgedAt = now
+	s.deliveries[delivery.ID] = cloneDelivery(delivery)
+	s.ackByKey[lookupKey] = delivery.ID
+	return cloneDelivery(delivery), false, nil
+}
+
+func (s *MemoryStore) Delete(ctx context.Context, request DeleteRequest) (DeleteResult, error) {
+	if err := ctxErr(ctx); err != nil {
+		return DeleteResult{}, err
+	}
+	if s == nil {
+		return DeleteResult{}, ErrStoreRequired
+	}
+	request = normDeleteReq(request)
+	if len(request.DeliveryIDs) == 0 {
+		return DeleteResult{}, nil
+	}
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	result := DeleteResult{}
+	for _, id := range request.DeliveryIDs {
+		delivery, ok := s.deliveries[id]
+		if !ok || delivery.Status == StatusDeleted || (request.AccountID != "" && delivery.AccountID != request.AccountID) {
+			result.MissingIDs = append(result.MissingIDs, id)
+			continue
+		}
+		delivery.Status = StatusDeleted
+		s.deliveries[id] = cloneDelivery(delivery)
+		result.DeletedIDs = append(result.DeletedIDs, id)
+	}
+	sort.Strings(result.DeletedIDs)
+	sort.Strings(result.MissingIDs)
+	return result, nil
+}
+
+func (s *MemoryStore) ListForAccount(ctx context.Context, query Query) ([]Delivery, error) {
+	if err := ctxErr(ctx); err != nil {
+		return nil, err
+	}
+	if s == nil {
+		return nil, ErrStoreRequired
+	}
+	query.AccountID = strings.TrimSpace(query.AccountID)
+	query.ShardID = strings.TrimSpace(query.ShardID)
+	if query.AccountID == "" {
+		return nil, ErrRecipientRequired
+	}
+	now := normalizeNow(query.Now)
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	ids := append([]string(nil), s.deliveriesByAcc[query.AccountID]...)
+	out := make([]Delivery, 0, len(ids))
+	for _, id := range ids {
+		delivery, ok := s.deliveries[id]
+		if !ok {
+			continue
+		}
+		notice, ok := s.notices[delivery.NoticeID]
+		if !ok || !noticeVisible(notice, query.ShardID, now) {
+			continue
+		}
+		if delivery.Status == StatusDeleted {
+			continue
+		}
+		out = append(out, cloneDelivery(delivery))
+	}
+	sortAcctDeliveries(out)
+	return out, nil
+}
+
+func (s *MemoryStore) ActiveAnnouncements(ctx context.Context, query Query) ([]Notice, error) {
+	if err := ctxErr(ctx); err != nil {
+		return nil, err
+	}
+	if s == nil {
+		return nil, ErrStoreRequired
+	}
+	query.ShardID = strings.TrimSpace(query.ShardID)
+	now := normalizeNow(query.Now)
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	out := make([]Notice, 0)
+	for _, notice := range s.notices {
+		if notice.Kind != KindAnnouncement || !noticeVisible(notice, query.ShardID, now) {
+			continue
+		}
+		out = append(out, cloneNotice(notice))
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].ID < out[j].ID })
+	return out, nil
+}
+
+func (s *MemoryStore) Snapshot(ctx context.Context) (Snapshot, error) {
+	if err := ctxErr(ctx); err != nil {
+		return Snapshot{}, err
+	}
+	if s == nil {
+		return Snapshot{}, ErrStoreRequired
+	}
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	snapshot := Snapshot{
+		Notices:         len(s.notices),
+		Deliveries:      len(s.deliveries),
+		ByKind:          make(map[string]int),
+		ByStatus:        make(map[string]int),
+		PublishKeys:     len(s.publishByKey),
+		AcknowledgeKeys: len(s.ackByKey),
+	}
+	for _, notice := range s.notices {
+		snapshot.ByKind[notice.Kind]++
+	}
+	for _, delivery := range s.deliveries {
+		snapshot.ByStatus[delivery.Status]++
+	}
+	if len(snapshot.ByKind) == 0 {
+		snapshot.ByKind = nil
+	}
+	if len(snapshot.ByStatus) == 0 {
+		snapshot.ByStatus = nil
+	}
+	return snapshot, nil
+}
+
+func validPublishReq(request PublishRequest) error {
+	notice := request.Notice
+	if notice.ID == "" {
+		return ErrNoticeIDRequired
+	}
+	if notice.Title == "" && notice.Body == "" {
+		return ErrNoticeContentEmpty
+	}
+	if request.IdempotencyKey == "" {
+		return ErrIdempotencyRequired
+	}
+	switch notice.Kind {
+	case KindDirect:
+		if len(request.Recipients) == 0 {
+			return ErrRecipientRequired
+		}
+	case KindAnnouncement:
+	default:
+		return fmt.Errorf("%w: %s", ErrInvalidNoticeKind, notice.Kind)
+	}
+	if !notice.StartsAt.IsZero() && !notice.EndsAt.IsZero() && notice.EndsAt.Before(notice.StartsAt) {
+		return fmt.Errorf("%w: ends_at is before starts_at", ErrInvalidNotice)
+	}
+	return nil
+}
+
+func normPublishReq(request PublishRequest) PublishRequest {
+	request.Notice = normalizeNotice(request.Notice)
+	request.Recipients = normalizeIDs(request.Recipients)
+	request.IdempotencyKey = strings.TrimSpace(request.IdempotencyKey)
+	request.Meta = normalizeStringMap(request.Meta)
+	return request
+}
+
+func normalizeNotice(notice Notice) Notice {
+	notice.ID = strings.TrimSpace(notice.ID)
+	notice.Kind = strings.ToLower(strings.TrimSpace(notice.Kind))
+	if notice.Kind == "" {
+		notice.Kind = KindDirect
+	}
+	notice.Scope = strings.TrimSpace(notice.Scope)
+	notice.ShardID = strings.TrimSpace(notice.ShardID)
+	notice.Title = strings.TrimSpace(notice.Title)
+	notice.Body = strings.TrimSpace(notice.Body)
+	notice.AttachmentRef = strings.TrimSpace(notice.AttachmentRef)
+	notice.StartsAt = normalizeTime(notice.StartsAt)
+	notice.EndsAt = normalizeTime(notice.EndsAt)
+	notice.Meta = normalizeStringMap(notice.Meta)
+	return notice
+}
+
+func normalizeAckRequest(request AcknowledgeRequest) AcknowledgeRequest {
+	request.DeliveryID = strings.TrimSpace(request.DeliveryID)
+	request.NoticeID = strings.TrimSpace(request.NoticeID)
+	request.AccountID = strings.TrimSpace(request.AccountID)
+	request.IdempotencyKey = strings.TrimSpace(request.IdempotencyKey)
+	return request
+}
+
+func normDeleteReq(request DeleteRequest) DeleteRequest {
+	request.NoticeID = strings.TrimSpace(request.NoticeID)
+	request.AccountID = strings.TrimSpace(request.AccountID)
+	request.DeliveryIDs = normalizeIDs(request.DeliveryIDs)
+	if len(request.DeliveryIDs) == 0 && request.NoticeID != "" && request.AccountID != "" {
+		request.DeliveryIDs = []string{DeliveryID(request.NoticeID, request.AccountID)}
+	}
+	return request
+}
+
+func noticeVisible(notice Notice, shardID string, now time.Time) bool {
+	if notice.Disabled {
+		return false
+	}
+	if notice.ShardID != "" && shardID != "" && notice.ShardID != shardID {
+		return false
+	}
+	if !notice.StartsAt.IsZero() && now.Before(notice.StartsAt) {
+		return false
+	}
+	if !notice.EndsAt.IsZero() && now.After(notice.EndsAt) {
+		return false
+	}
+	return true
+}
+
+func DeliveryID(noticeID, accountID string) string {
+	seed := encodeNoticeKey(strings.TrimSpace(noticeID), strings.TrimSpace(accountID))
+	sum := sha256.Sum256([]byte(seed))
+	return hex.EncodeToString(sum[:16])
+}
+
+func publishLookupKey(request PublishRequest) string {
+	return encodeNoticeKey(strings.TrimSpace(request.Notice.ID), strings.TrimSpace(request.IdempotencyKey))
+}
+
+func publishReplayClash(existing PublishResult, request PublishRequest) bool {
+	if !reflect.DeepEqual(existing.Notice, request.Notice) {
+		return true
+	}
+	if !reflect.DeepEqual(publishRecipients(existing.Deliveries), request.Recipients) {
+		return true
+	}
+	if !reflect.DeepEqual(existing.Meta, request.Meta) {
+		return true
+	}
+	return false
+}
+
+func publishRecipients(deliveries []Delivery) []string {
+	if len(deliveries) == 0 {
+		return nil
+	}
+	out := make([]string, 0, len(deliveries))
+	for _, delivery := range deliveries {
+		out = append(out, delivery.AccountID)
+	}
+	sort.Strings(out)
+	return out
+}
+
+func acknowledgeLookupKey(deliveryID, key string) string {
+	return encodeNoticeKey(strings.TrimSpace(deliveryID), strings.TrimSpace(key))
+}
+
+// encodeNoticeKey 用长度前缀编码多段内部键，避免字段自带分隔符或控制字符时发生碰撞。
+func encodeNoticeKey(parts ...string) string {
+	var builder strings.Builder
+	for _, part := range parts {
+		builder.WriteString(strconv.Itoa(len(part)))
+		builder.WriteByte(':')
+		builder.WriteString(part)
+	}
+	return builder.String()
+}
+
+func mergeCommandParams(params map[string]any, request PublishRequest) map[string]any {
+	out := make(map[string]any, len(params)+5)
+	for key, value := range params {
+		out[key] = value
+	}
+	out["notice_id"] = request.Notice.ID
+	out["kind"] = request.Notice.Kind
+	out["shard_id"] = request.Notice.ShardID
+	out["recipient_count"] = len(request.Recipients)
+	out["idempotency_key"] = request.IdempotencyKey
+	return out
+}
+
+func normalizeIDs(values []string) []string {
+	seen := make(map[string]struct{}, len(values))
+	out := make([]string, 0, len(values))
+	for _, value := range values {
+		value = strings.TrimSpace(value)
+		if value == "" {
+			continue
+		}
+		if _, ok := seen[value]; ok {
+			continue
+		}
+		seen[value] = struct{}{}
+		out = append(out, value)
+	}
+	sort.Strings(out)
+	return out
+}
+
+func appendUnique(values []string, value string) []string {
+	for _, existing := range values {
+		if existing == value {
+			return values
+		}
+	}
+	return append(values, value)
+}
+
+func removeString(values []string, value string) []string {
+	if len(values) == 0 {
+		return nil
+	}
+	out := values[:0]
+	for _, existing := range values {
+		if existing != value {
+			out = append(out, existing)
+		}
+	}
+	return out
+}
+
+func firstNonEmpty(values ...string) string {
+	for _, value := range values {
+		value = strings.TrimSpace(value)
+		if value != "" {
+			return value
+		}
+	}
+	return ""
+}
+
+func normalizeNow(value time.Time) time.Time {
+	if value.IsZero() {
+		return time.Now().UTC()
+	}
+	return value.UTC()
+}
+
+func normalizeTime(value time.Time) time.Time {
+	if value.IsZero() {
+		return time.Time{}
+	}
+	return value.UTC()
+}
+
+func normalizeStringMap(values map[string]string) map[string]string {
+	if len(values) == 0 {
+		return nil
+	}
+	out := make(map[string]string, len(values))
+	for key, value := range values {
+		key = strings.TrimSpace(key)
+		if key == "" {
+			continue
+		}
+		out[key] = strings.TrimSpace(value)
+	}
+	if len(out) == 0 {
+		return nil
+	}
+	return out
+}
+
+func mergeStringMap(base map[string]string, overlays ...map[string]string) map[string]string {
+	out := cloneStringMap(base)
+	for _, overlay := range overlays {
+		for key, value := range overlay {
+			if out == nil {
+				out = make(map[string]string)
+			}
+			out[key] = value
+		}
+	}
+	return out
+}
+
+func cloneNotice(notice Notice) Notice {
+	notice.Meta = cloneStringMap(notice.Meta)
+	return notice
+}
+
+func cloneDelivery(delivery Delivery) Delivery {
+	delivery.Meta = cloneStringMap(delivery.Meta)
+	return delivery
+}
+
+func clonePublishResult(result PublishResult) PublishResult {
+	result.Notice = cloneNotice(result.Notice)
+	result.Deliveries = cloneDeliveries(result.Deliveries)
+	result.Meta = cloneStringMap(result.Meta)
+	return result
+}
+
+func cloneDeliveries(in []Delivery) []Delivery {
+	if len(in) == 0 {
+		return nil
+	}
+	out := make([]Delivery, len(in))
+	for idx, delivery := range in {
+		out[idx] = cloneDelivery(delivery)
+	}
+	return out
+}
+
+func cloneStringMap(values map[string]string) map[string]string {
+	if len(values) == 0 {
+		return nil
+	}
+	out := make(map[string]string, len(values))
+	for key, value := range values {
+		out[key] = value
+	}
+	return out
+}
+
+func sortDeliveries(deliveries []Delivery) {
+	sort.Slice(deliveries, func(i, j int) bool {
+		if deliveries[i].AccountID != deliveries[j].AccountID {
+			return deliveries[i].AccountID < deliveries[j].AccountID
+		}
+		return deliveries[i].ID < deliveries[j].ID
+	})
+}
+
+func sortAcctDeliveries(deliveries []Delivery) {
+	sort.Slice(deliveries, func(i, j int) bool {
+		if !deliveries[i].CreatedAt.Equal(deliveries[j].CreatedAt) {
+			return deliveries[i].CreatedAt.Before(deliveries[j].CreatedAt)
+		}
+		return deliveries[i].ID < deliveries[j].ID
+	})
+}
+
+func paginateDeliveries(deliveries []Delivery, query Query) ListResult {
+	sortAcctDeliveries(deliveries)
+	limit := query.Limit
+	if limit <= 0 {
+		limit = defaultListLimit
+	}
+	if limit > maxListLimit {
+		limit = maxListLimit
+	}
+	cursor := strings.TrimSpace(query.Cursor)
+	start := 0
+	if cursor != "" {
+		for idx, delivery := range deliveries {
+			if delivery.ID == cursor {
+				start = idx + 1
+				break
+			}
+		}
+	}
+	end := start + limit
+	if end > len(deliveries) {
+		end = len(deliveries)
+	}
+	items := cloneDeliveries(deliveries[start:end])
+	nextCursor := ""
+	if end < len(deliveries) && len(items) > 0 {
+		nextCursor = items[len(items)-1].ID
+	}
+	return ListResult{Items: items, NextCursor: nextCursor}
+}
+
+func ctxErr(ctx context.Context) error {
+	if ctx == nil {
+		return nil
+	}
+	return ctx.Err()
+}

server/internal/runtime/notice/onlinepush_publisher.go

@@ -0,0 +1,130 @@
+package notice
+
+import (
+	"context"
+	"encoding/base64"
+	"errors"
+	"strings"
+
+	"longheng.io/server/internal/platform/onlinepush"
+	"longheng.io/server/pkg/protocol"
+)
+
+type OnlinePushSender interface {
+	Send(context.Context, onlinepush.Request) (onlinepush.Receipt, error)
+}
+
+type OnlinePushPublisherOptions struct {
+	Sender                 OnlinePushSender
+	PacketID               int32
+	MsgID                  uint32
+	WireFormat             string
+	Encode                 GatewayPushEncoder
+	BroadcastAnnouncements bool
+	OfflinePolicy          string
+	IdempotencyPrefix      string
+}
+
+type OnlinePushPublisher struct {
+	options OnlinePushPublisherOptions
+}
+
+func NewOnlinePushPublisher(sender OnlinePushSender) *OnlinePushPublisher {
+	return NewOnlinePushPublisherWithOptions(OnlinePushPublisherOptions{Sender: sender})
+}
+
+func NewOnlinePushPublisherWithOptions(options OnlinePushPublisherOptions) *OnlinePushPublisher {
+	if options.PacketID == 0 {
+		options.PacketID = protocol.PacketIDContent
+	}
+	if options.MsgID == 0 {
+		options.MsgID = protocol.MessageNoticePush
+	}
+	if options.Encode == nil {
+		options.Encode = EncodeGatewayNoticePush
+	}
+	if strings.TrimSpace(options.OfflinePolicy) == "" {
+		options.OfflinePolicy = onlinepush.OfflineStore
+	}
+	if strings.TrimSpace(options.IdempotencyPrefix) == "" {
+		options.IdempotencyPrefix = "notice-live"
+	}
+	return &OnlinePushPublisher{options: options}
+}
+
+func (p *OnlinePushPublisher) PublishNotice(ctx context.Context, result PublishResult) error {
+	if err := ctxErr(ctx); err != nil {
+		return err
+	}
+	if p == nil || p.options.Sender == nil {
+		return ErrLivePublisherMissing
+	}
+	if result.Notice.Kind == KindAnnouncement && len(result.Deliveries) == 0 && p.options.BroadcastAnnouncements {
+		body, err := p.options.Encode(result, Delivery{})
+		if err != nil {
+			return err
+		}
+		_, err = p.options.Sender.Send(ctx, onlinepush.Request{
+			IdempotencyKey: p.idempotencyKey(result, Delivery{}, "announcement"),
+			Broadcast:      true,
+			PacketID:       p.options.PacketID,
+			MsgID:          p.options.MsgID,
+			WireFormat:     p.options.WireFormat,
+			Body:           body,
+			Metadata:       gwNoticeMeta(result, Delivery{}),
+			Note:           "notice-announcement-push",
+			OfflinePolicy:  onlinepush.OfflineDrop,
+			CreatedAt:      result.PublishedAt,
+		})
+		return err
+	}
+	var errs []error
+	for _, delivery := range result.Deliveries {
+		body, err := p.options.Encode(result, delivery)
+		if err != nil {
+			errs = append(errs, err)
+			continue
+		}
+		_, err = p.options.Sender.Send(ctx, onlinepush.Request{
+			IdempotencyKey: p.idempotencyKey(result, delivery, "direct"),
+			AccountID:      delivery.AccountID,
+			PacketID:       p.options.PacketID,
+			MsgID:          p.options.MsgID,
+			WireFormat:     p.options.WireFormat,
+			Body:           body,
+			Metadata:       gwNoticeMeta(result, delivery),
+			Note:           "notice-direct-push",
+			OfflinePolicy:  p.options.OfflinePolicy,
+			CreatedAt:      result.PublishedAt,
+		})
+		if err != nil {
+			errs = append(errs, err)
+		}
+	}
+	return errors.Join(errs...)
+}
+
+func (p *OnlinePushPublisher) idempotencyKey(result PublishResult, delivery Delivery, suffix string) string {
+	parts := []string{
+		encodePushKeyPart(p.options.IdempotencyPrefix),
+		encodePushKeyPart(result.IdempotencyKey),
+		encodePushKeyPart(result.Notice.ID),
+		encodePushKeyPart(delivery.ID),
+		encodePushKeyPart(suffix),
+	}
+	out := make([]string, 0, len(parts))
+	for _, part := range parts {
+		if part != "" {
+			out = append(out, part)
+		}
+	}
+	return strings.Join(out, ":")
+}
+
+func encodePushKeyPart(value string) string {
+	value = strings.TrimSpace(value)
+	if value == "" {
+		return ""
+	}
+	return base64.RawURLEncoding.EncodeToString([]byte(value))
+}

server/internal/runtime/notice/sql_store.go

@@ -0,0 +1,691 @@
+package notice
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"fmt"
+	"sort"
+	"strings"
+	"time"
+)
+
+var (
+	ErrNoticeSQLDBRequired = errors.New("notice sql db is required")
+	ErrNoticeInvalidTable  = errors.New("notice sql table name is invalid")
+	ErrNoticeInvalidRows   = errors.New("notice sql rows are invalid")
+)
+
+const defSQLTablePrefix = "notice"
+
+type SQLRows interface {
+	Next() bool
+	Scan(...any) error
+	Close() error
+	Err() error
+}
+
+type SQLTx interface {
+	ExecContext(context.Context, string, ...any) (sql.Result, error)
+	QueryContext(context.Context, string, ...any) (SQLRows, error)
+	Commit() error
+	Rollback() error
+}
+
+type SQLDB interface {
+	ExecContext(context.Context, string, ...any) (sql.Result, error)
+	QueryContext(context.Context, string, ...any) (SQLRows, error)
+	BeginTx(context.Context, *sql.TxOptions) (SQLTx, error)
+}
+
+type SQLDBAdapter struct {
+	DB *sql.DB
+}
+
+type SQLTxAdapter struct {
+	Tx *sql.Tx
+}
+
+var (
+	_ SQLDB = SQLDBAdapter{}
+	_ SQLTx = SQLTxAdapter{}
+)
+
+func (a SQLDBAdapter) ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error) {
+	if a.DB == nil {
+		return nil, ErrNoticeSQLDBRequired
+	}
+	return a.DB.ExecContext(ctx, query, args...)
+}
+
+func (a SQLDBAdapter) QueryContext(ctx context.Context, query string, args ...any) (SQLRows, error) { //nolint:rowserrcheck // 适配层只返回 rows，调用方负责遍历结束后的 Err 检查。
+	if a.DB == nil {
+		return nil, ErrNoticeSQLDBRequired
+	}
+	return a.DB.QueryContext(ctx, query, args...) //nolint:rowserrcheck // rows 返回后由上层统一关闭并检查 Err。
+}
+
+func (a SQLDBAdapter) BeginTx(ctx context.Context, options *sql.TxOptions) (SQLTx, error) {
+	if a.DB == nil {
+		return nil, ErrNoticeSQLDBRequired
+	}
+	tx, err := a.DB.BeginTx(ctx, options)
+	if err != nil {
+		return nil, err
+	}
+	return SQLTxAdapter{Tx: tx}, nil
+}
+
+func (a SQLTxAdapter) ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error) {
+	if a.Tx == nil {
+		return nil, ErrNoticeSQLDBRequired
+	}
+	return a.Tx.ExecContext(ctx, query, args...)
+}
+
+func (a SQLTxAdapter) QueryContext(ctx context.Context, query string, args ...any) (SQLRows, error) { //nolint:rowserrcheck // 事务适配层只透传 rows，调用方负责遍历结束后的 Err 检查。
+	if a.Tx == nil {
+		return nil, ErrNoticeSQLDBRequired
+	}
+	return a.Tx.QueryContext(ctx, query, args...) //nolint:rowserrcheck // rows 返回后由上层统一关闭并检查 Err。
+}
+
+func (a SQLTxAdapter) Commit() error {
+	if a.Tx == nil {
+		return ErrNoticeSQLDBRequired
+	}
+	return a.Tx.Commit()
+}
+
+func (a SQLTxAdapter) Rollback() error {
+	if a.Tx == nil {
+		return ErrNoticeSQLDBRequired
+	}
+	return a.Tx.Rollback()
+}
+
+type SQLStoreOptions struct {
+	Name                string
+	TablePrefix         string
+	NoticeTable         string
+	DeliveryTable       string
+	PublishKeyTable     string
+	AcknowledgeKeyTable string
+}
+
+type SQLStore struct {
+	name       string
+	db         SQLDB
+	notices    string
+	deliveries string
+	publish    string
+	ack        string
+	closer     interface{ Close() error }
+}
+
+func NewSQLStore(db SQLDB, options SQLStoreOptions) (*SQLStore, error) {
+	if db == nil {
+		return nil, ErrNoticeSQLDBRequired
+	}
+	tables, err := normSQLStoreTables(options)
+	if err != nil {
+		return nil, err
+	}
+	name := strings.TrimSpace(options.Name)
+	if name == "" {
+		name = "sql-notice"
+	}
+	return &SQLStore{
+		name:       name,
+		db:         db,
+		notices:    tables.notices,
+		deliveries: tables.deliveries,
+		publish:    tables.publish,
+		ack:        tables.ack,
+	}, nil
+}
+
+func NewSQLStoreFromDB(db *sql.DB, options SQLStoreOptions) (*SQLStore, error) {
+	if db == nil {
+		return nil, ErrNoticeSQLDBRequired
+	}
+	store, err := NewSQLStore(SQLDBAdapter{DB: db}, options)
+	if err != nil {
+		return nil, err
+	}
+	store.closer = db
+	return store, nil
+}
+
+func (s *SQLStore) Close() error {
+	if s == nil || s.closer == nil {
+		return nil
+	}
+	return s.closer.Close()
+}
+
+func (s *SQLStore) EnsureSchema(ctx context.Context) error {
+	if err := ctxErr(ctx); err != nil {
+		return err
+	}
+	ctx = sqlContext(ctx)
+	if s == nil || s.db == nil {
+		return ErrNoticeSQLDBRequired
+	}
+	for _, schema := range s.Schema() {
+		if _, err := s.db.ExecContext(ctx, schema); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func (s *SQLStore) Schema() []string {
+	noticeTable := quoteSQLIdentifier(s.notices)
+	deliveryTable := quoteSQLIdentifier(s.deliveries)
+	publishTable := quoteSQLIdentifier(s.publish)
+	ackTable := quoteSQLIdentifier(s.ack)
+	return []string{
+		fmt.Sprintf(`CREATE TABLE IF NOT EXISTS %s (
+  id VARCHAR(128) NOT NULL,
+  kind VARCHAR(32) NOT NULL,
+  scope VARCHAR(128) NOT NULL DEFAULT '',
+  shard_id VARCHAR(128) NOT NULL DEFAULT '',
+  title VARCHAR(255) NOT NULL DEFAULT '',
+  body TEXT NULL,
+  attachment_ref VARCHAR(255) NOT NULL DEFAULT '',
+  starts_at DATETIME(6) NULL,
+  ends_at DATETIME(6) NULL,
+  disabled BOOLEAN NOT NULL DEFAULT FALSE,
+  meta_json JSON NULL,
+  published_at DATETIME(6) NOT NULL,
+  PRIMARY KEY (id),
+  KEY idx_notice_kind (kind, shard_id, starts_at, ends_at)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`, noticeTable),
+		fmt.Sprintf(`CREATE TABLE IF NOT EXISTS %s (
+  id VARCHAR(64) NOT NULL,
+  notice_id VARCHAR(128) NOT NULL,
+  account_id VARCHAR(128) NOT NULL,
+  shard_id VARCHAR(128) NOT NULL DEFAULT '',
+  status VARCHAR(32) NOT NULL,
+  attachment_ref VARCHAR(255) NOT NULL DEFAULT '',
+  idempotency_key VARCHAR(191) NOT NULL DEFAULT '',
+  meta_json JSON NULL,
+  created_at DATETIME(6) NOT NULL,
+  acknowledged_at DATETIME(6) NULL,
+  PRIMARY KEY (id),
+  KEY idx_notice_delivery_account (account_id, status, created_at),
+  KEY idx_notice_delivery_notice (notice_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`, deliveryTable),
+		fmt.Sprintf(`CREATE TABLE IF NOT EXISTS %s (
+  lookup_key CHAR(64) NOT NULL,
+  notice_id VARCHAR(128) NOT NULL,
+  idempotency_key VARCHAR(191) NOT NULL,
+  meta_json JSON NULL,
+  created_at DATETIME(6) NOT NULL,
+  PRIMARY KEY (lookup_key),
+  KEY idx_notice_publish_notice (notice_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`, publishTable),
+		fmt.Sprintf(`CREATE TABLE IF NOT EXISTS %s (
+  lookup_key CHAR(64) NOT NULL,
+  delivery_id VARCHAR(64) NOT NULL,
+  idempotency_key VARCHAR(191) NOT NULL,
+  created_at DATETIME(6) NOT NULL,
+  PRIMARY KEY (lookup_key),
+  KEY idx_notice_ack_delivery (delivery_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`, ackTable),
+	}
+}
+
+func (s *SQLStore) Publish(ctx context.Context, request PublishRequest, now time.Time) (PublishResult, error) {
+	if err := ctxErr(ctx); err != nil {
+		return PublishResult{}, err
+	}
+	ctx = sqlContext(ctx)
+	if s == nil || s.db == nil {
+		return PublishResult{}, ErrNoticeSQLDBRequired
+	}
+	request = normPublishReq(request)
+	if err := validPublishReq(request); err != nil {
+		return PublishResult{}, err
+	}
+	now = normalizeNow(now)
+
+	tx, err := s.db.BeginTx(ctx, nil)
+	if err != nil {
+		return PublishResult{}, err
+	}
+	committed := false
+	defer func() {
+		if !committed {
+			_ = tx.Rollback()
+		}
+	}()
+
+	lookupKey := sqlLookupKey(publishLookupKey(request))
+	if existingNoticeID, ok, err := s.lookupPublishKey(ctx, tx, lookupKey); err != nil {
+		return PublishResult{}, err
+	} else if ok {
+		result, err := s.publishNoticeResult(ctx, tx, existingNoticeID, request.IdempotencyKey, true)
+		if err != nil {
+			return PublishResult{}, err
+		}
+		if publishReplayClash(result, request) {
+			return PublishResult{}, ErrIdempotencyConflict
+		}
+		if err := tx.Commit(); err != nil {
+			return PublishResult{}, err
+		}
+		committed = true
+		return result, nil
+	}
+	if _, ok, err := s.getNotice(ctx, tx, request.Notice.ID); err != nil {
+		return PublishResult{}, err
+	} else if ok {
+		return PublishResult{}, ErrNoticeExists
+	}
+	if err := s.insertNotice(ctx, tx, request.Notice, now); err != nil {
+		return PublishResult{}, err
+	}
+	deliveries := make([]Delivery, 0, len(request.Recipients))
+	for _, accountID := range request.Recipients {
+		delivery := Delivery{
+			ID:             DeliveryID(request.Notice.ID, accountID),
+			NoticeID:       request.Notice.ID,
+			AccountID:      accountID,
+			ShardID:        request.Notice.ShardID,
+			Status:         StatusPending,
+			AttachmentRef:  request.Notice.AttachmentRef,
+			IdempotencyKey: request.IdempotencyKey,
+			Meta:           mergeStringMap(request.Notice.Meta, request.Meta),
+			CreatedAt:      now,
+		}
+		if err := s.insertDelivery(ctx, tx, delivery); err != nil {
+			return PublishResult{}, err
+		}
+		deliveries = append(deliveries, cloneDelivery(delivery))
+	}
+	sortDeliveries(deliveries)
+	if err := s.insertPublishKey(ctx, tx, lookupKey, request.Notice.ID, request.IdempotencyKey, request.Meta, now); err != nil {
+		if isNoticeSQLDuplicate(err) {
+			_ = tx.Rollback()
+			committed = true
+			existingNoticeID, ok, lookupErr := s.lookupPublishKey(ctx, s.db, lookupKey)
+			if lookupErr != nil {
+				return PublishResult{}, lookupErr
+			}
+			if !ok {
+				return PublishResult{}, err
+			}
+			result, getErr := s.publishNoticeResult(ctx, s.db, existingNoticeID, request.IdempotencyKey, true)
+			if getErr != nil {
+				return PublishResult{}, getErr
+			}
+			if publishReplayClash(result, request) {
+				return PublishResult{}, ErrIdempotencyConflict
+			}
+			return result, nil
+		}
+		return PublishResult{}, err
+	}
+	if err := tx.Commit(); err != nil {
+		if recovered, ok := s.recoverPublishCommit(ctx, request); ok {
+			committed = true
+			return recovered, nil
+		}
+		return PublishResult{}, err
+	}
+	committed = true
+	result := PublishResult{
+		Accepted:       true,
+		Notice:         cloneNotice(request.Notice),
+		Deliveries:     deliveries,
+		IdempotencyKey: request.IdempotencyKey,
+		AdminReceiptID: request.Meta["admin_receipt_id"],
+		Meta:           cloneStringMap(request.Meta),
+		PublishedAt:    now,
+	}
+	return clonePublishResult(result), nil
+}
+
+func (s *SQLStore) RollbackPublish(ctx context.Context, result PublishResult) error {
+	if err := ctxErr(ctx); err != nil {
+		return err
+	}
+	ctx = sqlContext(ctx)
+	if s == nil || s.db == nil {
+		return ErrNoticeSQLDBRequired
+	}
+	if result.Notice.ID == "" || result.IdempotencyKey == "" {
+		return nil
+	}
+	tx, err := s.db.BeginTx(ctx, nil)
+	if err != nil {
+		return err
+	}
+	committed := false
+	defer func() {
+		if !committed {
+			_ = tx.Rollback()
+		}
+	}()
+	lookupKey := sqlLookupKey(publishLookupKey(PublishRequest{Notice: result.Notice, IdempotencyKey: result.IdempotencyKey}))
+	if _, err := tx.ExecContext(ctx, "DELETE FROM "+quoteSQLIdentifier(s.publish)+" WHERE lookup_key = ?", lookupKey); err != nil {
+		return err
+	}
+	if _, err := tx.ExecContext(ctx, "DELETE FROM "+quoteSQLIdentifier(s.ack)+" WHERE delivery_id IN (SELECT id FROM "+quoteSQLIdentifier(s.deliveries)+" WHERE notice_id = ?)", result.Notice.ID); err != nil {
+		return err
+	}
+	if _, err := tx.ExecContext(ctx, "DELETE FROM "+quoteSQLIdentifier(s.deliveries)+" WHERE notice_id = ?", result.Notice.ID); err != nil {
+		return err
+	}
+	if _, err := tx.ExecContext(ctx, "DELETE FROM "+quoteSQLIdentifier(s.notices)+" WHERE id = ?", result.Notice.ID); err != nil {
+		return err
+	}
+	if err := tx.Commit(); err != nil {
+		return err
+	}
+	committed = true
+	return nil
+}
+
+func (s *SQLStore) Acknowledge(ctx context.Context, request AcknowledgeRequest, now time.Time) (Delivery, bool, error) {
+	if err := ctxErr(ctx); err != nil {
+		return Delivery{}, false, err
+	}
+	ctx = sqlContext(ctx)
+	if s == nil || s.db == nil {
+		return Delivery{}, false, ErrNoticeSQLDBRequired
+	}
+	request = normalizeAckRequest(request)
+	if request.IdempotencyKey == "" {
+		return Delivery{}, false, ErrIdempotencyRequired
+	}
+	now = normalizeNow(now)
+
+	deliveryID := request.DeliveryID
+	if deliveryID == "" {
+		deliveryID = DeliveryID(request.NoticeID, request.AccountID)
+	}
+	if deliveryID == "" {
+		return Delivery{}, false, ErrInvalidNoticeRequest
+	}
+	lookupKey := sqlLookupKey(acknowledgeLookupKey(deliveryID, request.IdempotencyKey))
+
+	tx, err := s.db.BeginTx(ctx, nil)
+	if err != nil {
+		return Delivery{}, false, err
+	}
+	committed := false
+	defer func() {
+		if !committed {
+			_ = tx.Rollback()
+		}
+	}()
+	if knownDeliveryID, ok, err := s.lookupAcknowledgeKey(ctx, tx, lookupKey); err != nil {
+		return Delivery{}, false, err
+	} else if ok {
+		delivery, ok, err := s.getDelivery(ctx, tx, knownDeliveryID)
+		if err != nil {
+			return Delivery{}, true, err
+		}
+		if !ok {
+			return Delivery{}, true, ErrDeliveryNotFound
+		}
+		if err := tx.Commit(); err != nil {
+			return Delivery{}, true, err
+		}
+		committed = true
+		return cloneDelivery(delivery), true, nil
+	}
+	delivery, ok, err := s.getDelivery(ctx, tx, deliveryID)
+	if err != nil {
+		return Delivery{}, false, err
+	}
+	if !ok {
+		return Delivery{}, false, ErrDeliveryNotFound
+	}
+	if delivery.Status == StatusDeleted {
+		return Delivery{}, false, ErrDeliveryNotFound
+	}
+	duplicate := false
+	if delivery.Status == StatusAcknowledged {
+		duplicate = true
+	} else {
+		delivery.Status = StatusAcknowledged
+		delivery.AcknowledgedAt = now
+		if err := s.updateDeliveryAck(ctx, tx, delivery); err != nil {
+			return Delivery{}, false, err
+		}
+	}
+	if err := s.insertAcknowledgeKey(ctx, tx, lookupKey, delivery.ID, request.IdempotencyKey, now); err != nil && !isNoticeSQLDuplicate(err) {
+		return Delivery{}, false, err
+	}
+	if err := tx.Commit(); err != nil {
+		if recovered, ok := s.recoverAckCommit(ctx, lookupKey, delivery.ID); ok {
+			committed = true
+			return recovered, duplicate, nil
+		}
+		return Delivery{}, duplicate, err
+	}
+	committed = true
+	return cloneDelivery(delivery), duplicate, nil
+}
+
+func (s *SQLStore) Delete(ctx context.Context, request DeleteRequest) (DeleteResult, error) {
+	if err := ctxErr(ctx); err != nil {
+		return DeleteResult{}, err
+	}
+	ctx = sqlContext(ctx)
+	if s == nil || s.db == nil {
+		return DeleteResult{}, ErrNoticeSQLDBRequired
+	}
+	request = normDeleteReq(request)
+	if len(request.DeliveryIDs) == 0 {
+		return DeleteResult{}, nil
+	}
+	tx, err := s.db.BeginTx(ctx, nil)
+	if err != nil {
+		return DeleteResult{}, err
+	}
+	committed := false
+	defer func() {
+		if !committed {
+			_ = tx.Rollback()
+		}
+	}()
+
+	result := DeleteResult{}
+	for _, id := range request.DeliveryIDs {
+		delivery, ok, err := s.getDelivery(ctx, tx, id)
+		if err != nil {
+			return DeleteResult{}, err
+		}
+		if !ok || delivery.Status == StatusDeleted || (request.AccountID != "" && delivery.AccountID != request.AccountID) {
+			result.MissingIDs = append(result.MissingIDs, id)
+			continue
+		}
+		delivery.Status = StatusDeleted
+		if err := s.updateDeliveryStatus(ctx, tx, delivery.ID, StatusDeleted); err != nil {
+			return DeleteResult{}, err
+		}
+		result.DeletedIDs = append(result.DeletedIDs, id)
+	}
+	if err := tx.Commit(); err != nil {
+		return DeleteResult{}, err
+	}
+	committed = true
+	sort.Strings(result.DeletedIDs)
+	sort.Strings(result.MissingIDs)
+	return result, nil
+}
+
+func (s *SQLStore) ListForAccount(ctx context.Context, query Query) ([]Delivery, error) {
+	if err := ctxErr(ctx); err != nil {
+		return nil, err
+	}
+	ctx = sqlContext(ctx)
+	if s == nil || s.db == nil {
+		return nil, ErrNoticeSQLDBRequired
+	}
+	query.AccountID = strings.TrimSpace(query.AccountID)
+	query.ShardID = strings.TrimSpace(query.ShardID)
+	if query.AccountID == "" {
+		return nil, ErrRecipientRequired
+	}
+	now := normalizeNow(query.Now)
+	rows, err := s.db.QueryContext(ctx, "SELECT "+deliveryColumns()+" FROM "+quoteSQLIdentifier(s.deliveries)+" WHERE account_id = ? AND status <> ? ORDER BY created_at ASC, id ASC", query.AccountID, StatusDeleted)
+	if err != nil {
+		return nil, err
+	}
+	deliveries, err := scanSQLDeliveries(rows)
+	if err != nil {
+		return nil, err
+	}
+	out := make([]Delivery, 0, len(deliveries))
+	for _, delivery := range deliveries {
+		notice, ok, err := s.getNotice(ctx, s.db, delivery.NoticeID)
+		if err != nil {
+			return nil, err
+		}
+		if !ok || !noticeVisible(notice, query.ShardID, now) {
+			continue
+		}
+		out = append(out, cloneDelivery(delivery))
+	}
+	sortAcctDeliveries(out)
+	return out, nil
+}
+
+func (s *SQLStore) ActiveAnnouncements(ctx context.Context, query Query) ([]Notice, error) {
+	if err := ctxErr(ctx); err != nil {
+		return nil, err
+	}
+	ctx = sqlContext(ctx)
+	if s == nil || s.db == nil {
+		return nil, ErrNoticeSQLDBRequired
+	}
+	query.ShardID = strings.TrimSpace(query.ShardID)
+	now := normalizeNow(query.Now)
+	rows, err := s.db.QueryContext(ctx, "SELECT "+noticeColumns()+" FROM "+quoteSQLIdentifier(s.notices)+" WHERE kind = ? ORDER BY id ASC", KindAnnouncement)
+	if err != nil {
+		return nil, err
+	}
+	notices, err := scanSQLNotices(rows)
+	if err != nil {
+		return nil, err
+	}
+	out := make([]Notice, 0, len(notices))
+	for _, notice := range notices {
+		if noticeVisible(notice, query.ShardID, now) {
+			out = append(out, cloneNotice(notice))
+		}
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].ID < out[j].ID })
+	return out, nil
+}
+
+func (s *SQLStore) Snapshot(ctx context.Context) (Snapshot, error) {
+	if err := ctxErr(ctx); err != nil {
+		return Snapshot{}, err
+	}
+	ctx = sqlContext(ctx)
+	if s == nil || s.db == nil {
+		return Snapshot{}, ErrNoticeSQLDBRequired
+	}
+	notices, err := s.queryStringColumn(ctx, "SELECT kind FROM "+quoteSQLIdentifier(s.notices))
+	if err != nil {
+		return Snapshot{}, err
+	}
+	statuses, err := s.queryStringColumn(ctx, "SELECT status FROM "+quoteSQLIdentifier(s.deliveries))
+	if err != nil {
+		return Snapshot{}, err
+	}
+	publishKeys, err := s.queryStringColumn(ctx, "SELECT lookup_key FROM "+quoteSQLIdentifier(s.publish))
+	if err != nil {
+		return Snapshot{}, err
+	}
+	ackKeys, err := s.queryStringColumn(ctx, "SELECT lookup_key FROM "+quoteSQLIdentifier(s.ack))
+	if err != nil {
+		return Snapshot{}, err
+	}
+	snapshot := Snapshot{
+		Notices:         len(notices),
+		Deliveries:      len(statuses),
+		ByKind:          make(map[string]int),
+		ByStatus:        make(map[string]int),
+		PublishKeys:     len(publishKeys),
+		AcknowledgeKeys: len(ackKeys),
+	}
+	for _, kind := range notices {
+		snapshot.ByKind[kind]++
+	}
+	for _, status := range statuses {
+		snapshot.ByStatus[status]++
+	}
+	if len(snapshot.ByKind) == 0 {
+		snapshot.ByKind = nil
+	}
+	if len(snapshot.ByStatus) == 0 {
+		snapshot.ByStatus = nil
+	}
+	return snapshot, nil
+}
+
+func (s *SQLStore) publishNoticeResult(ctx context.Context, db sqlNoticeQuerier, noticeID string, idempotencyKey string, duplicate bool) (PublishResult, error) {
+	notice, publishedAt, ok, err := s.getNoticePubAt(ctx, db, noticeID)
+	if err != nil {
+		return PublishResult{}, err
+	}
+	if !ok {
+		return PublishResult{}, ErrNoticeNotFound
+	}
+	deliveries, err := s.deliveriesForNotice(ctx, db, noticeID)
+	if err != nil {
+		return PublishResult{}, err
+	}
+	meta, err := s.publishMeta(ctx, db, sqlLookupKey(publishLookupKey(PublishRequest{Notice: notice, IdempotencyKey: idempotencyKey})))
+	if err != nil {
+		return PublishResult{}, err
+	}
+	result := PublishResult{
+		Accepted:       true,
+		Duplicate:      duplicate,
+		Notice:         notice,
+		Deliveries:     deliveries,
+		IdempotencyKey: idempotencyKey,
+		AdminReceiptID: meta["admin_receipt_id"],
+		Meta:           meta,
+		PublishedAt:    publishedAt,
+	}
+	return clonePublishResult(result), nil
+}
+
+func (s *SQLStore) recoverPublishCommit(parent context.Context, request PublishRequest) (PublishResult, bool) {
+	ctx, cancel := sqlRecoveryCtx(parent)
+	defer cancel()
+	lookupKey := sqlLookupKey(publishLookupKey(request))
+	existingNoticeID, ok, err := s.lookupPublishKey(ctx, s.db, lookupKey)
+	if err != nil || !ok {
+		return PublishResult{}, false
+	}
+	result, err := s.publishNoticeResult(ctx, s.db, existingNoticeID, request.IdempotencyKey, false)
+	if err != nil || publishReplayClash(result, request) {
+		return PublishResult{}, false
+	}
+	return result, true
+}
+
+func (s *SQLStore) recoverAckCommit(parent context.Context, lookupKey string, deliveryID string) (Delivery, bool) {
+	ctx, cancel := sqlRecoveryCtx(parent)
+	defer cancel()
+	knownDeliveryID, ok, err := s.lookupAcknowledgeKey(ctx, s.db, lookupKey)
+	if err != nil || !ok || knownDeliveryID != deliveryID {
+		return Delivery{}, false
+	}
+	delivery, ok, err := s.getDelivery(ctx, s.db, knownDeliveryID)
+	if err != nil || !ok || delivery.Status == StatusDeleted {
+		return Delivery{}, false
+	}
+	return cloneDelivery(delivery), true
+}

server/internal/runtime/notice/sql_store_helpers.go

@@ -0,0 +1,513 @@
+package notice
+
+import (
+	"context"
+	"crypto/sha256"
+	"database/sql"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"regexp"
+	"strings"
+	"time"
+
+	mysql "github.com/go-sql-driver/mysql"
+)
+
+type sqlNoticeQuerier interface {
+	QueryContext(context.Context, string, ...any) (SQLRows, error)
+}
+
+type sqlNoticeExecutor interface {
+	sqlNoticeQuerier
+	ExecContext(context.Context, string, ...any) (sql.Result, error)
+}
+
+func (s *SQLStore) lookupPublishKey(ctx context.Context, db sqlNoticeQuerier, lookupKey string) (string, bool, error) {
+	return s.lookupKey(ctx, db, "SELECT notice_id FROM "+quoteSQLIdentifier(s.publish)+" WHERE lookup_key = ? LIMIT 1", lookupKey)
+}
+
+func (s *SQLStore) lookupAcknowledgeKey(ctx context.Context, db sqlNoticeQuerier, lookupKey string) (string, bool, error) {
+	return s.lookupKey(ctx, db, "SELECT delivery_id FROM "+quoteSQLIdentifier(s.ack)+" WHERE lookup_key = ? LIMIT 1", lookupKey)
+}
+
+func (s *SQLStore) lookupKey(ctx context.Context, db sqlNoticeQuerier, query string, lookupKey string) (string, bool, error) {
+	rows, err := db.QueryContext(ctx, query, lookupKey)
+	if err != nil {
+		return "", false, err
+	}
+	values, err := scanSQLStrings(rows)
+	if err != nil {
+		return "", false, err
+	}
+	if len(values) == 0 {
+		return "", false, nil
+	}
+	return values[0], true, nil
+}
+
+func (s *SQLStore) getNotice(ctx context.Context, db sqlNoticeQuerier, id string) (Notice, bool, error) {
+	notice, _, ok, err := s.getNoticePubAt(ctx, db, id)
+	return notice, ok, err
+}
+
+func (s *SQLStore) getNoticePubAt(ctx context.Context, db sqlNoticeQuerier, id string) (Notice, time.Time, bool, error) {
+	rows, err := db.QueryContext(ctx, "SELECT "+noticeColumns()+" FROM "+quoteSQLIdentifier(s.notices)+" WHERE id = ? LIMIT 1", id)
+	if err != nil {
+		return Notice{}, time.Time{}, false, err
+	}
+	notices, publishedAt, err := scanSQLPubNotices(rows)
+	if err != nil {
+		return Notice{}, time.Time{}, false, err
+	}
+	if len(notices) == 0 {
+		return Notice{}, time.Time{}, false, nil
+	}
+	return cloneNotice(notices[0]), publishedAt[0], true, nil
+}
+
+func (s *SQLStore) getDelivery(ctx context.Context, db sqlNoticeQuerier, id string) (Delivery, bool, error) {
+	rows, err := db.QueryContext(ctx, "SELECT "+deliveryColumns()+" FROM "+quoteSQLIdentifier(s.deliveries)+" WHERE id = ? LIMIT 1", id)
+	if err != nil {
+		return Delivery{}, false, err
+	}
+	deliveries, err := scanSQLDeliveries(rows)
+	if err != nil {
+		return Delivery{}, false, err
+	}
+	if len(deliveries) == 0 {
+		return Delivery{}, false, nil
+	}
+	return cloneDelivery(deliveries[0]), true, nil
+}
+
+func (s *SQLStore) deliveriesForNotice(ctx context.Context, db sqlNoticeQuerier, noticeID string) ([]Delivery, error) {
+	rows, err := db.QueryContext(ctx, "SELECT "+deliveryColumns()+" FROM "+quoteSQLIdentifier(s.deliveries)+" WHERE notice_id = ? ORDER BY account_id ASC, id ASC", noticeID)
+	if err != nil {
+		return nil, err
+	}
+	deliveries, err := scanSQLDeliveries(rows)
+	if err != nil {
+		return nil, err
+	}
+	sortDeliveries(deliveries)
+	return deliveries, nil
+}
+
+func (s *SQLStore) publishMeta(ctx context.Context, db sqlNoticeQuerier, lookupKey string) (map[string]string, error) {
+	rows, err := db.QueryContext(ctx, "SELECT meta_json FROM "+quoteSQLIdentifier(s.publish)+" WHERE lookup_key = ? LIMIT 1", lookupKey)
+	if err != nil {
+		return nil, err
+	}
+	values, err := scanSQLNullStrings(rows)
+	if err != nil {
+		return nil, err
+	}
+	if len(values) == 0 {
+		return nil, nil
+	}
+	return decodeSQLStringMap(values[0])
+}
+
+func (s *SQLStore) insertNotice(ctx context.Context, db sqlNoticeExecutor, notice Notice, publishedAt time.Time) error {
+	meta, err := encodeSQLStringMap(notice.Meta)
+	if err != nil {
+		return err
+	}
+	_, err = db.ExecContext(ctx,
+		"INSERT INTO "+quoteSQLIdentifier(s.notices)+" (id, kind, scope, shard_id, title, body, attachment_ref, starts_at, ends_at, disabled, meta_json, published_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+		notice.ID,
+		notice.Kind,
+		notice.Scope,
+		notice.ShardID,
+		notice.Title,
+		nullableSQLString(notice.Body),
+		notice.AttachmentRef,
+		nullableSQLTime(notice.StartsAt),
+		nullableSQLTime(notice.EndsAt),
+		notice.Disabled,
+		meta,
+		publishedAt.UTC(),
+	)
+	return err
+}
+
+func (s *SQLStore) insertDelivery(ctx context.Context, db sqlNoticeExecutor, delivery Delivery) error {
+	meta, err := encodeSQLStringMap(delivery.Meta)
+	if err != nil {
+		return err
+	}
+	_, err = db.ExecContext(ctx,
+		"INSERT INTO "+quoteSQLIdentifier(s.deliveries)+" (id, notice_id, account_id, shard_id, status, attachment_ref, idempotency_key, meta_json, created_at, acknowledged_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+		delivery.ID,
+		delivery.NoticeID,
+		delivery.AccountID,
+		delivery.ShardID,
+		delivery.Status,
+		delivery.AttachmentRef,
+		delivery.IdempotencyKey,
+		meta,
+		delivery.CreatedAt.UTC(),
+		nullableSQLTime(delivery.AcknowledgedAt),
+	)
+	return err
+}
+
+func (s *SQLStore) insertPublishKey(ctx context.Context, db sqlNoticeExecutor, lookupKey string, noticeID string, idempotencyKey string, meta map[string]string, createdAt time.Time) error {
+	metaJSON, err := encodeSQLStringMap(meta)
+	if err != nil {
+		return err
+	}
+	_, err = db.ExecContext(ctx,
+		"INSERT INTO "+quoteSQLIdentifier(s.publish)+" (lookup_key, notice_id, idempotency_key, meta_json, created_at) VALUES (?, ?, ?, ?, ?)",
+		lookupKey,
+		noticeID,
+		idempotencyKey,
+		metaJSON,
+		createdAt.UTC(),
+	)
+	return err
+}
+
+func (s *SQLStore) insertAcknowledgeKey(ctx context.Context, db sqlNoticeExecutor, lookupKey string, deliveryID string, idempotencyKey string, createdAt time.Time) error {
+	_, err := db.ExecContext(ctx,
+		"INSERT INTO "+quoteSQLIdentifier(s.ack)+" (lookup_key, delivery_id, idempotency_key, created_at) VALUES (?, ?, ?, ?) ON DUPLICATE KEY UPDATE delivery_id = delivery_id",
+		lookupKey,
+		deliveryID,
+		idempotencyKey,
+		createdAt.UTC(),
+	)
+	return err
+}
+
+func (s *SQLStore) updateDeliveryAck(ctx context.Context, db sqlNoticeExecutor, delivery Delivery) error {
+	result, err := db.ExecContext(ctx,
+		"UPDATE "+quoteSQLIdentifier(s.deliveries)+" SET status = ?, acknowledged_at = ? WHERE id = ?",
+		delivery.Status,
+		nullableSQLTime(delivery.AcknowledgedAt),
+		delivery.ID,
+	)
+	if err != nil {
+		return err
+	}
+	if result == nil {
+		return nil
+	}
+	affected, err := result.RowsAffected()
+	if err != nil {
+		return err
+	}
+	if affected == 0 {
+		return ErrDeliveryNotFound
+	}
+	return nil
+}
+
+func (s *SQLStore) updateDeliveryStatus(ctx context.Context, db sqlNoticeExecutor, deliveryID string, status string) error {
+	result, err := db.ExecContext(ctx,
+		"UPDATE "+quoteSQLIdentifier(s.deliveries)+" SET status = ? WHERE id = ?",
+		status,
+		deliveryID,
+	)
+	if err != nil {
+		return err
+	}
+	if result == nil {
+		return nil
+	}
+	affected, err := result.RowsAffected()
+	if err != nil {
+		return err
+	}
+	if affected == 0 {
+		return ErrDeliveryNotFound
+	}
+	return nil
+}
+
+func (s *SQLStore) queryStringColumn(ctx context.Context, query string, args ...any) ([]string, error) {
+	rows, err := s.db.QueryContext(ctx, query, args...)
+	if err != nil {
+		return nil, err
+	}
+	return scanSQLStrings(rows)
+}
+
+func scanSQLNotices(rows SQLRows) ([]Notice, error) {
+	notices, _, err := scanSQLPubNotices(rows)
+	return notices, err
+}
+
+func scanSQLPubNotices(rows SQLRows) (notices []Notice, published []time.Time, err error) {
+	if rows == nil {
+		return nil, nil, ErrNoticeInvalidRows
+	}
+	defer closeNoticeRowsErr(rows, &err)
+	for rows.Next() {
+		notice, publishedAt, err := scanSQLNotice(rows)
+		if err != nil {
+			return nil, nil, err
+		}
+		notices = append(notices, notice)
+		published = append(published, publishedAt)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, nil, err
+	}
+	return notices, published, nil
+}
+
+func scanSQLNotice(rows SQLRows) (Notice, time.Time, error) {
+	var notice Notice
+	var scope, shardID, body, attachmentRef, meta sql.NullString
+	var startsAt, endsAt sql.NullTime
+	var publishedAt time.Time
+	if err := rows.Scan(
+		&notice.ID,
+		&notice.Kind,
+		&scope,
+		&shardID,
+		&notice.Title,
+		&body,
+		&attachmentRef,
+		&startsAt,
+		&endsAt,
+		&notice.Disabled,
+		&meta,
+		&publishedAt,
+	); err != nil {
+		return Notice{}, time.Time{}, err
+	}
+	if scope.Valid {
+		notice.Scope = scope.String
+	}
+	if shardID.Valid {
+		notice.ShardID = shardID.String
+	}
+	if body.Valid {
+		notice.Body = body.String
+	}
+	if attachmentRef.Valid {
+		notice.AttachmentRef = attachmentRef.String
+	}
+	if startsAt.Valid {
+		notice.StartsAt = startsAt.Time.UTC()
+	}
+	if endsAt.Valid {
+		notice.EndsAt = endsAt.Time.UTC()
+	}
+	if meta.Valid {
+		decoded, err := decodeSQLStringMap(meta.String)
+		if err != nil {
+			return Notice{}, time.Time{}, err
+		}
+		notice.Meta = decoded
+	}
+	return cloneNotice(notice), publishedAt.UTC(), nil
+}
+
+func scanSQLDeliveries(rows SQLRows) (deliveries []Delivery, err error) {
+	if rows == nil {
+		return nil, ErrNoticeInvalidRows
+	}
+	defer closeNoticeRowsErr(rows, &err)
+	for rows.Next() {
+		delivery, err := scanSQLDelivery(rows)
+		if err != nil {
+			return nil, err
+		}
+		deliveries = append(deliveries, delivery)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return deliveries, nil
+}
+
+func scanSQLDelivery(rows SQLRows) (Delivery, error) {
+	var delivery Delivery
+	var shardID, attachmentRef, idempotencyKey, meta sql.NullString
+	var acknowledgedAt sql.NullTime
+	if err := rows.Scan(
+		&delivery.ID,
+		&delivery.NoticeID,
+		&delivery.AccountID,
+		&shardID,
+		&delivery.Status,
+		&attachmentRef,
+		&idempotencyKey,
+		&meta,
+		&delivery.CreatedAt,
+		&acknowledgedAt,
+	); err != nil {
+		return Delivery{}, err
+	}
+	if shardID.Valid {
+		delivery.ShardID = shardID.String
+	}
+	if attachmentRef.Valid {
+		delivery.AttachmentRef = attachmentRef.String
+	}
+	if idempotencyKey.Valid {
+		delivery.IdempotencyKey = idempotencyKey.String
+	}
+	if meta.Valid {
+		decoded, err := decodeSQLStringMap(meta.String)
+		if err != nil {
+			return Delivery{}, err
+		}
+		delivery.Meta = decoded
+	}
+	delivery.CreatedAt = delivery.CreatedAt.UTC()
+	if acknowledgedAt.Valid {
+		delivery.AcknowledgedAt = acknowledgedAt.Time.UTC()
+	}
+	return cloneDelivery(delivery), nil
+}
+
+func scanSQLStrings(rows SQLRows) ([]string, error) {
+	values, err := scanSQLNullStrings(rows)
+	if err != nil {
+		return nil, err
+	}
+	out := make([]string, 0, len(values))
+	for _, value := range values {
+		out = append(out, strings.TrimSpace(value))
+	}
+	return out, nil
+}
+
+func scanSQLNullStrings(rows SQLRows) (values []string, err error) {
+	if rows == nil {
+		return nil, ErrNoticeInvalidRows
+	}
+	defer closeNoticeRowsErr(rows, &err)
+	for rows.Next() {
+		var value sql.NullString
+		if err := rows.Scan(&value); err != nil {
+			return nil, err
+		}
+		if value.Valid {
+			values = append(values, value.String)
+		} else {
+			values = append(values, "")
+		}
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return values, nil
+}
+
+// closeNoticeRowsErr 在扫描辅助函数返回前合并 Close 错误，避免查询清理失败被静默吞掉。
+func closeNoticeRowsErr(rows SQLRows, err *error) {
+	if rows == nil || err == nil {
+		return
+	}
+	if closeErr := rows.Close(); closeErr != nil && *err == nil {
+		*err = closeErr
+	}
+}
+
+func noticeColumns() string {
+	return "id, kind, scope, shard_id, title, body, attachment_ref, starts_at, ends_at, disabled, meta_json, published_at"
+}
+
+func deliveryColumns() string {
+	return "id, notice_id, account_id, shard_id, status, attachment_ref, idempotency_key, meta_json, created_at, acknowledged_at"
+}
+
+func encodeSQLStringMap(values map[string]string) (any, error) {
+	if len(values) == 0 {
+		return nil, nil
+	}
+	data, err := json.Marshal(values)
+	if err != nil {
+		return nil, err
+	}
+	return string(data), nil
+}
+
+func decodeSQLStringMap(value string) (map[string]string, error) {
+	value = strings.TrimSpace(value)
+	if value == "" {
+		return nil, nil
+	}
+	var out map[string]string
+	if err := json.Unmarshal([]byte(value), &out); err != nil {
+		return nil, err
+	}
+	return normalizeStringMap(out), nil
+}
+
+func nullableSQLString(value string) any {
+	value = strings.TrimSpace(value)
+	if value == "" {
+		return nil
+	}
+	return value
+}
+
+func nullableSQLTime(value time.Time) any {
+	if value.IsZero() {
+		return nil
+	}
+	return value.UTC()
+}
+
+type sqlStoreTables struct {
+	notices    string
+	deliveries string
+	publish    string
+	ack        string
+}
+
+func normSQLStoreTables(options SQLStoreOptions) (sqlStoreTables, error) {
+	prefix := strings.TrimSpace(options.TablePrefix)
+	if prefix == "" {
+		prefix = defSQLTablePrefix
+	}
+	tables := sqlStoreTables{
+		notices:    firstNonEmpty(options.NoticeTable, prefix+"_notices"),
+		deliveries: firstNonEmpty(options.DeliveryTable, prefix+"_deliveries"),
+		publish:    firstNonEmpty(options.PublishKeyTable, prefix+"_publish_keys"),
+		ack:        firstNonEmpty(options.AcknowledgeKeyTable, prefix+"_ack_keys"),
+	}
+	for _, table := range []string{tables.notices, tables.deliveries, tables.publish, tables.ack} {
+		if !noticeTablePattern.MatchString(table) {
+			return sqlStoreTables{}, ErrNoticeInvalidTable
+		}
+	}
+	return tables, nil
+}
+
+func quoteSQLIdentifier(identifier string) string {
+	return "`" + identifier + "`"
+}
+
+func sqlLookupKey(raw string) string {
+	sum := sha256.Sum256([]byte(raw))
+	return hex.EncodeToString(sum[:])
+}
+
+func sqlContext(ctx context.Context) context.Context {
+	if ctx == nil {
+		return context.Background()
+	}
+	return ctx
+}
+
+func sqlRecoveryCtx(parent context.Context) (context.Context, context.CancelFunc) {
+	base := context.Background()
+	if parent != nil {
+		base = context.WithoutCancel(parent)
+	}
+	return context.WithTimeout(base, rollbackTimeout)
+}
+
+func isNoticeSQLDuplicate(err error) bool {
+	var mysqlErr *mysql.MySQLError
+	return errors.As(err, &mysqlErr) && mysqlErr.Number == 1062
+}
+
+var noticeTablePattern = regexp.MustCompile(`^[A-Za-z_][A-Za-z0-9_]*$`)