// Package protocol 定义客户端 ↔ 后端的通信契约，是 5 端（server/desktop/android/ios/web）
// 对齐的唯一真相源。设计依据 doc/backend-architecture.html 第四章。
package protocol

// 音频参数：二进制帧为 16kHz / 16bit / mono PCM，每 100ms 一帧。
const (
	SampleRate  = 16000
	FrameMillis = 100
	FrameBytes  = SampleRate * 2 * FrameMillis / 1000 // 3200

	// MaxSessionSeconds 单会话上限，到点服务端自动截断定稿（SESSION_LIMIT）。
	MaxSessionSeconds = 180

	// 设备维度 30 分钟滑动窗口限制。
	RateWindowSeconds      = 30 * 60
	RateMaxSessions        = 30
	RateMaxAudioSeconds    = 30 * 60
	MaxConcurrentPerDevice = 1

	// TrialDailySeconds 每日免费试用时长（秒）。
	TrialDailySeconds = 180
)

// 上行文本帧类型。
const (
	MsgStart  = "start"
	MsgStop   = "stop"
	MsgCancel = "cancel"
)

// 下行文本帧类型。
const (
	MsgPartial = "partial"
	MsgFinal   = "final"
	MsgUsage   = "usage"
	MsgError   = "error"
)

// ClientMsg 客户端上行控制消息（文本帧）。音频走二进制帧。
type ClientMsg struct {
	Type       string `json:"type"` // start | stop | cancel
	SessionID  string `json:"session_id"`
	SampleRate int    `json:"sample_rate,omitempty"` // start 必填，当前仅支持 16000
	Format     string `json:"format,omitempty"`      // start 必填，当前仅支持 pcm16
}

// ServerMsg 服务端下行消息（文本帧）。
type ServerMsg struct {
	Type      string `json:"type"` // partial | final | usage | error
	SessionID string `json:"session_id,omitempty"`

	// partial / final
	Text string `json:"text,omitempty"`

	// usage：识别中每 2s 及 stop 后下发，驱动 UI 实时刷新余额。
	// 去 omitempty（16G）：0 是合法值（扣穿 / 试用用尽），客户端须能区分
	// "未下发"与"为 0"。partial/final 帧亦会带这三个 0 字段，客户端以 type 分发，无碍。
	SessionSeconds int   `json:"session_seconds"`
	BalanceSeconds int64 `json:"balance_seconds"`
	TrialRemaining int   `json:"trial_remaining"`

	// error
	Code    string `json:"code,omitempty"`
	Message string `json:"message,omitempty"`
}