79 lines
5.2 KiB
Markdown
79 lines
5.2 KiB
Markdown
# AM Downloader 交互界面 (UI) 重构与优化文档
|
||
|
||
## 1. 概述与背景
|
||
`am-downloader` 原先的 `index.html` 采用单页平铺逻辑，随着多用户鉴权、积分兑换、用户级 WebDAV 与管理员后台的引入，旧版界面存在层级分散、导航冗余、缺乏现代感与移动端适配生硬等问题。
|
||
|
||
本项目已完成系统级的前端现代化重构，并保持对后端原有 API 契约和前端 DOM 事件完全兼容，目前已在运行中的 Docker 容器环境（端口 `9540`）热更新上线生效。
|
||
|
||
---
|
||
|
||
## 2. 视觉设计系统规范
|
||
|
||
### 2.1 配色与质感（Modern Dark Glassmorphism）
|
||
- **深色基底**：主背景采用 `#080c14`，配合双色极光渐变暗影（翡翠绿 `#10b981` 与天蓝 `#38bdf8`），提升流媒体科技质感。
|
||
- **毛玻璃面板**：卡片与导航栏统一采用 `rgba(17, 26, 42, 0.75)` 配以 `backdrop-filter: blur(16px)`，边框引入半透明微发光分割线（`rgba(255, 255, 255, 0.08)`）。
|
||
- **字体与层级**：接入 `Plus Jakarta Sans` 作为主要无衬线英文字体，`JetBrains Mono` 作为代码、卡密与音质参数等宽字体。
|
||
|
||
---
|
||
|
||
## 3. 核心功能与架构重构细节
|
||
|
||
### 3.1 导航体系净化与精简
|
||
1. **移除顶部及移动端独立「设置」按钮**：
|
||
- 彻底移除了原先顶栏导航与移动端底栏的独立「设置」入口。
|
||
- 所有系统运行配置统一纳管在管理员后台内部，避免入口碎片化。
|
||
2. **下载按钮去除角标数字**：
|
||
- 移除桌面端导航与移动端底栏「下载」按钮后方突兀的数字徽章（Badge），保持导航栏整体视觉纯粹和谐。
|
||
- 保留 DOM 节点以保证后台任务轮询更新逻辑的向后兼容，不报错不中断。
|
||
|
||
### 3.2 管理控制台（Admin Center）全面重构
|
||
1. **分段式选项卡（Segmented Tabs）**：
|
||
- 废弃原有的“点击磁贴切换子面板再返回”繁琐交互，重构为顶部毛玻璃分段 Tab 栏：
|
||
- `👥 用户管理`
|
||
- `◎ 积分账本`
|
||
- `◇ 卡密批次`
|
||
- `≡ 审计日志`
|
||
- `⚙️ 全局设置`（由原“纳管设置”更名，系统 API、下载存储策略、全局 WebDAV 完整收拢在此）
|
||
- Tab 切换平滑无刷新，记忆当前选中状态。
|
||
|
||
2. **抽屉详情交互（Slide-over Drawer）**：
|
||
- 用户详情不再替换整页或跳转离开当前列表。
|
||
- 点击任意用户的「查看详情」时，桌面端由右侧平滑滑出毛玻璃抽屉面板，移动端自适应为底部滑起抽屉（Bottom Sheet）。
|
||
- 抽屉内置：账号角色与状态、密码重置、账号启停、积分增减与实时流水。
|
||
- 配合磨砂半透明背景遮罩（Backdrop），点击空白处或「✕ 关闭」按钮即可无缝收起，列表浏览上下文不丢失。
|
||
|
||
---
|
||
|
||
## 4. 兼容性与上线记录
|
||
- **DOM 契约兼容**：保留所有核心配置 ID（`amApi`、`downloadDir`、`localFilePolicy`、`defaultQuality`、`davUrl` 等）以及事件回调机制。
|
||
- **上线状态**：最新代码已提交 Git（分支 `master`），并同步热更新至运行中的 `am-downloader` 容器内 `/app/index.html`。
|
||
|
||
---
|
||
|
||
## 5. 交互与细节修复记录（2026-09-17）
|
||
|
||
### 5.1 移动端底部导航栏贴底优化
|
||
- **改动说明**：解决移动端底栏浮岛胶囊式设计（悬空 `12px` 且带圆角）在滚动时产生的文字从缝隙穿插、视觉割裂问题。
|
||
- **调整实现**：
|
||
- 改为全宽贴底原生 TabBar 布局（`left: 0; right: 0; bottom: 0; border-radius: 0;`）。
|
||
- 顶部微弱边框隔离（`border-top: 1px solid var(--border-subtle)`），四周无多余外边框。
|
||
- 适配安全区域与深色毛玻璃（`padding: 6px 8px calc(6px + env(safe-area-inset-bottom, 0px)); background: rgba(8, 12, 20, 0.95); backdrop-filter: blur(20px);`）。
|
||
|
||
### 5.2 全局接口与弹窗提示中文语义化
|
||
- **改动说明**：解决兑换失败、加入队列失败时直接将后端原始错误 JSON（如 `["error""code already used or unavailable"]`）弹给用户的粗糙体验。
|
||
- **调整实现**：
|
||
- 在底层封装统一错误解析器 `parseErrorMsg(msg)`，自动解包后端返回的 JSON 结构。
|
||
- 建立错误语义字典映射：
|
||
- `code already used or unavailable` → **该兑换码已被使用或已失效**
|
||
- `record not found` → **兑换码不存在，请核对后重试**
|
||
- `insufficient credits` → **积分不足，请先兑换或充值积分**
|
||
- `code expired` → **该兑换码已过期**
|
||
- `user disabled` → **账户已被禁用，无法执行此操作**
|
||
- `only failed tasks can be retried` → **只有失败的任务才支持重试**
|
||
- 其他校验项（用户名/密码规则、金额非零等）同步完成中文友好化。
|
||
|
||
### 5.3 用户管理抽屉积分调整事件委托审核
|
||
- **问题根因**：原代码在为 `detailAdd` 与 `detailSub` 绑定 `onclick` 后，通过 `innerHTML += ...` 追加积分流水，导致整个容器内 DOM 被全量重构，先前绑定的监听器失效。
|
||
- **修复方案与审核**：通过 `document.createElement('div')` + `appendChild(ledger)` 实现流水平行追加，既保留了已渲染节点的事件监听，又保证了 DOM 结构与 ID 契约完整无副作用。
|
||
|