docs: define multi-user V1 architecture

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. 测试、迁移兼容性、备份与部署