# preview-center 规范

## 目的

定义预览首页这一项能力：插件元数据如何转换为可浏览的菜单、预览区块、线上菜单补充信息，以及不同分类在预览体验中的呈现方式。

## 职责边界

### 本规范覆盖

- `src/plugins/preview.vue` 作为预览中心主入口
- `basic`、`caseCenter`、`Tvtstore`、`zoneEditor` 的分类规则
- 预览侧的菜单计数、筛选、滚动定位、哈希跳转
- `getOnlinePluginConfig` 驱动的线上菜单补充逻辑
- 基于插件元数据的预览卡片行为
- 仅属于预览模式的 UI 约定，不应反向污染普通项目模式

### 本规范不覆盖

- 插件路由在构建或运行时是如何被发现的
- 插件如何被打包或安装
- `qiankun`、小程序或 `uni-app` 容器如何嵌入页面
- 单个案例页面的具体实现细节

## 主要代码依据

- `src/plugins/preview.vue`
- `src/common/utils.js`
- `src/stores/forPreview.js`
- `src/components/forPreview/cardList.vue`
- `src/components/forPreview/filterComFixed.vue`
- `src/components/forPreview/oneImageQr.vue`

## 要求

### Requirement: 预览分类规则

预览中心 SHALL 按稳定规则对插件进行分类：`basic` 作为基础功能分组专区；未声明 `tvtstore` 的普通插件归入 `caseCenter`；声明了 `tvtstore` 且插件名以 `zone` 开头的插件归入 `zoneEditor`；声明了 `tvtstore` 且插件名不以 `zone` 开头的插件归入 `Tvtstore`。

#### Scenario: basic 分类

- GIVEN 插件键名为 `basic`
- WHEN 预览中心生成左侧菜单和内容区
- THEN 该插件 SHALL 进入基础功能分组区域

#### Scenario: 普通案例分类

- GIVEN 某插件未声明 `tvtstore`
- WHEN 预览中心计算分类
- THEN 该插件 SHALL 归入 `caseCenter`

#### Scenario: 区域场景编辑器分类

- GIVEN 某插件声明了 `tvtstore`
- AND 插件名以 `zone` 开头
- WHEN 预览中心计算分类
- THEN 该插件 SHALL 归入 `zoneEditor`

#### Scenario: 插件市场分类

- GIVEN 某插件声明了 `tvtstore`
- AND 插件名不以 `zone` 开头
- WHEN 预览中心计算分类
- THEN 该插件 SHALL 归入 `Tvtstore`

### Requirement: 预览菜单与计数行为

预览中心 SHALL 将分类结果体现在左侧菜单、内容分区和计数统计中。`basic` 的计数 SHALL 汇总其 `child[].preview` 数量；其他分类插件的计数 SHALL 基于顶层 `preview.length` 计算。

#### Scenario: basic 计数

- GIVEN `basic` 插件存在多个 `child` 分组
- WHEN 预览中心计算基础功能数量
- THEN SHALL 汇总所有 `child[].preview` 的总数

#### Scenario: 非 basic 计数

- GIVEN 一个普通插件含有顶层 `preview`
- WHEN 预览中心计算对应分类数量
- THEN SHALL 使用该插件 `preview.length`

### Requirement: 线上菜单补充与本地优先

预览中心 MAY 从线上接口补充插件菜单信息，但本地代码配置 SHALL 始终是事实源。线上数据只允许补充本地缺失的插件条目或预览项，不得覆盖本地已有同名预览项。

#### Scenario: 本地已有预览项

- GIVEN 本地配置已存在某个 `preview.name`
- WHEN 线上接口返回同名预览项
- THEN 预览中心 SHALL 保留本地项为主
- AND 不得用线上项替换本地项

#### Scenario: 本地缺失预览项

- GIVEN 本地插件已存在，但线上返回了本地没有的预览项
- WHEN 预览中心合并菜单数据
- THEN 系统 SHALL 追加这些缺失项

#### Scenario: 本地缺失整个插件条目

- GIVEN 本地不存在某插件配置
- WHEN 线上接口返回了该插件条目
- THEN 系统 SHALL 允许将该插件作为补充条目加入预览中心

### Requirement: 线上菜单补充范围

当前 `getOnlinePluginConfig` 驱动的线上补充 SHALL 仅作用于普通案例插件集合。`basic` 分组以及声明了 `tvtstore` 的插件市场/区域场景编辑器条目 SHALL 继续完全以本地配置为准，不走这条线上合并路径。

#### Scenario: basic 不参与线上补充

- GIVEN 线上接口返回 `basic` 相关菜单数据
- WHEN 预览中心执行线上菜单合并
- THEN `basic` 分组 SHALL 继续以本地 `child[].preview` 配置为准
- AND 不应通过这条线上合并逻辑追加或覆盖 `basic` 条目

#### Scenario: tvtstore 条目不参与线上补充

- GIVEN 某个插件已声明 `tvtstore`
- WHEN 预览中心执行线上菜单合并
- THEN 该插件 SHALL 继续以本地配置为准
- AND 不应通过这条线上合并逻辑追加或覆盖其预览条目

### Requirement: 远程标签元数据与本地结构分离

预览中心 SHALL 将远程 `menuSetup` 标签数据与本地插件结构分开处理。远程标签数据可以驱动左侧徽标、预览卡片标记、筛选条件与编辑器提示，但 SHALL 不直接替换本地 `pluginsConfig` 中的插件结构与条目来源。

#### Scenario: editor 标签的特殊处理

- GIVEN 远程 `menuSetup` 将某个预览项标记为 `editor`
- WHEN 预览中心渲染左侧菜单与卡片
- THEN 该标签 SHALL 主要用于卡片侧的编辑器提示与交互
- AND 左侧菜单 MAY 不显示同名 `editor` 徽标

### Requirement: waitForGit 提示归属

当线上菜单补充引入了本地尚未同步的插件或预览项时，预览中心 SHALL 通过 `waitForGit` 等标记和提示文案向用户展示“线上已更新、本地待同步”的状态。这一提示属于预览中心的正式 UI 行为，而不是独立运维说明。

#### Scenario: 本地待同步提示

- GIVEN 预览项或插件条目来自线上补充而非本地代码
- WHEN 预览中心渲染卡片
- THEN 该条目 SHALL 带有待同步状态标记
- AND 预览界面 SHALL 显示对应提示文案

### Requirement: 预览交互为正式行为

预览中心的筛选、哈希跳转、分区滚动定位和分类展示 SHALL 被视为正式行为，不应视为偶然实现细节。后续若要调整这些行为，应先更新规范。

#### Scenario: 菜单点击滚动定位

- GIVEN 用户点击左侧菜单中的一个插件或分组
- WHEN 预览中心处理该交互
- THEN 内容区 SHALL 滚动到对应分区
- AND 路由哈希 SHALL 同步更新