数据模型

API 请求和响应中使用的数据结构定义。

模型索引

模型	说明
audioTracksResponse	包含 1 个字段
AutoScanSetting	包含 2 个字段
dirValidateRequest	包含 1 个字段
dirValidateResponse	包含 5 个字段
equalizerSetting	包含 3 个字段
githubProxySetting	包含 1 个字段
hlsProxySettingRequest	包含 1 个字段
httpProxySetting	包含 1 个字段
jsPluginBatchUpdateResponse	包含 6 个字段
jsPluginBatchUpdateResult	包含 8 个字段
jsPluginUploadResponse	包含 5 个字段
jsPluginUploadResult	包含 4 个字段
libraryBrowseSetting	包含 1 个字段
libraryBrowseView	包含 2 个字段
logLevelSettingRequest	包含 1 个字段
MusicPathSetting	包含 4 个字段
pluginAutoUpdateSetting	包含 1 个字段
pluginHealthResponse	包含 1 个字段
pluginKeepAliveSetting	包含 1 个字段
pluginRegistriesSetting	包含 1 个字段
pluginTabEntry	包含 3 个字段
proxyAllowlistSettingRequest	包含 1 个字段
registryInstallRequest	包含 4 个字段
registryPluginEntry	包含 12 个字段
registryRefreshRequest	包含 7 个字段
registryRefreshResponse	包含 5 个字段
remoteTitleSourceRequest	包含 1 个字段
scanAutoCreatePlaylistsRequest	包含 1 个字段
scanPlaylistModeRequest	包含 1 个字段
scanPlaylistModeResponse	包含 1 个字段
ScanRequest	包含 2 个字段
scanTitleSourceRequest	包含 1 个字段
startFingerprintRequest	包含 1 个字段
tabConfigSetting	包含 3 个字段
userPreferencesSetting	包含 6 个字段
WriteSongTagsRequest	包含 13 个字段
JSPlugin	包含 23 个字段
RegistryConfig	包含 4 个字段
BatchDeletePlaylistsRequest	包含 1 个字段
BatchDeletePlaylistsResponse	包含 1 个字段
BatchDeleteSongsRequest	包含 2 个字段
BatchDeleteSongsResponse	包含 1 个字段
Config	包含 4 个字段
CreateConfigRequest	包含 2 个字段
ErrorResponse	包含 2 个字段
ImportResult	包含 5 个字段
JSPluginStatus	string
LoginRequest	包含 2 个字段
LoginResponse	包含 4 个字段
Playlist	包含 9 个字段
RefreshTokenRequest	包含 1 个字段
RevokeTokenRequest	包含 1 个字段
SetPlaylistVisibilityRequest	包含 1 个字段
Song	包含 35 个字段
SuccessResponse	包含 1 个字段
TokenInfo	包含 8 个字段
UpdateConfigRequest	包含 1 个字段
UpdatePlaylistRequest	包含 5 个字段
UpgradeProgress	包含 4 个字段
AudioTrackInfo	包含 5 个字段
CacheConfig	包含 4 个字段
CacheConfigResponse	包含 5 个字段
CacheStats	包含 3 个字段
FingerprintProgress	包含 4 个字段
MetadataRefreshProgress	包含 4 个字段
OrganizeItem	包含 2 个字段
OrganizePreviewResult	包含 5 个字段
OrganizeResult	包含 4 个字段
RefreshResponse	包含 4 个字段
ScanProgress	包含 14 个字段
ScanStatus	string
HealthClass	string
Outcome	包含 6 个字段
OutcomeResult	string
PluginHealthSnapshot	包含 5 个字段

audioTracksResponse {#handlers-audiotracksresponse}

完整名称：handlers.audioTracksResponse

类型： object

字段	类型	必填	说明
tracks	AudioTrackInfo[]	否

---

AutoScanSetting {#handlers-autoscansetting}

完整名称：handlers.AutoScanSetting

类型： object

字段	类型	必填	说明
enabled	boolean	否
interval_seconds	integer	否

---

dirValidateRequest {#handlers-dirvalidaterequest}

完整名称：handlers.dirValidateRequest

类型： object

字段	类型	必填	说明
path	string	否

---

dirValidateResponse {#handlers-dirvalidateresponse}

完整名称：handlers.dirValidateResponse

类型： object

字段	类型	必填	说明
created	boolean	否
error	string	否
free_size	integer	否
total_size	integer	否
valid	boolean	否

---

equalizerSetting {#handlers-equalizersetting}

完整名称：handlers.equalizerSetting

类型： object

字段	类型	必填	说明
bands	number[]	否
enabled	boolean	否
preset	string	否

---

githubProxySetting {#handlers-githubproxysetting}

完整名称：handlers.githubProxySetting

类型： object

字段	类型	必填	说明
proxy	string	否

---

hlsProxySettingRequest {#handlers-hlsproxysettingrequest}

完整名称：handlers.hlsProxySettingRequest

类型： object

字段	类型	必填	说明
enabled	boolean	否

---

httpProxySetting {#handlers-httpproxysetting}

完整名称：handlers.httpProxySetting

类型： object

字段	类型	必填	说明
proxy	string	否

---

jsPluginBatchUpdateResponse {#handlers-jspluginbatchupdateresponse}

完整名称：handlers.jsPluginBatchUpdateResponse

类型： object

字段	类型	必填	说明
failed	integer	否
message	string	否
results	jsPluginBatchUpdateResult[]	否
skipped	integer	否
total	integer	否
updated	integer	否

---

jsPluginBatchUpdateResult {#handlers-jspluginbatchupdateresult}

完整名称：handlers.jsPluginBatchUpdateResult

类型： object

字段	类型	必填	说明
current_version	string	否
entry_path	string	否
error	string	否
has_update	boolean	否
new_version	string	否
plugin_id	integer	否
plugin_name	string	否
success	boolean	否

---

jsPluginUploadResponse {#handlers-jspluginuploadresponse}

完整名称：handlers.jsPluginUploadResponse

类型： object

字段	类型	必填	说明
failed	integer	否
message	string	否
results	jsPluginUploadResult[]	否
success	integer	否
total	integer	否

---

jsPluginUploadResult {#handlers-jspluginuploadresult}

完整名称：handlers.jsPluginUploadResult

类型： object

字段	类型	必填	说明
error	string	否
file_name	string	否
plugin	JSPlugin	否
success	boolean	否

---

libraryBrowseSetting {#handlers-librarybrowsesetting}

完整名称：handlers.libraryBrowseSetting

类型： object

字段	类型	必填	说明
views	libraryBrowseView[]	否

---

libraryBrowseView {#handlers-librarybrowseview}

完整名称：handlers.libraryBrowseView

类型： object

字段	类型	必填	说明
key	string	否
visible	boolean	否

---

logLevelSettingRequest {#handlers-loglevelsettingrequest}

完整名称：handlers.logLevelSettingRequest

类型： object

字段	类型	必填	说明
level	string	否

---

MusicPathSetting {#handlers-musicpathsetting}

完整名称：handlers.MusicPathSetting

类型： object

字段	类型	必填	说明
auto_create_exclude_dirs	string[]	否
exclude_dirs	string[]	否
exclude_paths	string[]	否
path	string	否

---

pluginAutoUpdateSetting {#handlers-pluginautoupdatesetting}

完整名称：handlers.pluginAutoUpdateSetting

类型： object

字段	类型	必填	说明
enabled	boolean	否

---

pluginHealthResponse {#handlers-pluginhealthresponse}

完整名称：handlers.pluginHealthResponse

类型： object

字段	类型	必填	说明
plugins	PluginHealthSnapshot[]	否

---

pluginKeepAliveSetting {#handlers-pluginkeepalivesetting}

完整名称：handlers.pluginKeepAliveSetting

类型： object

字段	类型	必填	说明
plugins	string[]	否

---

pluginRegistriesSetting {#handlers-pluginregistriessetting}

完整名称：handlers.pluginRegistriesSetting

类型： object

字段	类型	必填	说明
registries	RegistryConfig[]	否

---

pluginTabEntry {#handlers-plugintabentry}

完整名称：handlers.pluginTabEntry

类型： object

字段	类型	必填	说明
entry_path	string	否
name	string	否
plugin_id	integer	否

---

proxyAllowlistSettingRequest {#handlers-proxyallowlistsettingrequest}

完整名称：handlers.proxyAllowlistSettingRequest

类型： object

字段	类型	必填	说明
allowlist	string[]	否

---

registryInstallRequest {#handlers-registryinstallrequest}

完整名称：handlers.registryInstallRequest

类型： object

字段	类型	必填	说明
download_url	string	否
github_proxy	string	否
source_url	string	否	SourceURL 插件所属订阅源 URL。「全部」聚合模式安装时回传：
当未显式提供 token 时，后端据此从 plugin_registries 配置解析该源的 token。
token	string	否

---

registryPluginEntry {#handlers-registrypluginentry}

完整名称：handlers.registryPluginEntry

类型： object

字段	类型	必填	说明
author	string	否
description	string	否
download_url	string	否
entry_path	string	否
has_update	boolean	否
homepage	string	否
icon	string	否
installed	boolean	否
installed_version	string	否
name	string	否
source_url	string	否	SourceURL 该插件所属订阅源 URL（仅「全部」聚合模式返回），
安装时回传给后端以按源解析私有源 token。
version	string	否

---

registryRefreshRequest {#handlers-registryrefreshrequest}

完整名称：handlers.registryRefreshRequest

类型： object

字段	类型	必填	说明
all_sources	boolean	否
github_proxy	string	否
page	integer	否
page_size	integer	否
registry_url	string	否
search	string	否
token	string	否

---

registryRefreshResponse {#handlers-registryrefreshresponse}

完整名称：handlers.registryRefreshResponse

类型： object

字段	类型	必填	说明
page	integer	否
page_size	integer	否
plugins	registryPluginEntry[]	否
total	integer	否
warnings	string[]	否

---

remoteTitleSourceRequest {#handlers-remotetitlesourcerequest}

完整名称：handlers.remoteTitleSourceRequest

类型： object

字段	类型	必填	说明
title_source	string	否	可选值: tag, filename 示例: "filename"

---

scanAutoCreatePlaylistsRequest {#handlers-scanautocreateplaylistsrequest}

完整名称：handlers.scanAutoCreatePlaylistsRequest

类型： object

字段	类型	必填	说明
enabled	boolean	否

---

scanPlaylistModeRequest {#handlers-scanplaylistmoderequest}

完整名称：handlers.scanPlaylistModeRequest

类型： object

字段	类型	必填	说明
mode	string	否	可选值: directory, top_level, bubble_up 示例: "directory"

---

scanPlaylistModeResponse {#handlers-scanplaylistmoderesponse}

完整名称：handlers.scanPlaylistModeResponse

类型： object

字段	类型	必填	说明
mode	string	否	示例: "directory"

---

ScanRequest {#handlers-scanrequest}

完整名称：handlers.ScanRequest

类型： object

字段	类型	必填	说明
paths	string[]	否	Paths 为目录级定向扫描（Issue #262）：为空时扫描整个音乐根目录（默认行为）；
非空时只扫描给定目录（含子目录），过期记录清理也仅收敛到这些目录之内。
每个目录必须位于音乐根目录之下，否则返回 400。
reimport	boolean	否

---

scanTitleSourceRequest {#handlers-scantitlesourcerequest}

完整名称：handlers.scanTitleSourceRequest

类型： object

字段	类型	必填	说明
title_source	string	否	可选值: tag, filename 示例: "tag"

---

startFingerprintRequest {#handlers-startfingerprintrequest}

完整名称：handlers.startFingerprintRequest

类型： object

字段	类型	必填	说明
recompute_all	boolean	否

---

tabConfigSetting {#handlers-tabconfigsetting}

完整名称：handlers.tabConfigSetting

类型： object

字段	类型	必填	说明
plugin_tabs	pluginTabEntry[]	否
show_library	boolean	否
show_playlists	boolean	否

---

userPreferencesSetting {#handlers-userpreferencessetting}

完整名称：handlers.userPreferencesSetting

类型： object

字段	类型	必填	说明
audio_quality	string	否
local_cache_max_size	integer	否
play_mode	string	否
playlist_view_mode	string	否
theme_mode	string	否
volume	number	否

---

WriteSongTagsRequest {#handlers-writesongtagsrequest}

完整名称：handlers.WriteSongTagsRequest

类型： object

字段	类型	必填	说明
album	string	否
artist	string	否
clear_cover	boolean	否
cover_data	string	否
cover_url	string	否
genre	string	否
language	string	否
lyrics	string	否
rename_file	boolean	否	RenameFile 为 true 时按新标题重命名本地音频文件（保留原目录与扩展名），仅对本地非 CUE 歌曲生效。
style	string	否
title	string	否
track	string	否
year	integer	否

---

JSPlugin {#jsplugin-jsplugin}

完整名称：jsplugin.JSPlugin

类型： object

字段	类型	必填	说明
author	string	否
created_at	string	否
description	string	否
download_url	string	否
entry_hash	string	否	main.js/main.jsc 内容 SHA256
entry_path	string	否	路由前缀（如 "myplugin"）
external_paths	string[]	否	可访问的外部绝对路径目录
file_mod_time	string	否
file_path	string	否	ZIP 文件相对路径
homepage	string	否
icon	string	否
id	integer	否
license	string	否
main	string	否	入口文件路径（如 "main.js"）
min_host_version	string	否
name	string	否
permissions	string[]	否	权限列表
public_paths	string[]	否	无需 JWT 认证的路径前缀
status	JSPluginStatus	否
update_url	string	否
updated_at	string	否
version	string	否
zip_hash	string	否	ZIP 文件 SHA256

---

RegistryConfig {#jsplugin-registryconfig}

完整名称：jsplugin.RegistryConfig

类型： object

字段	类型	必填	说明
enabled	boolean	否
name	string	否
token	string	否
url	string	否

---

BatchDeletePlaylistsRequest {#models-batchdeleteplaylistsrequest}

完整名称：models.BatchDeletePlaylistsRequest

类型： object

字段	类型	必填	说明
ids	integer[]	否	要删除的歌单 ID 列表 示例: [1]

---

BatchDeletePlaylistsResponse {#models-batchdeleteplaylistsresponse}

完整名称：models.BatchDeletePlaylistsResponse

类型： object

字段	类型	必填	说明
deleted	integer	否	实际删除的数量 示例: 3

---

BatchDeleteSongsRequest {#models-batchdeletesongsrequest}

完整名称：models.BatchDeleteSongsRequest

类型： object

字段	类型	必填	说明
delete_files	boolean	否	是否同步删除本地音频文件 示例: false
ids	integer[]	否	要删除的歌曲 ID 列表 示例: [1]

---

BatchDeleteSongsResponse {#models-batchdeletesongsresponse}

完整名称：models.BatchDeleteSongsResponse

类型： object

字段	类型	必填	说明
deleted	integer	否	实际删除的数量 示例: 3

---

Config {#models-config}

完整名称：models.Config

类型： object

字段	类型	必填	说明
id	integer	否	配置ID 示例: 1
key	string	否	配置键 示例: "music_path"
updated_at	string	否	更新时间 示例: "2024-01-01T12:00:00Z"
value	string	否	配置值（JSON格式） 示例: "{\"path\":\"/music\"}"

---

CreateConfigRequest {#models-createconfigrequest}

完整名称：models.CreateConfigRequest

类型： object

字段	类型	必填	说明
key	string	是	配置键 示例: "music_path"
value	string	是	配置值（JSON 格式） 示例: "{\"path\":\"/music\"}"

---

ErrorResponse {#models-errorresponse}

完整名称：models.ErrorResponse

类型： object

字段	类型	必填	说明
detail	string	否	详细错误信息（可选） 示例: "详细错误信息"
error	string	否	错误信息 示例: "操作失败"

---

ImportResult {#models-importresult}

完整名称：models.ImportResult

类型： object

字段	类型	必填	说明
playlists_created	integer	否
playlists_merged	integer	否
songs_created	integer	否
songs_matched	integer	否
songs_skipped	integer	否

---

JSPluginStatus {#models-jspluginstatus}

完整名称：models.JSPluginStatus

类型： string

可选值：

• active
• inactive
• error

---

LoginRequest {#models-loginrequest}

完整名称：models.LoginRequest

类型： object

字段	类型	必填	说明
password	string	是	密码 示例: "admin"
username	string	是	用户名 示例: "admin"

---

LoginResponse {#models-loginresponse}

完整名称：models.LoginResponse

类型： object

字段	类型	必填	说明
access_token	string	否	Access Token 示例: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
expires_in	integer	否	Access Token 过期时间（秒） 示例: 604800
refresh_token	string	否	Refresh Token 示例: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
token_type	string	否	Token 类型 示例: "Bearer"

---

Playlist {#models-playlist}

完整名称：models.Playlist

类型： object

字段	类型	必填	说明
cover_url	string	否	封面图片 URL 示例: "https://example.com/playlist.jpg"
created_at	string	否	创建时间 示例: "2024-01-01T12:00:00Z"
description	string	否	歌单描述 示例: "收藏的经典歌曲"
id	integer	否	歌单 ID 示例: 1
labels	string[]	否	歌单标签，如 ["built_in"] 示例: ["[\"built_in\"]"]
name	string	否	歌单名称 示例: "我的最爱"
song_count	integer	否	歌曲数量 示例: 10
type	string	否	歌单类型：normal/radio 可选值: normal, radio 示例: "normal"
updated_at	string	否	最后更新时间 示例: "2024-01-01T12:00:00Z"

---

RefreshTokenRequest {#models-refreshtokenrequest}

完整名称：models.RefreshTokenRequest

类型： object

字段	类型	必填	说明
refresh_token	string	是	刷新令牌 示例: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

---

RevokeTokenRequest {#models-revoketokenrequest}

完整名称：models.RevokeTokenRequest

类型： object

字段	类型	必填	说明
reason	string	否	撤销原因 示例: "用户主动登出"

---

SetPlaylistVisibilityRequest {#models-setplaylistvisibilityrequest}

完整名称：models.SetPlaylistVisibilityRequest

类型： object

字段	类型	必填	说明
hidden	boolean	否	是否隐藏歌单 示例: true

---

Song {#models-song}

完整名称：models.Song

类型： object

字段	类型	必填	说明
added_at	string	否	添加时间 示例: "2024-01-01T12:00:00Z"
album	string	否	专辑名称 示例: "十一月的萧邦"
artist	string	否	艺术家/歌手 示例: "周杰伦"
bit_rate	integer	否	比特率（kbps） 示例: 320
cover_url	string	否	封面图片URL 示例: "https://example.com/cover.jpg"
cue_source_path	string	否	CUE 来源路径（非空表示 CUE 拆分歌曲）
cue_track_index	integer	否	CUE track 序号 (1-99)
dedup_key	string	否	去重 key(由插件定义,典型形态 "<platform>:<platform_id>");与 PluginEntryPath 组成 UNIQUE
duration	number	否	播放时长（秒） 示例: 253.5
file_modified_at	string	否	文件修改时间(mtime，本地歌曲扫描时记录；未知为 nil)
file_path	string	否	本地文件路径 示例: "/music/周杰伦/夜曲.mp3"
file_size	integer	否	文件大小（字节） 示例: 10485760
fingerprint	string	否	音频指纹(Chromaprint)
fingerprint_duration	number	否	指纹对应音频时长
format	string	否	音频格式 示例: "mp3"
genre	string	否	流派 示例: "Pop"
id	integer	否	歌曲ID 示例: 1
is_live	boolean	否	是否为直播流 示例: false
is_video	boolean	否	是否含真实视频轨(扫描时 ffprobe 探测,排除封面);客户端据此渲染画面/选择投屏 mime 示例: false
isrc	string	否	ISRC(国际标准录音编码)
language	string	否	语种 示例: "国语"
lyric_remote_url	string	否	lyric_source=url 时的原始 URL(运行时由 LyricFetcher 拉取)
lyric_url	string	否	歌词端点 URL(客户端唯一可见字段,指向 /api/v1/songs/{id}/lyric)
plugin_entry_path	string	否	音源插件 entryPath(网络歌曲) 示例: "my-source"
sample_rate	integer	否	采样率（Hz） 示例: 44100
source_cover_url	string	否	原始封面 URL(仅 JSON 输出,CoverURL 非空时保留原始值供编辑使用)
source_data	string	否	音源元数据 JSON(给插件 music/url 接口用,opaque)
source_url	string	否	原始音源 URL(仅 JSON 输出,radio/remote 类型返回原始流地址供编辑使用)
style	string	否	风格 示例: "抒情"
title	string	否	标题 示例: "夜曲"
track	string	否	音轨号，可为 "3" 或 "3/12"（轨号/总数） 示例: "3/12"
type	string	否	歌曲类型：local/remote/radio 可选值: local, remote, radio 示例: "local"
updated_at	string	否	最后更新时间 示例: "2024-01-01T12:00:00Z"
url	string	否	网络地址 示例: "https://example.com/song.mp3"
year	integer	否	发行年份 示例: 2005

---

SuccessResponse {#models-successresponse}

完整名称：models.SuccessResponse

类型： object

字段	类型	必填	说明
message	string	否	成功信息 示例: "操作成功"

---

TokenInfo {#models-tokeninfo}

完整名称：models.TokenInfo

类型： object

字段	类型	必填	说明
client_info	string	否	客户端信息 示例: "Mozilla/5.0 AppleWebKit/605.1.15"
created_at	string	否	创建时间 示例: "2024-01-01T12:00:00Z"
expires_at	string	否	过期时间 示例: "2024-01-08T12:00:00Z"
revoked_at	string	否	撤销时间 示例: "2024-01-01T12:00:00Z"
revoked_by	string	否	撤销者 示例: "user"
revoked_reason	string	否	撤销原因 示例: "用户主动登出"
token_id	string	否	令牌 ID 示例: "abc123"
token_type	string	否	令牌类型 可选值: access, refresh 示例: "access"

---

UpdateConfigRequest {#models-updateconfigrequest}

完整名称：models.UpdateConfigRequest

类型： object

字段	类型	必填	说明
value	string	是	配置值（JSON 格式） 示例: "{\"path\":\"/new_music\"}"

---

UpdatePlaylistRequest {#models-updateplaylistrequest}

完整名称：models.UpdatePlaylistRequest

类型： object

字段	类型	必填	说明
cover_path	string	否	封面图片本地路径（传空字符串清除） 示例: ""
cover_song_id	integer	否	从指定歌曲复制封面（与 cover_path/cover_url 互斥，优先级更高） 示例: 42
cover_url	string	否	封面图片 URL（传空字符串清除） 示例: ""
description	string	否	歌单描述 示例: "收藏的经典歌曲"
name	string	否	歌单名称 示例: "我的最爱"

---

UpgradeProgress {#models-upgradeprogress}

完整名称：models.UpgradeProgress

类型： object

字段	类型	必填	说明
current_step	string	否	当前步骤描述 示例: "正在下载新版本..."
error	string	否	错误信息（如有） 示例: "下载失败"
progress	integer	否	进度百分比 (0-100) 示例: 50
status	string	否	状态 可选值: idle, downloading, testing, replacing, restarting, completed, failed 示例: "downloading"

---

AudioTrackInfo {#services-audiotrackinfo}

完整名称：services.AudioTrackInfo

类型： object

字段	类型	必填	说明
codec	string	否
default	boolean	否
index	integer	否
language	string	否
title	string	否

---

CacheConfig {#services-cacheconfig}

完整名称：services.CacheConfig

类型： object

字段	类型	必填	说明
cache_dir	string	否	自定义缓存目录，空字符串表示使用默认目录
max_size	integer	否	最大缓存大小（字节），0 表示无限制
transcode_format	string	否	TranscodeFormat 缓存网络歌曲落盘时统一转码的目标格式（mp3/m4a/ogg/flac/wav）。
空字符串表示不转码、按上游原格式落盘（默认）。缺 ffmpeg 或转码失败时优雅降级保留原格式。
transcode_quality	string	否	TranscodeQuality 转码目标码率（128/192/320），空或非法值表示最高质量。仅对有损格式生效。

---

CacheConfigResponse {#services-cacheconfigresponse}

完整名称：services.CacheConfigResponse

类型： object

字段	类型	必填	说明
cache_dir	string	否
default_cache_dir	string	否
max_size	integer	否
transcode_format	string	否
transcode_quality	string	否

---

CacheStats {#services-cachestats}

完整名称：services.CacheStats

类型： object

字段	类型	必填	说明
file_count	integer	否	文件数量
max_size	integer	否	最大缓存大小（字节），0 表示无限制
total_size	integer	否	总大小（字节）

---

FingerprintProgress {#services-fingerprintprogress}

完整名称：services.FingerprintProgress

类型： object

字段	类型	必填	说明
computed	integer	否
failed	integer	否
status	string	否	idle, running, done
total	integer	否

---

MetadataRefreshProgress {#services-metadatarefreshprogress}

完整名称：services.MetadataRefreshProgress

类型： object

字段	类型	必填	说明
failed	integer	否
processed	integer	否
status	string	否
total	integer	否

---

OrganizeItem {#services-organizeitem}

完整名称：services.OrganizeItem

类型： object

字段	类型	必填	说明
id	integer	否
target_path	string	否

---

OrganizePreviewResult {#services-organizepreviewresult}

完整名称：services.OrganizePreviewResult

类型： object

字段	类型	必填	说明
error	string	否
id	integer	否
new_path	string	否
old_path	string	否
status	string	否

---

OrganizeResult {#services-organizeresult}

完整名称：services.OrganizeResult

类型： object

字段	类型	必填	说明
error	string	否
file_path	string	否
id	integer	否
status	string	否

---

RefreshResponse {#services-refreshresponse}

完整名称：services.RefreshResponse

类型： object

字段	类型	必填	说明
access_token	string	否
expires_in	integer	否
refresh_token	string	否
token_type	string	否

---

ScanProgress {#services-scanprogress}

完整名称：services.ScanProgress

类型： object

字段	类型	必填	说明
cleaned_files	integer	否	清理的过期文件数
cue_split_sources	integer	否	splitting_cue 阶段已处理的 CUE 来源数
current_file	string	否	当前处理的文件
discovered_files	integer	否	scanning 阶段已发现的音频文件数
end_time	string	否	结束时间
error	string	否	错误信息
failed_files	integer	否	失败的文件数
imported_files	integer	否	已导入文件数
local_song_count	integer	否	扫描完成后数据库中本地歌曲总数
scanned_files	integer	否	已扫描文件数
skipped_files	integer	否	跳过的文件数（已存在）
start_time	string	否	开始时间
status	any	否	当前状态
total_files	integer	否	总文件数

---

ScanStatus {#services-scanstatus}

完整名称：services.ScanStatus

类型： string

可选值：

• idle
• scanning
• importing
• splitting_cue
• creating_playlists
• completed
• failed
• cancelling
• cancelled

---

HealthClass {#source-healthclass}

完整名称：source.HealthClass

类型： string

可选值：

• green
• yellow
• red

---

Outcome {#source-outcome}

完整名称：source.Outcome

类型： object

字段	类型	必填	说明
latency_ns	integer	否	纳秒;swagger 显式声明避免 time.Duration 解析失败
plugin_entry_path	string	否
reason	string	否
result	OutcomeResult	否
size_bytes	integer	否
timestamp	string	否

---

OutcomeResult {#source-outcomeresult}

完整名称：source.OutcomeResult

类型： string

可选值：

• success
• network_fail
• probe_fail
• validation_fail
• plugin_invocation_fail

---

PluginHealthSnapshot {#source-pluginhealthsnapshot}

完整名称：source.PluginHealthSnapshot

类型： object

字段	类型	必填	说明
class	HealthClass	否
last_failures	Outcome[]	否	最近 N 次失败,便于排查
plugin_entry_path	string	否
samples	integer	否
success_rate	number	否

---