MeBox/.workbuddy/memory/MEMORY.md

MediaStationGo 项目约定

项目信息

• 仓库：https://github.com/ShukeBta/MediaStationGo
• 本地路径：D:\项目\MediaStationGo
• 技术栈：Go 1.25 + Gin + GORM + SQLite / React 18 + Vite + Tailwind CSS + Zustand

构建方式（裸机 Windows）

# 后端
cd D:/项目/MediaStationGo
go build ./cmd/server    # 生成 server.exe

# 前端
cd D:/项目/MediaStationGo/web
npm install && npm run build    # 生成 web/dist/

# 配置
cp config.example.yaml config.yaml
mkdir -p data cache

启动命令

cd D:/项目/MediaStationGo
./server.exe
# 或带环境变量：
MEDIASTATION_APP_PORT=8080 MEDIASTATION_APP_DATA_DIR=./data MEDIASTATION_APP_WEB_DIR=./web/dist ./server.exe

默认配置

• 端口：8080
• 管理员：admin / admin123（首次登录提示改密）
• 数据目录：./data
• 缓存目录：./cache

关键 API 端点

• GET /api/health - 健康检查（无需认证）
• POST /api/auth/login - 登录获取 JWT
• GET /api/stats - 系统统计（需认证）
• GET /api/libraries - 媒体库列表（需认证）
• GET /api/admin/users - 用户管理（需 admin）

注意事项

• Docker Desktop 未启动时使用裸机构建
• Go 1.22 会自动下载 1.25 工具链（GOTOOLCHAIN=auto）
• FFmpeg/ffprobe 需要单独安装才能使用媒体扫描和转码功能
• DB 迁移：model.Base 嵌入 gorm.DeletedAt，如从旧版升级需手动 ALTER TABLE api_configs ADD COLUMN deleted_at datetime, created_at datetime
• 前端重建：修改后端代码后记得 npm run build 重建 dist

服务容器 (internal/service/service.go)

• SiteService 已注册为 Container.Site
• SiteHandler 位于 internal/handler/site_handler.go，支持 List/Get/Create/Update/Delete/Test/SiteTypes/AuthTypes
• 站点路由注册于 authed 组：/api/sites（7条）

前端 Admin 调度器面板

• 后端只支持 schedulerAPI.status() 和 schedulerAPI.run(name)
• 不支持 enable/disable 切换（后端无对应 API）

前端站点管理页面 (2026-05-16 新增)

• API 客户端：web/src/api/sites.ts，对接 8 个端点（list/get/create/update/remove/test/types/authTypes）
• 页面组件：web/src/pages/SitesPage.tsx，完整 CRUD + 测试 + 弹窗
• 路由：/sites（RequireAdmin），已集成到 App.tsx
• 侧边栏：管理区「站点管理」链接（Globe 图标）
• AdminPage Tab：新增「站点管理」默认激活 Tab，内嵌 SitesPage
• 站点类型：nexusphp / gazelle / unit3d / mteam / discuz / custom_rss
• 认证方式：cookie / api_key / auth_header
• 模型字段：Site{Name, Type(not "site_type"), URL(not "base_url"), AuthType, Cookie, APIKey, AuthHeader, Enabled, IsDefault, Extra} — 注意 Go 后端与 Python 后端的字段名差异

UI 修复与优化 (2026-05-16 第二阶段)

搜索页 & 收藏页空白修复

• 收藏页根因：后端 GET /api/favourites 在无数据时返回 {"items": null}，前端 playbackAPI.listFavourites() 提取 r.data.items 得到 null，items.length 抛出 TypeError → React 白屏
• 修复：FavouritesPage 增加 data ?? [] 空值保护，添加 .catch 错误处理、重试按钮、空状态提示
• 搜索页修复：增加错误处理，空查询不再发请求（避免无效 API 调用），添加 idle/empty/error 三态 UI

AdminPage 去重 & APIConfigs 重构

• 问题：原「API 配置」独立页面 (/api-configs) 与 AdminPage 内「设置」Tab 功能重叠
• 方案：
  • AdminPage 新增「外部API」Tab（api），嵌入新建的 APIConfigsPanel 组件
  • 原「设置」Tab 重命名为「系统设置」以区分用途
  • 侧边栏移除「API 配置」独立链接（KeyRound图标）
  • /api-configs 路由改为 <Navigate to="/admin" replace />
• APIConfigsPanel：紧凑表格布局（Provider | 密钥掩码 | 状态徽章 | 操作按钮），点击编辑后行内展开表单，替代原先卡片式布局
• 文件变更：新增 web/src/components/APIConfigsPanel.tsx；修改 AdminPage.tsx、Layout.tsx、App.tsx；保留 APIConfigsPage.tsx 但不再路由引用