diff --git a/MULTIUSER_PLAN.md b/MULTIUSER_PLAN.md new file mode 100644 index 0000000..756c9a0 --- /dev/null +++ b/MULTIUSER_PLAN.md @@ -0,0 +1,90 @@ +# AM Downloader 多用户 V1 方案 + +## 目标 +在现有 Go + Gin + GORM + SQLite + 下载队列 + WebDAV 架构上增量加入多用户、权限、下载额度和兑换码,不推倒重写现有 Downloader。 + +## 角色与权限 +- `admin`:全部权限;用户、兑换码、系统设置、日志、全局 WebDAV Storage 管理。 +- `privileged`:普通下载能力 + WebDAV;可以配置自己的 WebDAV。 +- `user`:下载、历史、兑换额度;不能访问 WebDAV、系统设置或其他用户。 +- 底层使用 capability:`download`、`redeem`、`webdav`、`webdav_config`、`api`、`advanced_download`,避免以后扩展时绑定死角色。 + +## 设置隔离 +- 用户设置:账户、外观;特权用户额外有自己的 WebDAV。 +- 管理设置:`/admin/*`,只有管理员可见且后端强制校验。 +- 现有全局 AM API、下载目录、默认音质、WebDAV Storage 等属于管理员配置。 +- 前端隐藏不是安全措施;API 必须返回 401/403。 + +## WebDAV +- 管理员定义 Storage Root,例如 `/data/webdav`。 +- 特权用户拥有自己的 WebDAV 配置和独立根目录 `/data/webdav/{user_id}/`。 +- 禁止用户通过 `..`、绝对路径等逃逸 Storage Root。 +- WebDAV 权限和 WebDAV 配置权限分离,方便以后扩展。 +- 现有全局 WebDAV 继续作为系统级远程 Storage,逐步迁移为管理员配置。 + +## Credits +- 一首实际成功下载的歌曲消耗 1 credit。 +- 已存在且可复用的文件不扣 credit。 +- 新下载创建任务时预留 credit;成功 commit,失败 refund。 +- 同一任务重试不能重复扣费。 +- 批量任务按实际成功数量结算。 +- 所有额度变化进入不可变流水,不允许直接改余额。 + +## Redeem Code +- 管理员可按批次批量生成兑换码。 +- 每个兑换码可以有自定义 credits、有效期、备注。 +- 状态:`unused`、`used`、`expired`、`revoked`。 +- 数据库只保存 code hash;生成后提供复制/导出明文。 +- 兑换必须事务化,防止并发双兑。 +- 管理员可以作废兑换码、查看批次统计和兑换记录。 + +## 数据模型 +- `users` +- `user_permissions` +- `credit_accounts` +- `credit_transactions` +- `credit_reservations` +- `redeem_batches` +- `redeem_codes` +- `redeem_records` +- `webdav_configs` +- `audit_logs` +- `sessions` +- 现有 `tasks` 增加 `user_id`、`credit_reservation_id`,继续保留全局资源去重索引。 +- `settings` 继续保存管理员系统设置。 + +## 下载与去重 +不要简单把现有唯一键改成 `user_id + source + rid + quality`。用户任务与全局资源/文件应逻辑分离:同一资源可以被多个用户请求,但每个用户拥有自己的任务、额度流水和访问边界。第一阶段保持现有 Task 模型兼容,再逐步增加资源复用层。 + +## API 分层 +- `/api/auth/*`:登录、登出、当前用户。 +- `/api/tasks`:当前用户任务;所有查询按 user_id 隔离。 +- `/api/credits/*`:余额、流水、兑换。 +- `/api/webdav/*`:仅拥有 webdav 权限的用户。 +- `/api/admin/users/*`:管理员。 +- `/api/admin/redeem/*`:管理员。 +- `/api/admin/settings/*`:管理员。 +- `/api/admin/audit/*`:管理员。 + +## 安全 +- 密码只保存强哈希。 +- Session 使用随机不可预测 token,数据库保存 hash。 +- 登录限速。 +- 管理员敏感操作记录 audit log。 +- 额度操作必须事务化。 +- 兑换码不可明文持久化。 +- WebDAV 路径必须做目录边界校验。 +- 用户绝不能通过 API 读取其他用户 Task、Credit、WebDAV 配置。 + +## 实施顺序 +1. 数据模型与数据库迁移 +2. Session/Auth +3. 权限中间件 +4. Task 用户隔离 +5. Credit Ledger + Reservation +6. 下载成功/失败扣退额度 +7. Redeem Code +8. WebDAV 特权用户隔离 +9. 管理后台 API +10. 前端用户/特权/管理员界面 +11. 测试、迁移兼容性、备份与部署