rogee/sub-store

Fork 0

Files

T

rogee 90e53aa754 chore: sub-store Go 重写项目初始化

2026-07-27 14:38:13 +08:00

25 KiB

Raw Permalink Blame History

Sub-Store 前端功能规划文档

基于原项目 ref/sub-store-cloudflare/frontend 的交互分析，规划 Go 重构版前端。核心原则：上下布局，PC 优先，弃用移动端 swipe/popup/floating-button 交互模式。

1. 原前端交互痛点分析

1.1 移动端优先的架构问题

痛点	原项目实现	PC 上的问题
Swipe 手势操作	`SubListItem` 用 `nut-swipe` 左/右滑动暴露复制/下载/删除按钮	桌面端无触屏，swipe 不触发，操作隐藏在不可见区域
底部 TabBar	`TabBar.vue` 3 个 tab 固定底部，768px+ 才切换为侧边栏	PC 上侧边栏是浮动定位 (`position: fixed`)，非真正双栏布局
底部 Popup 弹窗	添加订阅、模板编辑、目标选择均用 `nut-popup position="bottom"`	占满下半屏，PC 上极不协调，无法利用横向空间
浮动按钮	`nut-drag` 可拖拽的刷新/添加按钮，固定在屏幕边缘	PC 上浮动按钮遮挡内容，拖拽行为多余
单列滚动列表	源和集合在同一个页面上下排列，tag 筛选条横排	PC 宽屏下大量留白，列表项信息密度低
编辑器 Tab 横滚	SubEditor 的 display/content/actions 三个 tab 横向排列	PC 上应该用左右分栏或垂直 Tab
SubEditor 巨型组件	单文件 2174 行，混合 source/collection 两种编辑逻辑	维护困难，状态管理混乱
全屏预览覆盖	Preview.vue 用 `position: fixed; inset: 0` 全屏覆盖	PC 上应该是侧面板或分栏，不离开当前上下文
无键盘快捷键	所有操作只能点击	PC 用户期望 Ctrl+S 保存、Esc 关闭等
无右键菜单	操作按钮散落在列表项内部	PC 用户期望右键弹出操作菜单
Tools 页面粗糙	转换器/分享/回收站堆在一个页面，原生 HTML 控件	功能孤立，与主流程割裂

1.2 信息架构问题

源 (Source) 和集合 (Collection) 混在同一列表，靠标题区分，概念不清
模板管理藏在 "My" 设置页，与集合编辑中的模板选择脱节
分享 (Share) 和回收站 (Recycle Bin) 被丢进 Tools 工具页，而非关联到对应资源
预览/对比需要跳路由或弹全屏，丢失列表上下文
下载链接生成操作分散：列表项有复制链接，编辑页有链接生成，Tools 有分享创建

2. 整体布局设计：上下布局

┌──────────────────────────────────────────────────────────────────┐
│  TopBar  (h: 48px)                                                │
│  [Logo] Sub-Store    [搜索框]        [刷新] [主题] [语言] [设置]   │
├──────────────────────────────────────────────────────────────────┤
│  NavBar  (h: 40px)                                                 │
│  [订阅源] [集合] [模板] [工具] [回收站]              [+ 新建 ▾]    │
├──────────────────────────────────────────────────────────────────┤
│                                                                    │
│  Main Content Area  (flex: 1, overflow: auto)                      │
│                                                                    │
│  ┌──────────────────────┐  ┌──────────────────────────────────┐   │
│  │  Left Panel          │  │  Right Panel / Detail             │   │
│  │  (列表区, 固定宽度)   │  │  (编辑/预览/详情, flex: 1)        │   │
│  │  w: 360px            │  │                                  │   │
│  │                      │  │                                  │   │
│  │  [搜索] [筛选 tag]    │  │                                  │   │
│  │  ┌─────────────────┐ │  │                                  │   │
│  │  │ Source/Col Card │ │  │                                  │   │
│  │  ├─────────────────┤ │  │                                  │   │
│  │  │ Source/Col Card │ │  │                                  │   │
│  │  ├─────────────────┤ │  │                                  │   │
│  │  │ ...             │ │  │                                  │   │
│  │  └─────────────────┘ │  │                                  │   │
│  └──────────────────────┘  └──────────────────────────────────┘   │
│                                                                    │
├──────────────────────────────────────────────────────────────────┤
│  StatusBar  (h: 28px, 可选)                                        │
│  ● 已连接 · 12 源 · 3 集合 · v1.0.0          [最后同步: 2分钟前]   │
└──────────────────────────────────────────────────────────────────┘

2.1 布局规则

TopBar: 始终固定顶部，包含全局搜索、全局操作（刷新/主题/语言/设置）
NavBar: 水平标签栏，切换主功能区域，当前页高亮
Main Content: 根据当前 Tab 显示不同内容，内部可左右分栏
StatusBar: 底部状态栏，显示连接状态/数据统计/同步时间（可选关闭）
最小宽度: 1024px（PC 优先），窄屏降级为单列+抽屉

2.2 响应式策略

宽度	布局	说明
≥1280px	双栏 (列表+详情)	详情区常驻右侧
1024-1279px	双栏 (列表+详情)	列表区缩窄至 320px
768-1023px	单栏 + 右抽屉	详情从右侧滑入抽屉
<768px	单栏 + 全屏推入	详情全屏推入（移动端兼容）

3. 功能模块规划

3.1 订阅源管理 (Sources)

3.1.1 源列表 (Left Panel)

功能点:

卡片式列表，每张卡片显示：名称、类型徽章 (remote/local)、启用开关、流量摘要、标签
顶部工具栏：搜索框（实时过滤名称/URL）、标签筛选条、排序按钮
列表项右键菜单：编辑、复制链接、预览、克隆、删除、创建分享
拖拽排序（HTML5 drag API，非 vuedraggable touch 模式）
选中状态：单击选中（高亮），双击打开编辑
多选：Ctrl+Click 多选，批量启用/禁用/删除/导出
列表底部：显示总数和已加载数

卡片信息层次:

┌──────────────────────────────────────┐
│ [●] 机场A                  [remote] │
│     https://example.com/sub...  [⚡] │
│     ↑ 12.3GB  ↓ 89.7GB / 100GB      │
│     [HK] [JP]                    [⋮] │
└──────────────────────────────────────┘

3.1.2 源编辑 (Right Panel / Drawer)

布局: 垂直分区，非 Tab 切换

区域 1 - 基本信息:

ID（创建后只读）、显示名、备注、标签（逗号分隔或 chip 输入）
图标 URL、图标彩色开关

区域 2 - 数据源:

类型切换：Remote / Local（radio button 横排）
Remote: URL 文本域（支持多行多 URL）、UA 输入、passThrough UA 开关、subUserinfo 输入
Local: 全屏代码编辑器按钮 + 文件导入按钮 + 内容验证按钮 + CodeMirror 编辑器（内嵌）

区域 3 - 节点处理 (Filter Pipeline):

可视化流水线编辑器，每个 filter 是一个可折叠卡片
拖拽排序 filter 执行顺序
每个 filter 类型有专属配置表单：
- Region Filter: 复选框组 (HK/JP/SG/US/UK/DE/KR/TW)，keep/exclude 开关
- Type Filter: 复选框组 (ss/vmess/vless/trojan/...)，keep/exclude 开关
- Regex Filter: 正则输入框（支持多个），keep/exclude 开关，字段选择
- Regex Rename: 表格式输入 (表达式 → 替换为)
- Regex Delete: 正则输入框（支持多个），字段选择
- Regex Sort: 优先级正则列表 + 方向选择
- Handle Duplicate: 去重字段选择、动作 (delete/rename)、后缀模板、连接符、位置
- Sort: 方向选择 (asc/desc/random)
- Flag Operator: 模式 (add/remove)、台湾旗配置
- Quick Setting: UDP/TFO/scert/useless/vmess-aead 下拉选择
- Resolve Domain: DNS provider 选择、记录类型、过滤模式、自定义 URL、EDNS、并发数
- Script: 脚本选择下拉（从注册表加载）、参数表单（根据 metadata.parameters 动态生成）
新增 filter 按钮 → 下拉菜单选择类型
每个 filter 可启用/禁用（开关）、删除（按钮）

区域 4 - 操作栏 (底部固定):

[预览] [对比] [保存] [另存为]
Ctrl+S 快捷键保存

3.1.3 源预览

功能: 调用 /api/preview/source 显示原始节点 vs 处理后节点

布局: 右侧面板内的分栏视图

左栏：原始节点列表（可搜索、可排序）
右栏：处理后节点列表
顶部：节点数量统计 (原始 N → 处理后 M, 跳过 K)
每个节点显示：名称、类型、服务器:端口、协议详情
支持展开节点查看完整字段

3.1.4 源下载链接

功能: 生成各目标的下载链接

交互: 点击列表项的"复制链接"按钮 → 弹出链接面板（右侧抽屉或 popover）

目标选择：13 种目标客户端（下拉或 grid 按钮）
链接显示：只读文本框 + 复制按钮
二维码生成（可选）
临时覆盖选项：URL/content/UA 输入框（展开式高级选项）

3.2 集合管理 (Collections)

3.2.1 集合列表 (Left Panel)

与源列表同结构，但卡片额外显示：

包含的源数量/名称摘要
关联的模板名
ignoreFailed 状态徽章

3.2.2 集合编辑 (Right Panel / Drawer)

区域 1 - 基本信息: 同源编辑

区域 2 - 集合配置:

模板选择：下拉选择（内置 6 套 + 自定义），旁边"管理模板"链接
源选择器：双栏穿梭框 (Transfer) 布局
- 左栏：所有可用源（可搜索、可按 tag 筛选）
- 右栏：已选源（可拖拽排序）
- 全选/反选/清空按钮
- 空选择 = 包含所有 enabled 源（需明确提示）
ignoreFailed 切换：下拉选择 (跳过失败源 / 全部要求成功)

区域 3 - 节点处理: 同源编辑的 Filter Pipeline（集合级 filter）

区域 4 - 操作栏: 同源编辑

3.2.3 集合预览

功能: 调用 /api/preview/collection，显示合并后的节点

布局: 同源预览，但显示多源合并信息

额外显示：各源的节点数量、失败源列表
可按来源分组显示

3.3 模板管理 (Templates)

独立 Tab 页，非隐藏在设置中。

3.3.1 模板列表

表格布局：名称、目标客户端、类型 (内置/自定义)、操作
内置模板：只读，可查看不可编辑/删除
自定义模板：编辑、删除、克隆
新建按钮、从文件导入按钮 (JSON/YAML)

3.3.2 模板编辑

布局: 右侧面板或模态对话框

区域 1 - 元信息:

ID（创建后只读）、名称、目标客户端选择

区域 2 - 配置编辑器:

CodeMirror JSON/YAML 编辑器（全宽）
语法高亮、格式化按钮、校验按钮
可视化预览（可选）：解析 proxy-groups 和 rules，以树形图展示

区域 3 - 内置模板预览:

点击内置模板 → 只读模式显示配置 + 结构说明

3.4 工具 (Tools)

独立 Tab 页，包含三大工具，内部用子 Tab 或卡片分区。

3.4.1 格式转换器

功能: 一次性代理/规则转换 (/api/proxy/parse, /api/rule/parse)

布局: 左右分栏

左栏：输入
- 类型切换：代理转换 / 规则转换
- 目标选择：下拉
- 输入文本域（支持粘贴 URI/YAML/JSON）
- 从文件导入按钮
- [转换] 按钮
右栏：输出
- 输出文本域（只读）
- 统计信息：解析 N / 输出 M / 跳过 K
- 复制按钮、下载按钮

3.4.2 分享管理 (Shares)

功能: 创建/管理 download grants

布局: 列表 + 表单

列表区:

表格：资源类型、资源 ID、目标、过期时间、状态、操作
操作：启用/禁用切换、删除、复制链接
按资源类型筛选

创建表单 (右侧面板或顶部展开):

资源类型：source / collection
资源 ID：下拉选择（从现有数据加载）
目标：下拉（auto 或指定）
过期时间：数字 + 单位（小时/天），或永不过期
[创建] → 生成 token + URL，显示并可复制

3.4.3 节点信息查询

功能: 调用 /api/utils/node-info 查询 IP 信息

布局: 简单表单 + 结果卡片

输入：服务器地址
结果：IP、国家、地区、城市、连接信息

3.5 回收站 (Recycle Bin)

独立 Tab 页。

布局: 表格 + 详情抽屉

列表:

表格：资源类型、资源 ID、删除时间、操作
操作：恢复、彻底删除
按资源类型筛选
显示总数 / 上限 50 提示

恢复逻辑:

恢复时检查 ID 冲突（后端已处理，前端需展示友好错误）
恢复成功后刷新对应列表

3.6 设置 (Settings)

模态对话框或独立全屏页，非当前 My.vue 的卡片堆叠。

布局: 左侧分类菜单 + 右侧设置表单

分类:

3.6.1 请求设置

默认 User-Agent
默认流量 User-Agent
默认超时 (ms)
后端请求并发数
并发等待时间 (ms)
远程缓存 TTL (s)
缓存错误降级开关
节点信息 API URL

3.6.2 外观设置

主题选择（8 套主题）
简单模式开关
图标显示开关
图标彩色开关
列表视图模式（单列/双列）
浮动按钮开关（移动端兼容用）
编辑器分组模式

3.6.3 数据管理

导出备份（下载 JSON）
导入备份（上传 JSON）
Admin Token 设置
下载 Token 显示

3.6.4 关于

后端类型、版本、存储引擎
GitHub 链接
文档链接

4. 全局交互设计

4.1 键盘快捷键

快捷键	功能
`Ctrl+K`	聚焦全局搜索
`Ctrl+N`	新建（当前 Tab 对应类型）
`Ctrl+S`	保存当前编辑
`Ctrl+Shift+S`	另存为
`Ctrl+P`	预览当前选中项
`Ctrl+D`	复制下载链接
`Delete`	删除选中项（需确认）
`Esc`	关闭面板/对话框/取消选中
`↑↓`	列表中上下移动选中
`Enter`	打开选中项编辑
`Space`	切换选中项启用/禁用

4.2 右键菜单

列表项右键:

编辑
预览节点
复制下载链接 ▸ (子菜单：mihomo / sing-box / surge / ...)
创建分享
克隆
导出
删除

空白区域右键:

新建源
新建集合
粘贴导入
刷新列表

4.3 拖放操作

列表内拖拽: 排序（显示插入位置指示线）
跨列表拖拽: 源拖入集合（自动添加到集合的 sourceIds）
文件拖入: 拖入 JSON/YAML 文件 → 导入备份或模板

4.4 通知系统

Toast: 操作成功/失败（右上角，自动消失）
通知中心: 右上角铃铛图标，记录历史通知
内联状态: 列表项上的流量加载状态、同步状态

4.5 确认对话框

删除操作：模态确认框，显示资源名称
导入覆盖：模态确认框，显示将影响的数据统计
离开未保存编辑：路由守卫拦截，提示保存

5. 数据流与状态管理

5.1 Store 结构（Pinia）

stores/
├── global.ts          # 全局状态：环境信息、连接状态、主题
├── sources.ts         # 源列表、CRUD、排序
├── collections.ts     # 集合列表、CRUD、排序
├── templates.ts       # 模板列表、CRUD
├── shares.ts          # 分享列表、CRUD
├── recycleBin.ts      # 回收站列表、恢复/删除
├── settings.ts        # 应用设置
├── scripts.ts         # 脚本注册表元数据
└── notify.ts          # 通知队列

5.2 API 层

保持原项目的 axios 拦截器模式，但简化适配层：

// api/client.ts — axios 实例 + 拦截器
// api/sources.ts — 源 CRUD
// api/collections.ts — 集合 CRUD
// api/templates.ts — 模板 CRUD
// api/shares.ts — 分享 CRUD
// api/recycle.ts — 回收站
// api/settings.ts — 设置 + 导出/导入
// api/tools.ts — 转换器、节点信息
// api/env.ts — 环境

关键简化: 原项目的 api/app/index.ts (705 行) 包含大量 UI ↔ API 的 filter 格式转换逻辑 (toApiFilters / fromApiFilters / toActionMeta)。重构版应将此逻辑移入编辑器组件的 model 层，API 层只做纯 HTTP 调用。

5.3 Filter Pipeline 数据模型

// 编辑器内部的 UI 模型（与原项目 UiProcess 一致）
type FilterAction = {
  id: string;           // 前端 UUID
  type: ActionType;     // 'Region Filter' | 'Type Filter' | ...
  args: Record<string, any>;
  customName?: string;
  disabled: boolean;
};

// 提交到后端时转换为 FilterRule[]
// 从后端加载时转换为 FilterAction[]
// 转换逻辑封装在 composables/useFilterTransform.ts

6. 技术选型建议

6.1 框架与 UI 库

组件	原项目	重构建议	理由
框架	Vue 3	Vue 3	保持一致
UI 库	NutUI (移动端)	Naive UI / PrimeVue	PC 优先，需数据表格/穿梭框/树形组件
状态管理	Pinia	Pinia	保持一致
路由	Vue Router	Vue Router	保持一致
HTTP	Axios	Axios 或 ofetch	保持 Axios 即可
代码编辑器	CodeMirror 5	CodeMirror 6 / Monaco	CM6 更现代，Monaco 更强大
拖拽	vuedraggable (SortableJS)	原生 HTML5 Drag API + vue-draggable-plus	PC 用原生拖拽更可靠
i18n	vue-i18n	vue-i18n	保持一致
图标	Font Awesome + NutUI Icon	Lucide / Tabler Icons	更现代的图标集
样式	SCSS + CSS 变量	UnoCSS / Tailwind CSS	原子化 CSS，开发更快
主题	8 套主题 (SCSS 变量)	CSS 变量 + 暗色模式	简化主题系统

6.2 组件库选择考量

Naive UI (推荐):

Vue 3 原生，TypeScript 友好
内置数据表格、穿梭框、树形、抽屉、右键菜单
暗色模式原生支持
中文社区活跃

PrimeVue:

组件最全（含 CodeMirror 集成）
主题系统强大
但体积较大

7. 页面路由规划

/                   → 重定向到 /sources
/sources            → 订阅源管理（列表 + 右侧详情/编辑）
/sources/:id        → 订阅源管理（选中指定源，右侧显示编辑）
/collections        → 集合管理
/collections/:id    → 集合管理（选中指定集合）
/templates          → 模板管理
/templates/:id      → 模板管理（选中指定模板）
/tools              → 工具（默认显示转换器）
/tools/converter    → 格式转换器
/tools/shares       → 分享管理
/tools/node-info    → 节点信息查询
/recycle-bin        → 回收站
/settings           → 设置（模态对话框，非独立路由）
/preview/:type/:id  → 预览（可选独立路由，用于书签/分享）

路由模式:

列表+详情使用嵌套路由，详情区为子路由 <router-view>
预览使用 query 参数 ?preview=true 或子路由，避免全屏覆盖

8. 功能优先级

P0 — MVP 必须实现

上下布局框架（TopBar + NavBar + Main + StatusBar）
订阅源列表 + 编辑（基本表单 + URL/Content + Filter Pipeline）
集合列表 + 编辑（源选择器 + 模板选择 + Filter Pipeline）
源/集合预览（原始 vs 处理后节点对比）
下载链接生成 + 复制
模板列表 + 查看（内置只读）
设置（请求设置 + Admin Token）
导出/导入备份
键盘快捷键（Ctrl+S, Ctrl+K, Esc）
暗色模式

P1 — 增强体验

模板创建/编辑（CodeMirror 编辑器）
分享管理（创建/列表/启停/删除）
回收站（列表/恢复/彻底删除）
格式转换器工具
节点信息查询工具
右键菜单
拖拽排序 + 跨列表拖拽
多选批量操作
全局搜索（跨类型搜索源/集合/模板）

P2 — 高级功能

脚本参数动态表单
节点信息内联展示（预览中展开节点详情）
拖入文件导入
二维码生成
通知中心
自定义主题
移动端响应式降级

9. 与后端 API 的对接

9.1 API 端点映射

前端功能	后端 API	方法
源列表	`/api/sources`	GET
创建源	`/api/sources`	POST
更新源	`/api/sources/:name`	PATCH
删除源	`/api/sources/:name`	DELETE
排序源	`/api/sources` (PUT) 或 `/api/sort/sources` (POST)	PUT/POST
集合列表	`/api/collections`	GET
创建集合	`/api/collections`	POST
更新集合	`/api/collections/:name`	PATCH
删除集合	`/api/collections/:name`	DELETE
排序集合	`/api/collections` (PUT) 或 `/api/sort/collections` (POST)	PUT/POST
模板列表	`/api/templates`	GET
创建模板	`/api/templates`	POST
更新模板	`/api/templates/:name`	PATCH
删除模板	`/api/templates/:name`	DELETE
预览源	`/api/preview/source`	POST
预览集合	`/api/preview/collection`	POST
下载链接	`/api/link/source/:name`, `/api/link/collection/:name`	GET
流量信息	`/api/source/flow/:name`	GET
转换器	`/api/proxy/parse`, `/api/rule/parse`	POST
分享列表	`/api/shares`	GET
创建分享	`/api/shares`	POST
更新分享	`/api/shares/:id`	PATCH
删除分享	`/api/shares/:id`	DELETE
回收站列表	`/api/recycle-bin`	GET
恢复	`/api/recycle-bin/:id/restore`	POST
彻底删除	`/api/recycle-bin/:id`	DELETE
设置	`/api/settings`	GET/PATCH
导出	`/api/storage`	GET
导入	`/api/storage`	POST
环境	`/api/env`	GET
脚本列表	`/api/scripts`	GET
节点信息	`/api/utils/node-info`	POST

9.2 鉴权

所有 /api/* 请求携带 Authorization: Bearer <token> 头
Token 存储在 localStorage，可通过 URL ?token= 参数初始化
401 响应 → 清除 Token，显示重新输入界面

9.3 响应格式适配

统一响应包络：

{ "status": "success", "data": <T> }
{ "status": "failed", "error": { "code": <number>, "message": <string> } }

前端 axios 拦截器：

成功：解包 response.data.data
失败：提取 response.data.error.message，Toast 通知

10. 原项目功能对照清单

原项目功能	重构状态	说明
源列表 + swipe 操作	✅ 保留，改右键菜单	弃用 swipe
集合列表 + swipe 操作	✅ 保留，改右键菜单	弃用 swipe
源编辑 (SubEditor)	✅ 保留，拆分组件	2174 行 → 拆为 3-4 个子组件
集合编辑	✅ 保留，穿梭框选源	弃用 checkbox+draggable
Filter Pipeline 编辑	✅ 保留，改进交互	可视化流水线 + 专属配置表单
预览/对比	✅ 保留，右侧面板	弃用全屏覆盖
下载链接	✅ 保留，popover	弃用 PreviewPanel 弹窗
模板管理	✅ 提升为独立 Tab	从 My 页移出
设置 (My.vue)	✅ 保留，改模态/独立页	分类菜单 + 表单
备份导出/导入	✅ 保留	移入设置-数据管理
工具页	✅ 保留，增强	转换器+分享+节点信息
回收站	✅ 提升为独立 Tab	从 Tools 移出
分享管理	✅ 提升为 Tools 子页	从 Tools 移出
浮动按钮	❌ 移除	PC 不需要
底部 TabBar	❌ 移除	改为顶部 NavBar
底部 Popup	❌ 移除	改为右侧抽屉/模态
主题系统	✅ 保留，简化	8 套 → 暗色/亮色 + 配色变量
i18n	✅ 保留	中/英双语
标签筛选	✅ 保留	列表顶部 chip 筛选
拖拽排序	✅ 保留，原生 HTML5	弃用 vuedraggable
CodeMirror 编辑	✅ 保留，升级 CM6	本地内容/模板编辑
脚本参数	✅ 保留，动态表单	根据 metadata.parameters 生成
流量信息	✅ 保留	卡片内联显示
节点信息查询	✅ 保留	Tools 子功能

25 KiB Raw Permalink Blame History Unescape Escape