FileShare/server/internal/config/schema.go

// Package config — schema.go 定义 26.9 新增配置键（KV）schema：
// 键名常量、类型、默认值与取值边界。管理与 API 层（t2）按下表读写与校验，
// 文档（t4）按本表生成说明。键名除参考实现既有 camelCase 键外，
// 26.9 新增键统一 snake_case。
package config

// —— 26.9 新增/沿用键名常量（单一事实来源；settings 包会 re-export）——
// 命名规则：26.9 新增键 snake_case；与参考实现对齐的既有键保持原拼写。
const (
	// 需求 ①：背景图
	KeyBackground    = "background"     // 参考实现既有键（v1 兼容保留）
	KeyBackgroundURL = "background_url" // 26.9 新增：背景图 URL 或上传后的访问地址（空=默认主题）
	// 需求 ②：页脚
	KeyFooterText  = "footer_text"  // 26.9 新增：页脚自定义内容（纯文本或受控 HTML 片段）
	KeyFooterBeian = "footer_beian" // 26.9 新增：备案号（如 京ICP备2024xxxxxx号-1）
	// 需求 ③：系统通知
	KeyNotifyEnabled = "notify_enabled" // 26.9 新增：通知开关，1 开启 / 0 关闭
	KeyNotifyTitle   = "notify_title"   // 既有键：通知标题
	KeyNotifyContent = "notify_content" // 既有键：通知内容（允许 <a> 等受控 HTML）
	// 需求 ④：保存策略（上传页动态读取并在范围内选择）
	KeyMaxSaveSeconds = "max_save_seconds" // 既有键：最长保存秒数，0=不限制（仅受默认 7 天兜底）
	KeyMaxSaveCount   = "max_save_count"   // 26.9 新增：单次分享最大可取（保存）次数上限，0=不限制
	KeyExpireStyle    = "expireStyle"      // 既有键：允许的过期方式白名单
	// 需求 ④：上传频率限制（既有键，对齐参考 ip_limit["upload"]）
	KeyUploadCount  = "uploadCount"  // 窗口内允许上传次数
	KeyUploadMinute = "uploadMinute" // 频率窗口（分钟）
	// 需求 ④⑩：存储策略（最大文件大小/允许类型/总容量）
	KeyUploadSize   = "uploadSize"         // 既有键：单文件上限（字节），参考实现语义
	KeyMaxFileSize  = "max_file_size"      // 26.9 新增：存储策略-单文件上限（字节），0=回落 uploadSize
	KeyAllowedTypes = "allowed_file_types" // 既有键：允许类型白名单（"*" 不限制）
	KeyStorageLimit = "storageLimit"       // 既有键：站点总容量（字节），0=不限制
	KeyOpenUpload   = "openUpload"         // 既有键：游客上传开关
	// 26.9：存储引擎运行时可配（热切换；file_storage 为参考既有键保留兼容）
	KeyStorageEngine = "storage_engine" // 当前存储引擎：local|s3|webdav
	KeySiteDomain    = "site_domain"    // 站点对外域名（空=分享链接用当前地址）
	KeyUploadRate    = "upload_rate"    // 上传带宽字节/秒（0=不限速）
	KeyDownloadRate  = "download_rate"  // 下载带宽字节/秒（0=不限速）
	// —— 26.9 回收与下载安全 ——
	KeyRecycleEnabled   = "recycle_enabled"    // 过期分享自动回收开关（1 开 / 0 关）
	KeyRecycleInterval  = "recycle_interval"   // 回收扫描间隔（秒，60~86400）
	KeyRetentionDays    = "retention_days"     // 全局最长存储时长（天，0=不限制）
	KeyDedupEnabled     = "dedup_enabled"      // SHA512 内容去重开关
	KeyHotlinkEnabled   = "hotlink_enabled"    // 下载防盗链开关
	KeyHotlinkWhitelist = "hotlink_whitelist"  // 防盗链 Referer 白名单（逗号分隔域名）
	KeyDirectDownload   = "direct_download"    // 对象存储直链下载开关（仅 S3 引擎生效）
	KeyDirectLinkExpire = "direct_link_expire" // 直链有效期（秒，60~3600）
)

// —— 取值边界（管理端保存与 API 校验用）——
const (
	// 保存时间上限：最长 365 天，0 表示不限制。
	MaxSaveSecondsMax = 365 * 24 * 60 * 60
	// 保存次数上限：最长 100000 次，0 表示不限制。
	MaxSaveCountMax = 100000
	// 单文件大小上限：最长 10 GiB，0 表示回落 uploadSize。
	MaxFileSizeMax = 10 * 1024 * 1024 * 1024
	// 背景图 URL 最大长度（含 data: 之外的普通 http(s) URL）。
	BackgroundURLMaxLen = 2048
	// 页脚自定义内容最大长度。
	FooterTextMaxLen = 2000
	// 备案号最大长度。
	FooterBeianMaxLen = 128
	// 通知标题/内容最大长度。
	NotifyTitleMaxLen   = 128
	NotifyContentMaxLen = 2000
	// 回收扫描间隔边界（秒）：最快 1 分钟一轮，最慢 1 天一轮。
	RecycleIntervalMin = 60
	RecycleIntervalMax = 86400
	// 全局存储时长上限（天）：0=不限制，最长 10 年。
	RetentionDaysMax = 3650
	// 防盗链白名单最大长度。
	HotlinkWhitelistMaxLen = 2048
	// 直链有效期边界（秒）。
	DirectLinkExpireMin = 60
	DirectLinkExpireMax = 3600
)

// KVSchemaEntry 配置键元数据：类型 / 默认值 / 说明，供管理端 UI 与文档生成。
type KVSchemaEntry struct {
	Key         string // KV 键名
	Type        string // string | int | int64 | bool | []string
	Default     any    // 默认值（与 defaults() 保持一致，测试保证同步）
	Min         int64  // 数值键最小值（字符串键为长度下界）
	Max         int64  // 数值键最大值（字符串键为长度上界；-1 不限制）
	Description string // 中文说明
}

// KVSchema 26.9 全量配置键 schema 表（含既有策略键，供管理端/文档/AI 校验）。
// 注意：Default 与 config defaults() 逐一对应（schema_test 保证）。
func KVSchema() []KVSchemaEntry {
	return []KVSchemaEntry{
		// —— 需求 ① 背景图 ——
		{KeyBackgroundURL, "string", "", 0, BackgroundURLMaxLen, "背景图 URL 或上传后地址（空=主题默认）"},
		// —— 需求 ② 页脚 ——
		{KeyFooterText, "string", "", 0, FooterTextMaxLen, "页脚自定义内容（纯文本或受控 HTML 片段）"},
		{KeyFooterBeian, "string", "", 0, FooterBeianMaxLen, "备案号，展示于页脚"},
		// —— 需求 ③ 系统通知 ——
		{KeyNotifyEnabled, "int", 1, 0, 1, "系统通知开关：1 右上角悬浮窗展示 / 0 关闭"},
		{KeyNotifyTitle, "string", "系统通知", 0, NotifyTitleMaxLen, "通知标题"},
		{KeyNotifyContent, "string", "欢迎使用文件快传，拖拽或粘贴即可分享文本与文件。", 0, NotifyContentMaxLen, "通知内容（允许 <a> 等受控 HTML）"},
		// —— 需求 ④ 保存策略 ——
		{KeyMaxSaveSeconds, "int64", int64(0), 0, MaxSaveSecondsMax, "最长保存秒数上限，0=不限制（默认 7 天兜底）"},
		{KeyMaxSaveCount, "int", 0, 0, MaxSaveCountMax, "单次分享最大可取次数上限，0=不限制"},
		{KeyExpireStyle, "[]string", []string{"day", "hour", "minute", "forever", "count"}, -1, -1, "上传页可选过期方式白名单"},
		// —— 需求 ④ 上传频率限制（既有键对齐参考）——
		{KeyUploadCount, "int", 10, 1, 10000, "频率窗口内允许的上传次数"},
		{KeyUploadMinute, "int", 1, 1, 1440, "上传频率窗口（分钟）"},
		// —— 需求 ④⑩ 存储策略 ——
		{KeyMaxFileSize, "int64", int64(0), 0, MaxFileSizeMax, "存储策略-单文件上限（字节），0=回落 uploadSize"},
		{KeyUploadSize, "int64", int64(1024 * 1024 * 10), 1024, MaxFileSizeMax, "单文件上限（字节），参考实现语义"},
		{KeyAllowedTypes, "[]string", []string{"*"}, -1, -1, "允许上传类型白名单（\"*\" 不限制）"},
		{KeyStorageLimit, "int64", int64(0), 0, -1, "站点总容量（字节），0=不限制"},
		{KeyOpenUpload, "int", 1, 0, 1, "游客上传开关：1 开 / 0 需管理员登录"},
		// —— 26.9 存储引擎（热切换；引擎参数键沿用 defaults() 既有键，管理端经 config get/update 读写）——
		{KeyStorageEngine, "string", "", 0, 16, "当前存储引擎：local|s3|webdav（热切换，健康检查通过才生效；空=回落启动值 FCB_STORAGE_ENGINE）"},
		{KeySiteDomain, "string", "", 0, 256, "站点对外域名（http(s)://host[:port]，不带路径；空=分享链接用当前访问地址）"},
		{KeyUploadRate, "int64", "0", 0, 1073741824, "上传带宽字节/秒（0=不限速；范围 0~1 GiB/s）"},
		{KeyDownloadRate, "int64", "0", 0, 1073741824, "下载带宽字节/秒（0=不限速；范围 0~1 GiB/s）"},
		// —— 26.9 回收与下载安全 ——
		{KeyRecycleEnabled, "int", 1, 0, 1, "过期分享自动回收开关：1 定时清理过期记录与存储对象 / 0 关闭"},
		{KeyRecycleInterval, "int64", int64(1800), RecycleIntervalMin, RecycleIntervalMax, "回收扫描间隔（秒；范围 60~86400，默认 30 分钟）"},
		{KeyRetentionDays, "int64", int64(0), 0, RetentionDaysMax, "全局最长存储时长（天）：上传超过该天数的分享将被回收，0=不限制"},
		{KeyDedupEnabled, "int", 1, 0, 1, "SHA512 内容去重：相同文件仅存储一份（多分享引用同一对象）"},
		{KeyHotlinkEnabled, "int", 0, 0, 1, "下载防盗链：校验 Referer 白名单（空 Referer 放行）"},
		{KeyHotlinkWhitelist, "string", "", 0, HotlinkWhitelistMaxLen, "防盗链白名单：逗号分隔域名（如 a.com,b.org；空=仅本站域名）"},
		{KeyDirectDownload, "int", 1, 0, 1, "对象存储直链下载：S3 引擎时 302 跳转到限时预签名 URL（不走服务器代理）"},
		{KeyDirectLinkExpire, "int64", int64(900), DirectLinkExpireMin, DirectLinkExpireMax, "直链有效期（秒；范围 60~3600，默认 15 分钟；不超过分享剩余时效）"},
	}
}