syntax = "v1"

type (
	SettingPath {
		Scope   string `path:"scope" validate:"required,oneof=user account system"` // 設定範圍，可選 user / account / system
		ScopeID string `path:"scope_id" validate:"required"`                        // 範圍 ID，例如 user_id、account_id 或 global
		Page    int64  `form:"page,optional"`                                       // 頁碼，從 1 開始
		PageSize int64 `form:"pageSize,optional"`                                   // 每頁筆數，server 會限制最大值
	}

	SettingKeyPath {
		Scope   string `path:"scope" validate:"required,oneof=user account system"` // 設定範圍，可選 user / account / system
		ScopeID string `path:"scope_id" validate:"required"`                        // 範圍 ID，例如 user_id、account_id 或 global
		Key     string `path:"key" validate:"required"`                             // 設定 key，例如 ai.default
	}

	SettingUpsertReq {
		Scope   string         `path:"scope" validate:"required,oneof=user account system"` // 設定範圍，可選 user / account / system
		ScopeID string         `path:"scope_id" validate:"required"`                        // 範圍 ID，例如 user_id、account_id 或 global
		Key     string         `path:"key" validate:"required"`                             // 設定 key，例如 ai.default
		Value   map[string]interface{} `json:"value" validate:"required"`                           // 設定內容 JSON object
		Version int            `json:"version,optional"`                                     // schema version，未帶入時預設 1
	}

	SettingData {
		ID       string         `json:"id"`
		Scope    string         `json:"scope"`
		ScopeID  string         `json:"scope_id"`
		Key      string         `json:"key"`
		Value    map[string]interface{} `json:"value"`
		Version  int            `json:"version"`
		CreateAt int64          `json:"create_at"`
		UpdateAt int64          `json:"update_at"`
	}

	SettingListData {
		Pagination PaginationData `json:"pagination"`
		List       []SettingData  `json:"list"`
	}

	PaginationData {
		Total      int64 `json:"total"`
		Page       int64 `json:"page"`
		PageSize   int64 `json:"pageSize"`
		TotalPages int64 `json:"totalPages"`
	}
)

@server(
	group:      setting
	prefix:     /api/v1/settings
	middleware: AuthJWT
	tags:       "Setting - General"
	summary:    "Manage settings by scope, scope_id, and key. Requires Bearer JWT."
)
service gateway {
	@handler listSettings
	get /:scope/:scope_id (SettingPath) returns (SettingListData)

	@handler getSetting
	get /:scope/:scope_id/:key (SettingKeyPath) returns (SettingData)

	@handler upsertSetting
	put /:scope/:scope_id/:key (SettingUpsertReq) returns (SettingData)

	@handler deleteSetting
	delete /:scope/:scope_id/:key (SettingKeyPath)
}