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. 配置项

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

```dotenv
# 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 能正确迁移。
- 管理员操作会实际输出结构化审计日志。
- 首次访问不会创建数据库用户；保存昵称后才生成正式账号。
- 保存昵称前后账号设置界面状态正确，移动端页面无水平溢出，浏览器控制台无错误。