verdaccio-cache-manager/doc/design-spec.md

Verdaccio 缓存可视化管理面板 — 设计规范（编码阶段参考）

文档依据：

1. doc/需求文档.md（完整版：第一部分 功能需求 + 第二部分 前端界面设计）
2. doc/bright/（浅色设计稿：design-mockup-v2.html + 7 张效果图）
3. doc/dark/（暗色设计稿：design-mockup-v2-dark.html + 7 张效果图）
4. 手机版竖屏效果基准：bright/design-v2-mobile.png、dark/design-v2-dark-mobile.png

编码方式：一套代码 + CSS 变量双主题（bright=浅色默认 / dark=暗色），三端适配（电脑 ≥1024px / 平板 768~1023px / 手机 <768px），手机端效果以 dark/、bright/ 目录的 mobile 效果图为基准。

---

1. 设计 Token（bright / dark 双主题）

1.1 多巴胺色板

Token	bright（浅色）	dark（暗色）	用途
--green	#32CD32	#3DDB4D	正常状态标签、选中态标签
--green-soft	#E9F9E9	rgba(61,219,77,.14)	绿色标签底色
--orange	#FF8C00	#FFA033	清理按钮、Logo、搜索按钮
--orange-soft	#FFF3E2	rgba(255,160,51,.14)	橙色标签/数字底色
--red	#FF4500	#FF5630	预警标签、删除按钮、预警数量
--red-soft	#FFE9E2	rgba(255,86,48,.15)	红色标签/危险按钮底色
--blue	#1E90FF	#45A2FF	忽略类标签、信息类
--blue-soft	#E6F2FF	rgba(69,162,255,.15)	蓝色标签底色

1.2 中性色 / 背景

Token	bright	dark	用途
--ink	#2B2B33	#F1E8DE	主文字
--ink-dim	#8A8A94	#A79E91	次级文字
--ink-faint	#B9B9C2	#6E655A	弱化文字/提示
--line	#F1E7DA	#3A2F25	边框、分隔线
--card	#FFFFFF	#221B14	卡片/面板底色
--card-2	#FFFFFF	#2A211A	次级面板（抽屉内用户卡等）
--bg	#FFF8EF	#16110C	页面底色（暖白 / 暖黑）
--bg-deep	#FFFDF9	#100C08	深一档背景（画板容器）

1.3 字体

Token	值	用途
--num	'Fredoka','PingFang SC',sans-serif	数字/统计值/徽章/表格数字
--sans	'PingFang SC','Hiragino Sans GB','Microsoft YaHei',sans-serif	正文
--display	'ZCOOL QingKe HuangYou','PingFang SC',sans-serif	展示性标题

字号梯度：30（页面大标题）/ 16.5（品牌名）/ 14–15（卡片标题）/ 13.5（导航）/ 12–12.5（次要）/ 11–11.5（弱化）。

1.4 圆角 / 阴影 / 渐变

Token	值	用途
--r-lg	22px	大卡片
--r-md	16px	中小卡片/输入框
pill	99px	按钮、标签、搜索框、导航项
--shadow	bright：0 10px 30px -12px rgba(180,120,60,.18), 0 2px 8px -2px rgba(180,120,60,.08) / dark：0 12px 32px -14px rgba(0,0,0,.6), 0 2px 8px -2px rgba(0,0,0,.4)	卡片常态
--shadow-hover	bright：0 18px 44px -14px rgba(180,120,60,.30), 0 4px 14px -4px rgba(180,120,60,.12) / dark：0 20px 46px -16px rgba(0,0,0,.75), 0 4px 14px -4px rgba(0,0,0,.5)	hover 上浮

渐变常量（两版一致）：主按钮 linear-gradient(120deg,#FFB347,#FF8C00)；预警按钮 bright #FF5E1A→#FF8C00、dark #FF5630→#FF8C00；头像 #7CC6FF→#1E90FF（dark #5FA8E8→#2B74B9）。

---

2. 双主题实现方案

:root { /* bright 浅色 token（默认） */ }
html[data-theme="dark"] { /* 覆盖 dark token + 氛围背景 */ }

• 切换入口：顶栏右侧 pill 按钮（bright 显示「🌙 切到暗色」，dark 显示「☀️ 切到亮色」）；移动端并入设置抽屉「🌙 主题切换」项
• 记忆：localStorage 键 vcm-theme，加载时读取
• 注意：dark 下需同步覆盖 .ambient 氛围渐变、点阵背景、搜索框聚焦光圈、呼吸光晕强度等硬编码色（对照 bright/dark 两版 HTML）

---

3. 功能需求要点（编码约束，来自第一部分）

3.1 包列表与状态

• 字段：包名 / 版本数 / 占用空间 / 状态（正常·预警·已忽略）/ 操作（清理、忽略、取消忽略）
• 状态规则：正常 = 版本数 ≤ 阈值；预警 = 版本数 > 阈值 且未被忽略；已忽略 = 用户手动标记
• 排序：预警置顶 → 正常居中 → 已忽略垫底；同状态按版本数降序

3.2 检索

• 输入框实时过滤（防抖 300ms），一键清空；匹配：不区分大小写子串，仅匹配包名（界面文档扩展为包名/版本号/文件大小，编码以扩展版为准）
• 反馈：实时更新 + 「共找到 X 个包」；清空恢复完整列表

3.3 阈值配置

• 版本数阈值：取值范围 1~100，默认 15（功能需求为准；界面设计稿示例为 50，编码以 15 为默认并可在 UI 调整）
• 持久化：保存到 SQLite settings 表，重启不丢失，加载时读取；修改后列表状态立即重算
• 界面扩展配置项（设计稿已实现）：单包大小阈值（默认 500MB）、单包例外（覆盖全局）、恢复默认、保存生效提示

3.4 预警清理

• 超阈值包：预警标签、自动置顶、清理按钮可用
• 清理确认弹窗：包名、当前版本数、保留版本数输入（默认=阈值）、将删除版本列表（Tag）、将删除数量、取消、确认清理（loading）
• 清理原子逻辑：读 package.json → 按 semver 排序保留最新 N 个 → 删低版本 versions/time 记录 → 修正 dist-tags（如 latest 指向已删版本）→ 写回元数据 → 物理删 .tgz → 记日志 → 返回「删除数量、释放空间」
• 反馈：成功「已清理 X 个版本，释放 Y MB」；失败展示错误、不修改任何文件

3.5 忽略标记

• 标记/取消忽略立即持久化到 ignored_packages 表；取消后若仍超阈值自动回预警

3.6 操作日志

• 每次清理自动记录：包名、删除版本列表、删除数量、释放空间、操作时间（UTC）
• 按时间倒序展示最近 50 条，支持查看详情

3.7 非功能要求

• 性能：500 包加载 <2s、检索 <200ms、单包清理 <5s
• 可靠：清理原子性、元数据损坏标记「异常」不影响其他包、崩溃无脏数据
• 安全：非 root（UID 10000）、storage 只读挂载、仅改目标包文件

---

4. 数据模型与 API（编码依据）

4.1 SQLite

CREATE TABLE settings (key TEXT PRIMARY KEY, value TEXT);          -- version_threshold 默认 '15'
CREATE TABLE ignored_packages (pkg_name TEXT PRIMARY KEY, ignored_at DATETIME DEFAULT CURRENT_TIMESTAMP);
CREATE TABLE logs (id INTEGER PRIMARY KEY AUTOINCREMENT, pkg_name TEXT,
  deleted_versions TEXT, deleted_count INTEGER, freed_space TEXT, created_at DATETIME DEFAULT CURRENT_TIMESTAMP);

4.2 REST API

方法	路径	说明
GET/POST	/api/threshold	获取/设置阈值
GET	/api/ignored	获取已忽略包名
POST	/api/ignore	标记忽略
DELETE	/api/ignore/:pkgName	取消忽略
GET	/api/packages?keyword=	扫描包列表（模糊检索）
POST	/api/clean	执行清理
GET	/api/logs	最近 50 条日志

---

5. 页面清单（画板 → 页面）

#	页面/视图	关键内容	路由建议
1	缓存概览	4 核心统计卡 + 5 辅助指标、预警横幅卡、Top 30 访问排行、包卡片列表	/
2	全局检索	48px 大圆角搜索框、快捷筛选 pill、无边框结果表格	/search
3	阈值配置	全局阈值卡×2（版本数/大小，−/+ 步进器、恢复默认、保存）、单包例外表格、行内添加例外表单	/thresholds
4	包详情抽屉	600px 右侧滑出，包信息 + 版本列表（单版本删除、清理全部、忽略）	覆盖层
5	忽略列表	已忽略包表格 + 移出忽略（二次确认）	/ignored
6	最近动态	时间倒序操作日志表格，删除数量/释放空间 chip	/logs
7	移动端竖版	底部 4 Tab（概览/检索/阈值/动态）、2×2 统计、单列包卡、设置抽屉；效果图：bright/design-v2-mobile.png、dark/design-v2-dark-mobile.png	响应式实现
8	登录页	渐变背景 + 居中卡片 420px、emoji 输入框、渐变登录按钮、记住我/忘记密码；效果图 FRAME 08：bright/design-v2-login.png、dark/design-v2-dark-login.png（按需求文档 14 节）	/login

---

6. 组件清单（来自设计稿）

组件	要点
顶栏 Topbar	64px；Logo 渐变块 + 品牌名 + 副标题；中部 pill 导航（active 橙色渐变）；右侧主题切换按钮 + 圆形头像
统计卡 Stat1	4 个：图标 + Fredoka 数字 + 标签；四色 tone；预警数量卡红色呼吸光晕
辅助指标 Stat2	5 个轻量小卡（访问排行/今日下载/最大包/最老包/版本数分布）
预警卡 Alert	红色渐变边框 + 呼吸光晕 + 立即清理按钮
清理卡 Clean	橙色渐变 + 可清理空间 + 立即清理按钮
Top30 排行	表格：金银铜徽章、包名（scoped 省略+tooltip）、访问次数、热度进度条
包卡片	图标、包名、版本数/占用/最近更新、状态标签、清理/忽略按钮；warn 卡呼吸光晕
搜索框	48px 高、大圆角、放大镜 + 快捷键提示；focus 橙色光圈
Pill 筛选	状态过滤 + 排序切换，选中态绿色
结果表格	无边框、hover 行高亮、状态标签、删除操作
阈值卡	全局阈值 + −/+ 步进器 + 恢复默认 + 保存按钮 + 生效提示条
例外表格	包名/版本数阈值/大小阈值/命中状态/删除；行内添加例外表单
抽屉 Drawer	600px 右滑 + 遮罩；包详情版本列表、单版本删除、清理全部/忽略
忽略表	已忽略包 + 取消忽略
日志表	时间倒序；操作类型 + 版本数/释放空间 chip
移动端系列	M-Topbar（☰）、M-Stats 2×2、M-Banner 预警横幅、M-Card 单列、M-Tabbar 底部 4 Tab、M-Drawer 设置抽屉（主题/阈值入口/版本信息/退出登录）
登录页	渐变背景、居中白卡 420px、emoji 输入框、渐变登录按钮、记住我/忘记密码

---

7. 响应式断点（三端，以需求文档为准）

断点	尺寸	导航	统计卡	包列表	忽略列表	搜索框	包详情抽屉
桌面端	≥1024px	顶部 pill 按钮	4 列	4 列卡片网格	3 列网格	居中 600px	右侧 600px
平板端	768~1023px	紧凑 pill	2×2	2 列	2 列	100%（max 500px）	右侧 50%
手机端	<768px	汉堡/☰ + 抽屉	单列	单列	单列	全宽	底部弹窗 85vh

差异标注：需求文档手机端导航为「汉堡菜单 + 左侧 280px 侧边抽屉」；设计稿 FRAME 07 为「右上角 ☰ + 右侧设置抽屉（主题/阈值/版本/退出）+ 底部 4 Tab 核心导航」。编码以设计稿为准（设置类进抽屉、页面切换走底部 Tab），汉堡抽屉用于承载非核心设置项。

---

8. 动效规范

场景	动效
页面切换	平滑淡入 + 轻微上滑（300ms）
卡片悬停	上浮 2px + 阴影增强 + 边框强调
按钮点击	缩放 0.95 + 回弹
弹窗/抽屉	右侧滑入（0.35s cubic-bezier(.2,.8,.25,1)）+ 遮罩淡入；移动端底部滑入
预警呼吸	红色光晕呼吸动效（2.4~2.6s ease-in-out 循环）
清理成功	卡片缩小消失 + 成功 toast

---

9. 文案风格（C 端对照）

后台风	C 端
缓存管理	你的缓存
操作日志	最近动态
忽略列表	已忽略的包
阈值配置	预警设置
执行清理	一键清理
共 156 条记录	156 条动态

---

10. 技术选型与编码建议

• 后端：Node.js 18-slim + Express + better-sqlite3（单文件嵌入），Docker 单容器，storage 只读挂载、manager-data 读写挂载，非 root（UID 10000），端口 3000
• 前端：Vue 3 + Vite（pnpm 管理）+ Element Plus 按需引入；组件样式按 §1/§2 双主题 token 二次重写为设计稿风格（覆盖 el-card/el-table/el-table-v2/el-drawer/el-tag/el-input-number/el-pagination 等的圆角、阴影、边框、hover 态与预警呼吸光晕）
• 目录建议：src/components/（§6 组件逐一落地）、src/views/（§5 页面）、src/styles/tokens.css（双主题 token）
• 图标：emoji（与设计稿一致，无外部图标库）
• 数据：mock 先行跑通 UI，接口按 §4.2 对接
• 验收对照：需求文档 AC-1~8（包列表/检索/阈值/预警/清理/忽略/日志/原子性）

---

11. 已确认决策（编码按此执行）

1. 阈值默认值：15（功能需求 1~100 为准，UI 可调）
2. 登录页：补效果图（FRAME 08 已输出 bright/dark 两版，见 §5 #8）
3. UI 库：Element Plus 按需引入，组件样式按 §1/§2 token 重写覆盖为设计稿风格

---

12. Verdaccio 缓存目录配置与部署（编码依据）

12.1 目录配置机制

• Verdaccio 侧：缓存目录由 config.yaml 的 storage 字段指定（Docker 镜像内默认 /verdaccio/storage）
• 面板侧：环境变量 VERDACCIO_STORAGE 优先 → 其次 UI「设置」中配置并持久化到 SQLite settings 表（key = storage_dir）→ 均无时进入首次启动引导页要求配置
• 校验：保存/启动时校验目录存在、可读、含 package.json / .tgz；无效时提示重新配置，面板不启动扫描
• 扫描逻辑：递归 **/package.json 解析 versions/time，匹配 .tgz 计算占用；支持 scoped 包（@scope/name 嵌套目录）

12.2 部署方式一：Docker（与 Verdaccio 同主机）

services:
  verdaccio:
    image: verdaccio/verdaccio
    volumes: ["./storage:/verdaccio/storage"]        # Verdaccio 读写
  verdaccio-manager:
    build: ./                                        # node:18-slim 约 180MB
    environment: [VERDACCIO_STORAGE=/verdaccio/storage, PORT=3000]
    volumes:
      - "./storage:/verdaccio/storage:ro"            # 只读挂载 Verdaccio 存储
      - "./manager-data:/app/data"                   # 读写：SQLite 数据
    ports: ["3000:3000"]

12.3 部署方式二：虚拟机 / 裸机

• 环境：Node.js 18 + pnpm，构建前端后 node server.js，pm2/systemd 守护
• 配置（环境变量或 .env）：

  VERDACCIO_STORAGE=/var/lib/verdaccio/storage
  PORT=3000
  DATA_DIR=/var/lib/verdaccio-manager/data
  

• Verdaccio 侧 config.yaml：storage: /var/lib/verdaccio/storage（与面板指向同一目录）

12.4 UI 配置入口

• 首次启动：无 storage_dir 时展示引导页，提供缓存目录输入 + 「自动探测」（读环境变量/常见路径）按钮
• 后续修改：顶栏头像下拉「设置」/ 移动端设置抽屉中修改，保存后重新扫描并刷新概览