am-downloader/UI_REDESIGN.md

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