# 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 契约完整无副作用。