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