TECHNICAL_DEBT

技术债与路线图 (Technical Debt & Roadmap)

本文档记录了项目当前已知的设计缺陷、待改进项以及长期的技术规划。

⚠️ 错误处理与日志 (Error Handling & Logging)

现状

当前项目内的错误管理较为混乱，尤其是 playerStore 中。

• 很多函数有潜在抛出错误的可能，但未被显式捕获。
• playerStore 的调用方大多是 "fire-and-forget"，只有少部分处理了错误。

改进目标

• 引入 Result 模式: 使用 neverthrow 包装潜在的错误操作，替代 try-catch。
• 日志标准化: 在 Service 和 Facade 层添加更详细的结构化日志。
• Sentry 上报策略: 明确上报边界。建议：非三方 API 调用导致的系统内部错误，都应该上报。

🐛 已知问题：分 P 视频处理

目前 Bilibili API 的限制导致无法完美解决此问题。

问题描述

B 站视频唯一可播放单位是 (bvid, cid)，但在本项目中存在两种入口：

1. 整视频入口 (isMultiPage = false): 无 cid，默认播放第一 P。
2. 分 P 入口 (isMultiPage = true): 已知 cid。

这导致同一个视频的第一 P 可能对应数据库中的两条记录，且无法简单去重。

困难点

1. 可靠性: 分 P 顺序不可靠，UP 主可能删除分 P。
2. 性能: 批量获取 cid 成本过高，容易触发风控，导致导入歌单时无法预先获取 cid 进行去重。

暂行方案

目前维持现状，允许并在 UI 上展示这两种状态。