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