Go 上报方式

先在服务端 SDK 概览按事件风险选定路径，再使用本页的构造。安装、首条事件和 Gin 备注在Go 集成；Track 与画像签名在Go 基础 API。

路径	构造	本页
默认批量	server.NewClient	批量
日志交接	consumer.NewLoggingConsumer	日志
同步直发	consumer.NewDirectConsumer	直发
宿主事务 Outbox	宿主数据库与 Relay，不由 SDK 再构造一种 Client	Outbox

日志与直发示例展示低层 Consumer；普通业务埋点使用快速接入页的 Client.Track()。

默认批量

server.NewClient 使用有界内存队列和后台冲刷。初始化示例在集成页。

默认队列的进程退出风险见服务端 SDK 概览。需要与业务事务一起提交的事实使用宿主事务 Outbox。

日志交接

LoggingConsumer 将事件写入本地文件；文件格式、交接、磁盘预算和恢复规则见日志交接边界。

import (
	"github.com/track-business/track-business-sdk-go/consumer"
)

logger, err := consumer.NewLoggingConsumer(consumer.LoggingOptions{
	Directory:     "/var/log/track-business",
	FilePrefix:    "events",
	MaxFileBytes:  64 << 20,
	MaxTotalBytes: 1 << 30,
	SyncPolicy:    consumer.SyncOnFlush,
})
if err != nil {
	panic(err)
}
defer logger.Close()

if err := logger.Accept(event); err != nil {
    // 由宿主处理写入失败，并记录不含事件正文的诊断。
}

同步直发

DirectConsumer 使用宿主提供的 Transport 发送事件。确认与重试语义见服务端 SDK 概览。

direct, err := consumer.NewDirectConsumer(consumer.DirectOptions{Transport: transport})
if err != nil {
	panic(err)
}
result, err := direct.Accept(ctx, event)
if err != nil {
    // 由宿主处理未完成或未知结果；不要标记为成功。
} else {
    _ = result.Outcome // 按结果决定后续处理。
}

result.Outcome 只描述这一次响应：accepted、rejected 或 unresolved。超时和未完成是未知，不是成功。

宿主事务 Outbox

宿主事务 Outbox 由业务数据库事务和 Relay 实现；不要把同一事件同时送入默认队列。实现边界见服务端 SDK 概览。

业务写入与不可变事件记录必须使用同一个数据库事务；回滚时两者一起回滚。不要先提交订单，再调用 track()，并把这称为事务 Outbox。数据库迁移、事件完整序列化、租约、重试/死信与终态行保留均由宿主管理，SDK 不会自动安装数据库表或驱动。

接收端整批 ACK 与宿主终态提交是两个步骤。若接收端已接受但数据库提交报错或更新零行，Relay 报告提交未知并停止本次 drain。此时不能标记成功，也不能生成新的 eventId 作为补偿；按原记录、原 eventId 及稳定批次身份重试，并由 Collector 幂等处理。跨步骤不承诺 Exactly Once。

领取、续约、accepted/rejected 与 release 必须按记录 ID 和租约 token 限制，且终态/续约还须检查租约未过期；旧 owner 不能改变新 owner 的记录。租约使用数据库统一时间。慢发送需要续约时，宿主 Store 实现续约接口并显式配置间隔；间隔必须小于租约，留出数据库和网络抖动余量。续约失败时即使 HTTP 返回成功，也不能据此提交 accepted，已发出的请求不能靠本地取消撤回。

Go Store 可实现 relay.RenewableStore，构造时通过 relay.Options{LeaseRenewalInterval: interval} 显式启用。未配置时不自动续约。用 errors.As(err, &unknown) 识别 *relay.CommitUnknownError 后暂停本 Relay 后续调度，交由宿主恢复策略处理；不要把错误字符串或事件值直接写入日志。Core 仍不依赖数据库驱动或 Gin。

自定义 Store 触发 panic，或续约在发送结束后仍未退出时，当前 Relay 会停用该 Store。核对数据库记录与租约，并确认旧调用已退出，再创建新 Relay。普通 Client 的自定义 EventStore 触发 panic 后，准入返回 storage_unavailable，flush 返回 ErrCommitUnknown。恢复前须先核对 Store，避免覆盖可能已提交的数据。