docs/UPDATE_NOTES.md

本轮功能更新说明

本文记录从 Music-Together-Pro-UNM-Support 分支移植并在当前项目中完成适配的功能，涵盖用户数据持久化、多音源、账号系统、服务器管理员、权限安全和审计日志。

1. 用户数据持久化

• 新增 SQLite 数据库，默认地址为 file:./data/music-together.db，可通过 DATABASE_URL 修改。
• 用户账号资料、密码 Hash、角色和平台登录 Cookie 均可在服务器重启后恢复。
• 用户再次访问时可通过身份 Cookie 恢复账号及对应的房间身份。
• 平台 Cookie 加密后再持久化，避免以明文形式保存第三方平台凭据。
• 用户 ID 使用不区分大小写的唯一性约束，不能注册或修改为已存在的 ID。

当前房间和播放状态仍保存在内存中。服务器重启后，账号数据会保留，但正在运行的房间会消失。

2. 更广的音源与音质支持

• 扩展网易云音乐相关能力，并接入 QQ 音乐、酷狗音乐等音源。
• 增加多平台搜索、歌曲信息解析、播放地址获取和歌单解析能力。
• 支持按平台选择更多音质，包括标准、高品质、无损及平台提供的更高规格音质。
• 客户端会根据音源展示可用音质，服务端负责对应音源和音质的解析与回退。

第三方平台接口和高音质播放能力仍受账号权限、Cookie 有效期、地区限制及平台接口可用性影响。

3. 账号功能

• 账号现在包含：账号 ID、昵称、密码、头像和角色。
• 用户可修改自己的昵称、头像、密码和账号 ID。
• 修改密码时需要验证当前密码，验证失败返回 401。
• 修改账号 ID 时会检查格式、重复 ID、系统保留 ID和管理员配置 ID；冲突返回 409，非法或不可占用的 ID 返回 400。
• 普通用户只能修改自己的账号资料，不能指定其他用户作为修改目标，也不能自行提升为服务器管理员。
• 未登录或身份失效时，会按接口要求返回 401、403 或 409，不会绕过账号归属检查。

4. 延迟创建正式账号

账号生成逻辑已调整为“设置昵称后才创建正式账号”：

1. 用户首次访问时只签发临时身份 Cookie。
2. 此时不会向 users 表写入账号，也不会在客户端保存或展示正式用户 ID。
3. 用户保存昵称，或使用需要正式身份的创建/加入房间流程后，服务器才生成唯一账号 ID并创建账号。
4. 正式账号创建后，账号 ID、头像和密码设置等控件才会开放。

未设置昵称时：

• GET /api/auth/me 返回 204 No Content。
• 密码和头像设置接口返回 409 Conflict。
• 设置页显示“保存昵称后生成账号 ID”，不会暴露临时身份值。

5. 修改账号 ID时的数据迁移

账号 ID 修改不是简单地改一个字段。服务端会同步迁移与旧 ID 关联的数据和运行时身份，包括：

• 用户资料、密码 Hash 和账号角色。
• 已保存的平台 Cookie。
• 房主、主持人和房间管理员身份。
• WebSocket 用户映射与重连票据。

迁移完成后，原账号 ID 不再代表该用户；新的身份 Cookie 和运行时映射会继续指向同一账号。

6. 服务器管理员

• 新增服务器管理员角色和管理界面。
• 可通过 SERVER_ADMIN_IDS 配置初始服务器管理员账号 ID，多个 ID使用英文逗号分隔。
• 服务器管理员可查看用户和房间列表、重置用户密码、删除用户以及解散房间。
• 配置中的管理员 ID和系统保留 ID不能被普通用户抢占。

权限分层

服务器管理员和房间管理员是两套独立身份：

• 服务器管理员负责服务器级用户与房间治理。
• 房主、主持人、房间管理员负责当前房间内的管理操作。
• 服务器管理员身份不会覆盖或清除房间角色，房间角色也不会自动获得服务器管理权限。
• 所有敏感操作都在服务端重新校验身份和目标对象，不能仅靠修改客户端请求获得权限。

7. 管理员审计日志

管理员操作已按项目原有日志格式增加结构化审计记录，包含操作者、目标对象、操作结果及必要上下文。

新增的主要审计事件包括：

• admin.access_denied
• admin.users_viewed
• admin.rooms_viewed
• admin.user_deleted
• admin.user_delete_failed
• admin.user_delete_rejected
• admin.user_password_reset
• admin.user_password_reset_failed
• admin.user_password_reset_rejected
• admin.room_dissolved
• admin.room_dissolve_failed

房间管理日志同时增加 operatorIsServerAdmin 字段，用于区分操作来自房间权限还是服务器管理员权限。

8. 安全加固

• 账号资料修改以服务端认证身份为准，不接受客户端伪造的目标用户 ID。
• 普通用户不能读取或修改其他用户的敏感账号信息。
• 普通用户不能调用服务器管理员接口，越权访问返回 403 Forbidden。
• 账号 ID修改采用唯一性校验和事务迁移，防止重复 ID及只迁移部分数据。
• 密码只保存 Hash，不保存明文。
• 平台 Cookie 加密持久化，并绑定到账号身份。
• 删除用户、重置密码、解散房间等高风险管理员操作均记录成功、拒绝或失败结果。

9. 配置项

本轮涉及的主要环境变量如下：

# SQLite 数据库地址
DATABASE_URL=file:./data/music-together.db

# 服务器管理员账号 ID，多个值使用英文逗号分隔
SERVER_ADMIN_IDS=account-id-1,account-id-2

# 是否只通过 HTTPS发送身份 Cookie
IDENTITY_COOKIE_SECURE=false

部署时应使用持久化磁盘保存数据库文件，并在 HTTPS生产环境中启用安全 Cookie 配置。

10. 验证结果

本轮修改已完成以下验证：

• 项目完整构建通过。
• Prettier 格式检查通过。
• Git 差异空白检查通过。
• 普通用户跨账号修改注入测试通过。
• 普通用户访问管理员接口返回 403。
• 重复账号 ID返回 409。
• 管理员配置 ID抢占返回 400。
• 错误当前密码返回 401。
• 修改账号 ID后，房主身份和平台 Cookie 能正确迁移。
• 管理员操作会实际输出结构化审计日志。
• 首次访问不会创建数据库用户；保存昵称后才生成正式账号。
• 保存昵称前后账号设置界面状态正确，移动端页面无水平溢出，浏览器控制台无错误。