# VISTA C-2.12 HOMEVISTA 轻应用化桌面启动需求

版本范围：C端 2.12（KASIKA版本）/ B端 1.28（无需求）/ A端 1.40（维护快捷方式 LOGO / Icon）  
文档状态：需求草案  
需求边界：本需求是 HOMEVISTA 轻应用化续期的第一阶段，本期只实现“桌面 / 主屏幕启动”这一项能力；不包含 Push 通知、离线缓存、后台同步、Service Worker 业务策略等其他轻应用化能力。

---

## 修改记录

| 日期 | 修订内容 |
|---|---|
| 2026-07-02 | 将需求定位从“网页添加桌面快捷方式”调整为“HOMEVISTA 轻应用化续期第一阶段”，明确本期只实现桌面 / 主屏幕启动能力 |
| 2026-07-02 | 明确版本范围：C端 2.12（KASIKA版本）、B端 1.28（无需求）、A端 1.40（维护快捷方式 LOGO / Icon） |
| 2026-07-02 | 删除 PWA 开关需求，A 端仅保留快捷方式 LOGO / Icon 上传、替换、清空能力 |
| 2026-07-02 | 明确快捷方式名称取项目别名字段，不取项目名称字段 |
| 2026-07-02 | 补充 PC、Pad、Mobile 的操作系统与浏览器支持范围，区分必须验收、兼容验证、不作为强验收范围 |
| 2026-07-02 | 明确不采用“所有操作系统 × 所有浏览器”全组合强验收，改为主路径强验收 + 代表性兼容抽样 + 不支持范围提示验证 |
| 2026-07-02 | 明确浏览器 / 系统支持能力与 HOMEVISTA 应用提示能力的责任边界，并补充不支持场景提示文案原则 |
| 2026-07-02 | 明确 C 端需提供 HOMEVISTA 自定义轻量引导入口，不只依赖浏览器主动安装提示；默认不使用阻断式强弹窗 |
| 2026-07-02 | 调整启动页面规则：快捷方式启动需进入对应项目 C 端首页并携带顾客身份参数，用于确认顾客身份 |
| 2026-07-02 | 补充 Manifest 基础配置、启动页面、显示模式、页面安装按钮边界，以及 Safari 添加到主屏幕 / Add to Dock 的差异说明 |
| 2026-07-02 | 补充 Icon 缺失兜底规则：未上传或清空图标时，使用系统默认图标（HOMEVISTA 默认 Icon）作为启动 Icon |
| 2026-07-02 | 整理文档结构，保留需求正文、验收标准与参考依据分层，减少重复验收项 |
| 2026-07-02 | 扩展参考依据，补充 PWA 基础概念、安装能力、Manifest、Safari Web App、Icon 缺失兜底等公开资料 |

---

## 1. 需求背景

### 1.1 版本范围

| 端 | 版本 | 本期范围 |
|---|---|---|
| C 端 | 2.12（KASIKA版本） | 支持 HOMEVISTA 轻应用化桌面 / 主屏幕启动、Manifest 基础配置、启动体验 |
| B 端 | 1.28 | 无需求，不新增 B 端轻应用化桌面启动能力 |
| A 端 | 1.40 | 在 VISTA 项目管理中维护快捷方式 LOGO / Icon |

### 1.2 背景说明

HOMEVISTA C 端目前主要通过浏览器链接访问。对于客户、销售人员和案场演示人员来说，如果每次都需要从聊天记录、邮件、二维码或浏览器收藏夹重新进入项目页面，访问路径较长，也不利于后续反复查看。

C-2.12 版本不是单纯为网页增加“添加到桌面快捷方式”，而是 HOMEVISTA 轻应用化续期的第一阶段。轻应用化的完整方向可以包含桌面启动、消息触达、离线能力、后台同步等能力，但本期只实现其中的“桌面 / 主屏幕启动”能力：让用户可以从手机主屏幕、Pad 主屏幕或桌面应用入口快速启动 HOMEVISTA C 端项目页面。

本需求不是完整轻应用化改造，也不要求本阶段处理消息推送、离线访问、后台通知等能力。

## 2. 产品目标

| 目标 | 说明 |
|---|---|
| 建立轻应用化启动入口 | 将 HOMEVISTA C 端从一次性浏览器链接，升级为可从系统桌面 / 主屏幕启动的项目入口 |
| 降低再次访问成本 | 用户可从系统桌面 / 主屏幕直接启动 HOMEVISTA C 端 |
| 提升项目入口稳定性 | 项目入口从聊天记录、邮件、二维码等一次性入口，转为用户设备上的长期入口 |
| 兼容主要终端 | 覆盖 Mobile、Pad、PC 的主要操作系统与浏览器启动路径 |
| 支持项目品牌展示 | A 端可在 VISTA 项目管理中维护快捷方式 LOGO / Icon，使启动入口更符合项目或品牌识别 |
| 控制本期范围 | 本期只实现桌面 / 主屏幕启动，不扩展到 Push、离线、通知管理、后台同步等轻应用后续能力 |

## 3. 适用角色与终端

| 角色 | 典型场景 | 终端 |
|---|---|---|
| C 端客户 / 访客 | 保存项目页面，后续反复查看资料、户型、地图、预约信息 | iOS / Android / Pad |
| 销售人员 | 在客户沟通或案场演示时快速打开项目 C 端 | 手机 / Pad / 桌面 |
| 案场演示人员 | 在展示设备上保留固定项目入口，减少每次查找链接 | Pad / 桌面 |
| 内部测试 / 验收人员 | 验证不同系统下快捷方式名称、Icon、打开页面是否正确 | iOS / Android / Pad / 桌面 |
| A 端运营人员 | 在 A 端 VISTA 项目管理中上传 / 更新快捷方式 LOGO / Icon | 桌面后台 |

## 4. 功能范围

### 4.1 本期包含

1. A 端 VISTA 项目管理支持上传 / 更新快捷方式 LOGO / Icon。
2. C 端提供桌面 / 主屏幕启动入口的创建引导，包括“添加到桌面 / 添加到主屏幕 / 安装应用”等平台化操作。
3. 针对 iOS、Android、Pad、桌面浏览器提供不同的用户操作提示。
4. 用户通过系统能力完成入口创建后，可从桌面 / 主屏幕启动 HOMEVISTA C 端。
5. 快捷方式名称取项目别名字段，Icon 使用 A 端 VISTA 项目管理中配置的快捷方式 LOGO / Icon。
6. 无法创建或当前浏览器不支持时，给出明确提示。

### 4.2 本期不包含

| 不包含项 | 说明 |
|---|---|
| Push 通知 | 不处理通知授权、订阅、发送、点击通知跳转 |
| 离线访问 | 不承诺断网后可浏览项目内容 |
| 后台同步 | 不处理后台数据同步或缓存刷新策略 |
| 原生 App 下载 | 不引导跳转 App Store / Google Play |
| B 端桌面启动 | B 端不需要轻应用化桌面启动能力，本期仅覆盖 C 端项目入口 |
| 多项目快捷方式管理中心 | 不提供用户侧批量管理多个项目入口的页面 |
| 添加状态记录 | 不记录用户是否已添加快捷方式 |
| 复杂安装数据统计 | 本期不要求统计安装成功率、卸载率等深度指标 |

### 4.3 终端、操作系统与浏览器支持范围

本需求按 PC、Pad、Mobile 三类终端定义支持范围。PWA 桌面 / 主屏幕启动能力依赖操作系统与浏览器共同支持，同一浏览器在不同操作系统上可能出现不同安装入口、提示样式、图标裁切和启动窗口表现。

本期不采用“所有操作系统 × 所有浏览器”的全组合强验收方式。验收策略为：**主路径强验收 + 代表性兼容抽样 + 不支持范围提示验证**。兼容抽样发现问题时，若不影响必须验收范围，可作为兼容问题记录，不默认阻断本期上线。

#### 4.3.1 必须验收范围

必须验收范围用于确认每类终端的主路径可用，不代表覆盖所有操作系统与浏览器组合。

| 终端 | 主操作系统 | 主浏览器 | 支持方式 | 验收要求 |
|---|---|---|---|---|
| Mobile | iOS | Safari | 通过分享菜单添加到主屏幕 | 可按引导添加到主屏幕；快捷方式名称、Icon、启动页面正确 |
| Mobile | Android | Chrome | 浏览器安装提示或页面内添加入口 | 可添加到桌面；快捷方式名称、Icon、启动页面正确 |
| Pad | iPadOS | Safari | 通过分享菜单添加到主屏幕 | 可按引导添加到主屏幕；Pad 展示和 Icon 显示正常 |
| Pad | Android Pad | Chrome | 浏览器安装提示或页面内添加入口 | 可添加到桌面；Pad 展示和 Icon 显示正常 |
| PC | Windows | Chrome | 浏览器安装入口 / 页面内安装入口 | 可安装为桌面应用入口；名称、Icon、启动页面正确 |
| PC | Windows | Edge | 浏览器安装入口 / 页面内安装入口 | 可安装为桌面应用入口；名称、Icon、启动页面正确 |
| PC | macOS | Chrome | 浏览器安装入口 / 页面内安装入口 | 可安装为桌面应用入口；名称、Icon、启动页面正确 |
| PC | macOS | Edge | 浏览器安装入口 / 页面内安装入口 | 可安装为桌面应用入口；名称、Icon、启动页面正确 |
| PC | macOS Sonoma 14+ | Safari 17+ | Safari 分享菜单或文件菜单 Add to Dock | 可添加为 Dock Web App；名称、Icon、启动页面正确 |

#### 4.3.2 兼容验证范围

兼容验证范围用于发现主要差异，不作为本期强验收阻断项。

| 终端 | 操作系统 | 浏览器 | 说明 |
|---|---|---|---|
| Mobile | Android | Edge | Chromium 内核浏览器，可做兼容验证，不作为主验收浏览器 |
| Mobile | Android | Samsung Internet | Android 常见浏览器，可做兼容验证，不作为主验收浏览器 |
| Mobile / Pad | iOS / iPadOS 16.4 及以上 | Chrome / Edge / Firefox | 可通过系统分享菜单添加到主屏幕，但不承诺页面按钮直接唤起安装弹窗 |
| PC | macOS 14 以下 | Safari | 不作为本期强验收范围；低版本 Safari 不承诺具备 Add to Dock Web App 能力 |

#### 4.3.3 差异项验收原则

| 差异项 | 验收原则 |
|---|---|
| 安装入口差异 | 允许不同浏览器使用不同入口，例如页面按钮、浏览器地址栏安装入口、分享菜单、Add to Dock |
| 文案差异 | 浏览器 / 系统原生弹窗文案跟随系统语言，不要求 HOMEVISTA 控制 |
| 图标裁切差异 | 必须确保主体验收范围内图标不明显变形、不主体截断；兼容浏览器出现轻微裁切差异可记录为兼容问题 |
| 启动窗口差异 | 必须满足类 App 独立窗口体验；不同系统保留状态栏、Dock、任务栏等系统 UI 属于正常差异 |
| 页面按钮差异 | 支持安装事件的浏览器可展示安装按钮；Safari 等不支持安装事件的浏览器仅展示操作引导 |
| 不支持环境 | 不要求实现安装能力，但必须展示清晰的浏览器 / 系统限制说明和替代路径 |

#### 4.3.4 不作为本期强验收范围

| 终端 | 操作系统 / 浏览器 | 说明 |
|---|---|---|
| PC | Firefox 桌面版 | 不作为桌面 PWA 独立安装验收浏览器 |
| Mobile / Pad | 旧版 iOS / iPadOS 非 Safari 浏览器 | 不作为本期验收范围 |
| Mobile / Pad | App 内置 WebView、企业微信 / LINE / 邮件内置浏览器等 | 不承诺可直接添加快捷方式；应提示用户使用支持的外部浏览器打开 |
| 全端 | 低版本或非主流浏览器 | 不承诺 PWA 快捷方式能力一致 |

#### 4.3.5 页面按钮支持边界

| 场景 | 需求口径 |
|---|---|
| Chromium 系浏览器 | 可在浏览器支持安装事件时展示页面内“添加到桌面 / 安装”按钮，并触发浏览器安装确认 |
| iOS / iPadOS Safari | 页面按钮不能直接唤起系统“添加到主屏幕”弹窗，仅展示分享菜单操作引导 |
| 不支持安装事件的浏览器 | 不强制展示可点击安装按钮，应展示对应浏览器 / 系统的手动添加引导或不支持提示 |

## 5. 用户用例

### UC1：A 端运营人员上传 PNG 图标

| 项目 | 内容 |
|---|---|
| 终端 | A 端桌面后台 |
| 使用人 | A 端运营人员 |
| 场景 | 某个 VISTA 项目需要配置 C 端桌面 / 主屏幕快捷方式图标 |
| 前置条件 | 运营人员具备 A 端 VISTA 项目管理编辑权限 |
| 用户流程 | 进入 A 端 VISTA 项目管理 -> 打开指定项目设置 -> 上传 1024 x 1024 正方形 PNG 图标 -> 保存 |
| 预期结果 | 该项目 C 端加载 PWA 基础配置，用户可按终端能力创建快捷方式；快捷方式名称取项目别名，Icon 使用上传的 PNG 图标 |
| 异常情况 | 图标尺寸或格式不符合要求时阻止保存 |
| 验收标准 | A 端可上传合规 PNG 图标；保存后 C 端配置生效 |

### UC2：iOS 用户添加到主屏幕

| 项目 | 内容 |
|---|---|
| 终端 | iPhone / iOS Safari |
| 使用人 | C 端客户 / 销售人员 |
| 场景 | 用户希望把当前 HOMEVISTA 项目保存在 iPhone 主屏幕 |
| 前置条件 | 用户通过 Safari 打开 C 端项目页面 |
| 用户流程 | 进入项目页面 -> 查看添加引导 -> 点击系统分享按钮 -> 选择“添加到主屏幕” -> 确认名称与 Icon -> 完成添加 |
| 预期结果 | iPhone 主屏幕出现以项目别名命名的项目快捷方式；点击后打开对应 C 端页面 |
| 异常情况 | 非 Safari 浏览器无法完成时，系统提示用户使用 Safari 打开后再添加 |
| 验收标准 | 引导文案清楚；Icon 与名称显示正确；从主屏幕打开后进入正确项目 |

### UC3：Android 用户添加到桌面

| 项目 | 内容 |
|---|---|
| 终端 | Android 手机 / Chrome |
| 使用人 | C 端客户 / 销售人员 |
| 场景 | 用户希望把 HOMEVISTA 项目作为桌面入口保存 |
| 前置条件 | 用户通过支持安装能力的 Android 浏览器打开 C 端项目页面 |
| 用户流程 | 进入项目页面 -> 点击“添加到桌面 / 安装”入口或浏览器提示 -> 确认添加 -> 返回桌面查看图标 |
| 预期结果 | Android 桌面出现快捷方式；点击后打开对应 C 端项目页面 |
| 异常情况 | 当前浏览器不支持时，提示使用 Chrome 或支持 PWA 安装的浏览器 |
| 验收标准 | 能完成添加；桌面 Icon 清晰；启动后打开正确页面 |

### UC4：Pad 用户添加到主屏幕或桌面入口

| 项目 | 内容 |
|---|---|
| 终端 | iPad / Android Pad |
| 使用人 | 销售人员 / 案场演示人员 |
| 场景 | 销售或案场人员希望在演示设备上保留固定项目入口 |
| 前置条件 | Pad 已打开指定 HOMEVISTA C 端项目页面 |
| 用户流程 | 打开项目页面 -> 根据系统展示添加引导 -> 完成添加 -> 在主屏幕或桌面入口启动 |
| 预期结果 | Pad 主屏幕出现项目入口；点击后进入 C 端项目，适配 Pad 展示 |
| 异常情况 | iPadOS 与 Android Pad 的操作入口不同，系统需展示对应平台提示，不应使用同一套泛化文案 |
| 验收标准 | iPad 与 Android Pad 至少各完成一轮添加与启动验证；入口名称和 Icon 不变形 |

### UC5：桌面浏览器安装为应用入口

| 项目 | 内容 |
|---|---|
| 终端 | Windows / macOS 桌面浏览器 |
| 使用人 | 销售人员 / 内部人员 / 案场演示人员 |
| 场景 | 用户希望在电脑上通过独立应用窗口或桌面入口打开 HOMEVISTA |
| 前置条件 | 用户通过支持 PWA 安装的桌面浏览器打开 C 端项目页面 |
| 用户流程 | 进入项目页面 -> 点击浏览器地址栏或页面内安装入口 -> 确认安装 -> 从桌面 / Dock / 开始菜单打开 |
| 预期结果 | 桌面系统出现 HOMEVISTA 应用入口；点击后打开对应 C 端项目页面 |
| 异常情况 | 浏览器不支持安装时，提示使用 Chrome / Edge 等支持安装能力的浏览器 |
| 验收标准 | Chrome / Edge 至少完成安装与启动验证；名称、Icon、启动页面正确 |

### UC6：用户从快捷方式再次打开项目

| 项目 | 内容 |
|---|---|
| 终端 | iOS / Android / Pad / 桌面 |
| 使用人 | 已创建快捷方式的用户 |
| 场景 | 用户后续不再从链接进入，而是从系统桌面打开 |
| 前置条件 | 用户已成功创建 HOMEVISTA 快捷方式 |
| 用户流程 | 点击桌面 / 主屏幕 Icon -> 系统打开 HOMEVISTA C 端 |
| 预期结果 | 进入创建快捷方式时对应的项目页面；如登录态失效，则先进入登录或授权流程，再回到目标项目 |
| 异常情况 | 项目链接失效或用户无权限时，展示明确的失效 / 无权限提示 |
| 验收标准 | 不出现空白页；不跳错项目；权限失效时有明确提示 |

## 6. C 端页面需求

### 6.1 添加入口与提示

| 状态 | 页面表现 |
|---|---|
| 当前终端与浏览器属于必须验收或兼容验证范围 | 展示“添加到桌面 / 添加到主屏幕 / 安装”入口或引导 |
| 浏览器未主动展示安装提示 | C 端仍需提供弱引导入口，不应完全依赖浏览器主动提示 |
| iOS / iPadOS | 展示基于系统分享菜单的操作引导 |
| Android | 支持展示添加 / 安装入口；如浏览器有原生提示，可与系统提示保持一致 |
| 桌面浏览器 | 展示桌面安装提示，文案使用“安装到电脑 / 创建桌面入口”等更符合桌面语境的表达 |
| 已经通过快捷方式打开 | 不重复强提示，可弱化为“已从桌面入口打开”或不展示入口 |
| 当前环境不支持或不在验收范围 | 明确说明“不支持当前浏览器添加，请使用 Safari / Chrome / Edge 等支持浏览器打开” |

### 6.2 引导文案原则

1. 文案必须按系统区分，不使用一套“点击添加到桌面”覆盖所有终端。
2. iOS / iPadOS 重点提示“分享按钮 -> 添加到主屏幕”。
3. Android 重点提示“添加到桌面 / 安装应用”。
4. 桌面端重点提示“安装到浏览器应用 / 创建桌面入口”。
5. 不承诺“下载 App”，避免用户误解为原生 App。
6. 如使用 HOMEVISTA 自定义引导文案，需补充对应国际化 key 值。
7. 如使用浏览器或操作系统原生文案，则跟随用户当前系统 / 浏览器语言，不额外定义 HOMEVISTA 国际化 key。
8. 不在本期文案中强调 Push、离线、消息提醒等尚未实现能力。

### 6.3 快捷方式启动页面与显示模式

| 项目 | 需求 |
|---|---|
| 默认启动页面 | 快捷方式打开后进入对应项目的 C 端首页，并携带顾客身份参数 |
| 项目识别 | 快捷方式需保持创建时对应的项目身份，不应跳转到其他项目 |
| 快捷方式名称 | 取项目别名字段；不取项目名称字段。项目名称当前已在 C 端用于显示字符串路径，不作为真实展示名称配置 |
| 顾客身份参数 | 启动 URL 必须携带用于确认顾客身份的参数，确保从桌面 / 主屏幕启动后可识别当前顾客 |
| 参数边界 | 本期仅允许启动所需的项目识别与顾客身份确认参数，不支持通过快捷方式配置任意营销参数、业务参数或深层链接跳转到指定内页 |
| 登录态处理 | 如登录态失效，应先进入登录 / 授权流程，完成后回到对应项目 C 端首页 |
| 显示模式 | 快捷方式启动后应按类 App 的独立窗口体验处理，不展示普通浏览器地址栏 |
| 全屏要求 | 本期不要求真正全屏模式；不得以隐藏系统状态栏、强制横竖屏或沉浸式全屏作为验收条件 |

### 6.4 Manifest 基础配置

| 项目 | 需求 |
|---|---|
| 必选要求 | C 端必须提供 Web App Manifest，用于支持系统识别快捷方式名称、Icon、启动页面与显示模式 |
| 应用名称 | Manifest 中的名称取项目别名字段 |
| 启动页面 | Manifest 启动页面需指向对应项目 C 端首页，并包含顾客身份参数 |
| 图标来源 | Manifest 使用 A 端 VISTA 项目管理中上传的快捷方式 LOGO / Icon；未配置时使用系统默认图标（HOMEVISTA 默认 Icon） |
| 兜底图标 | 当 A 端未上传快捷方式 LOGO / Icon，或已清空图标时，C 端必须使用系统默认图标作为启动 Icon |
| 显示模式 | Manifest 显示模式需支持类 App 独立窗口体验，不以真正全屏作为强制要求 |
| 范围边界 | 本期 Manifest 仅作为轻应用化桌面 / 主屏幕启动的基础配置，不扩展 Push、离线缓存、后台同步等能力 |

### 6.5 启动入口提示策略

| 项目 | 需求 |
|---|---|
| 提示目标 | 当用户以普通浏览器方式访问 C 端，且当前终端 / 浏览器支持创建桌面或主屏幕入口时，可提示用户将 HOMEVISTA 添加为桌面 / 主屏幕启动入口 |
| 引导入口必要性 | C 端需要提供 HOMEVISTA 自定义的轻量引导入口，不应只依赖浏览器主动安装提示 |
| 引导强度 | 默认使用弱引导入口，例如顶部/菜单/浮层提示；不使用每次访问都阻断操作的强弹窗 |
| Chromium 系浏览器 | 当浏览器触发安装事件时，C 端可展示自定义“添加到桌面 / 安装”按钮；用户点击按钮后再调用浏览器安装确认，不自动强制弹出 |
| iOS / iPadOS Safari | 不支持网页按钮直接唤起系统添加弹窗；C 端仅展示“分享按钮 -> 添加到主屏幕”的操作引导 |
| 不支持安装事件的浏览器 | 不展示可点击安装按钮；仅展示手动添加引导或不支持提示 |
| 已从启动入口进入 | 若识别到当前访问处于 standalone / 类 App 显示模式，说明用户本次是从桌面 / 主屏幕入口进入，不再展示添加引导 |
| 普通浏览器访问 | 若识别到当前访问仍处于 browser 模式，可按提示频控规则展示添加引导 |
| 已安装状态判断 | 本期不要求准确判断“用户是否已经创建过快捷方式”。不同浏览器和系统对已安装状态暴露不一致，不能作为强验收能力 |
| 用户本次未安装 | 若用户关闭引导、选择暂不安装或未完成安装，本次会话不再反复强提示；后续访问可继续提示，但必须有频控 |
| 频控规则 | 建议同一设备 / 浏览器在用户关闭或暂不安装后，至少 7 天内不再强提示；可保留弱入口，例如菜单中的“添加到桌面” |
| 安装完成记录 | 本期不记录用户是否已添加快捷方式；仅可基于本地浏览器状态做提示频控，不作为业务数据或用户状态判断 |
| 用户选择结果 | Chromium 系浏览器如能获得安装确认 / 取消结果，可用于本地提示频控；Safari 等无法获得系统添加结果的平台，不要求记录结果 |

### 6.6 不支持场景提示

PWA 桌面 / 主屏幕启动能力由浏览器与操作系统提供，HOMEVISTA C 端不负责实现浏览器本身不支持的安装能力。HOMEVISTA 需要负责识别当前环境是否属于支持范围，并给出可执行的提示或降级引导。

| 场景 | 能力归属 | C 端提示要求 |
|---|---|---|
| 当前浏览器支持安装事件 | 浏览器能力 | 展示“添加到桌面 / 安装”按钮，用户点击后调用浏览器安装确认 |
| iOS / iPadOS Safari | 系统 + Safari 能力 | 展示“请点击 Safari 分享按钮，选择添加到主屏幕”的图文或步骤引导 |
| macOS Safari 17+ / Sonoma 14+ | 系统 + Safari 能力 | 展示“请在 Safari 中选择分享 / 文件菜单，将本页面添加到 Dock”的步骤引导 |
| 当前浏览器不支持安装事件，但属于可手动添加范围 | 浏览器 / 系统能力 | 不展示可点击安装按钮，展示手动添加路径 |
| 当前环境不在支持范围 | 浏览器 / 系统限制 | 提示“当前浏览器暂不支持添加为桌面启动入口，请使用 Safari、Chrome 或 Edge 打开” |
| App 内置 WebView | 宿主 App 限制 | 提示“当前内置浏览器不支持添加桌面启动入口，请在系统浏览器中打开” |
| 桌面 Firefox | 浏览器限制 | 提示“当前桌面 Firefox 不作为本期支持浏览器，请使用 Chrome、Edge 或 macOS Safari 17+ 打开” |

提示文案原则：

1. 不使用“系统错误”“安装失败”等容易误导用户的文案。
2. 明确说明限制来自当前浏览器 / 系统环境，不暗示 HOMEVISTA 功能异常。
3. 给出下一步可执行操作，例如“复制链接到 Safari 打开”“使用 Chrome 打开”“使用 Edge 打开”。
4. 如果是 HOMEVISTA 自定义提示文案，需补充国际化 key；如果是浏览器 / 系统原生弹窗文案，则跟随系统语言。

## 7. A 端 Icon 配置需求

### 7.1 配置入口

| 项目 | 需求 |
|---|---|
| 配置位置 | A 端 VISTA 项目管理 |
| 配置对象 | 项目级快捷方式 LOGO / Icon |
| 上传数量 | 仅上传 1 个通用图标，不要求运营人员分别准备 iOS、Android、Pad、桌面多套图标 |
| 默认值 | 未上传时使用系统默认图标（HOMEVISTA 默认 Icon） |
| 权限 | 仅 A 端具备 VISTA 项目管理编辑权限的人员可上传 / 替换 / 清空图标 |
| 生效范围 | 影响该项目 C 端被添加到桌面 / 主屏幕时使用的快捷方式名称、Icon、启动页面与显示模式 |

### 7.2 上传与预览

| 功能 | 需求 |
|---|---|
| 上传文件 | 支持上传 1 个通用图标文件，文件必须为 1024 x 1024 的正方形 PNG |
| 图片尺寸 | 必须为 1024 x 1024；非该尺寸应阻止保存并提示用户重新上传 |
| 背景要求 | 建议使用不透明背景，避免在不同系统底色中显示异常 |
| 安全区提示 | 上传区需提示“图标主体不要贴边，需预留裁切安全区” |
| 预览 | 后台至少展示圆角 / 圆形裁切预览，用于模拟不同系统桌面效果 |
| 替换 | 替换 Icon 后，新创建的快捷方式使用新 Icon；已创建的旧快捷方式不强制同步更新 |
| 清空 | 清空后恢复系统默认图标（HOMEVISTA 默认 Icon） |

## 8. 验收标准

### 8.1 A 端配置验收

| 验收项 | 标准 |
|---|---|
| 图标上传 | A 端 VISTA 项目管理可上传 1024 x 1024 正方形 PNG 图标 |
| 图标校验 | 非 PNG 或非 1024 x 1024 文件应阻止保存并提示用户重新上传 |
| 配置生效 | A 端保存后，对应项目 C 端按最新 Icon 配置生效 |
| 兜底图标 | 未上传或清空图标时，对应项目 C 端使用系统默认图标作为启动 Icon |

### 8.2 C 端创建快捷方式验收

| 验收项 | 标准 |
|---|---|
| 验收策略 | 不按“所有操作系统 × 所有浏览器”全矩阵强验收；按主路径强验收、兼容抽样、不支持提示验证执行 |
| 差异项处理 | 不同操作系统 / 浏览器的安装入口、原生文案、图标裁切、窗口 UI 存在差异；只要满足本需求主路径目标，不作为默认阻断项 |
| Mobile iOS 添加 | iPhone Safari 可根据引导添加到主屏幕，并从主屏幕打开正确项目 |
| Mobile Android 添加 | Android Chrome 可添加到桌面，并从桌面打开正确项目 |
| Pad 添加 | iPadOS Safari 与 Android Pad Chrome 可完成添加，Icon 与名称显示正常 |
| PC 桌面安装 | Windows Chrome / Edge、macOS Chrome / Edge、macOS Sonoma 14+ Safari 17+ 可安装或创建入口，并从桌面 / Dock 入口打开正确项目 |
| 兼容浏览器验证 | Android Edge、Android Samsung Internet、iOS / iPadOS 16.4+ Chrome / Edge / Firefox 可按兼容验证范围抽样检查；发现差异记录为兼容问题，不默认阻断上线 |
| 不支持浏览器提示 | 桌面 Firefox、旧版 iOS 非 Safari、App 内置 WebView 等不作为强验收范围；访问时应展示手动引导或不支持提示 |
| Manifest 配置 | C 端提供 Web App Manifest，名称、Icon、启动页面、显示模式与本需求一致 |
| 快捷方式名称 | 快捷方式名称取项目别名字段，不取项目名称字段 |
| 启动页面 | 快捷方式打开后进入对应项目 C 端首页，并携带顾客身份参数用于确认顾客身份 |
| 参数边界 | 快捷方式启动 URL 仅允许项目识别与顾客身份确认参数，不支持任意参数或深层链接跳转到指定内页 |
| 显示模式 | 快捷方式启动后呈现类 App 独立窗口体验，不以真正全屏作为验收条件 |
| 启动来源识别 | 从桌面 / 主屏幕入口进入时，可识别为 standalone / 类 App 模式，并不再展示添加引导 |
| 普通浏览器访问 | 普通浏览器方式访问时，可按当前终端 / 浏览器能力展示添加引导 |
| 提示频控 | 用户关闭引导、选择暂不安装或未完成安装后，本次会话不再反复强提示；后续访问按频控规则提示 |
| 已安装状态 | 本期不要求准确判断用户是否已经创建过快捷方式，也不记录添加状态 |
| 登录态处理 | 快捷方式打开后如登录态失效，应进入登录 / 授权流程，不应空白或跳错项目 |
| 权限处理 | 用户无项目权限时，展示无权限提示 |

### 8.3 Icon 验收

| 验收项 | 标准 |
|---|---|
| 默认 Icon | 未上传快捷方式 LOGO / Icon 时，各端显示系统默认图标（HOMEVISTA 默认 Icon） |
| 项目 Icon | A 端上传快捷方式 LOGO / Icon 后，新创建的快捷方式显示该 Icon |
| iOS / iPadOS | 主屏幕 Icon 清晰，无明显模糊、透明底异常、主体截断 |
| Android | 桌面 Icon 在系统裁切后主体完整 |
| Pad | 横竖屏与不同主屏幕布局下 Icon 显示正常 |
| 桌面 | 桌面入口、Dock / 任务栏 / 开始菜单图标清晰 |
| 替换 Icon | 后台替换后，新创建的快捷方式使用新 Icon；已创建的旧快捷方式不强制同步更新 |
| 清空 Icon | 清空快捷方式 LOGO / Icon 后，新创建快捷方式恢复系统默认图标（HOMEVISTA 默认 Icon） |

## 9. 技术调研重点

本章节用于沉淀研发评审需要关注的技术边界，包括浏览器支持范围、安装入口、Manifest、Safari Web App、Icon 兜底等问题。以下内容用于支撑产品需求边界，不替代最终技术实现方案。

### 9.1 PWA 安装能力与浏览器差异

| 参考点 | 对本需求的影响 |
|---|---|
| PWA 是可安装的 Web App，不是原生 App 安装包 | 本需求不涉及 App Store / Google Play，也不要求原生 App 能力 |
| PWA 由 Web 页面提供 Manifest、Icon、启动 URL 等配置，由浏览器解析并由系统展示入口 | 本需求需同时定义 C 端 Manifest、A 端 Icon 配置、系统桌面 / 主屏幕展示结果 |
| PWA 安装能力由浏览器和操作系统共同提供，不是单纯 C 端页面能力 | 本需求需要明确 PC / Pad / Mobile、操作系统、浏览器支持范围 |
| Android 常见浏览器支持 PWA 安装，但不同浏览器安装入口和提示样式不同 | Android Chrome 作为必须验收浏览器，Android Edge / Samsung Internet 作为兼容验证 |
| iOS / iPadOS 主要通过系统分享菜单添加到主屏幕 | iOS / iPadOS 不承诺页面按钮直接唤起系统添加弹窗 |
| 桌面端 Chrome / Edge 是主要 PWA 安装浏览器 | Windows / macOS 的 Chrome / Edge 作为必须验收浏览器 |
| macOS Sonoma 14+ / Safari 17+ 支持 Add to Dock Web App | macOS Safari 需限定版本，并按 Add to Dock 路径验收 |
| 桌面 Firefox 不作为 PWA 独立安装强验收浏览器 | 桌面 Firefox 只提示不支持或手动引导，不作为阻断项 |

来源：

1. web.dev Progressive Web Apps：说明 PWA 是可安装、可跨设备访问的 Web App，安装后外观接近应用，但仍基于 Web 技术。  
   https://web.dev/learn/pwa/progressive-web-apps
2. MDN Progressive Web Apps：说明 PWA 使用 Web 平台能力，让网站具备类似应用的体验。  
   https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps
3. MDN Making PWAs installable：说明 Android、iOS / iPadOS 等平台安装 PWA 的浏览器支持差异。  
   https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Guides/Making_PWAs_installable
4. web.dev PWA Installation：说明桌面 PWA 安装主要由 Chrome / Edge 等浏览器支持，且不同桌面浏览器体验不同。  
   https://web.dev/learn/pwa/installation
5. Apple Support - Use Safari web apps on Mac：macOS Sonoma 14+ 可在 Safari 中通过 Add to Dock 将网页保存为 Web App。  
   https://support.apple.com/en-us/104996

### 9.2 页面按钮与安装提示边界

| 参考点 | 对本需求的影响 |
|---|---|
| Chromium 系浏览器在满足安装条件时可触发安装事件 | Android Chrome、桌面 Chrome / Edge 可支持页面内安装按钮或浏览器安装入口 |
| `beforeinstallprompt` 不是所有主流浏览器都支持 | 不能把页面按钮直接安装作为全平台统一能力 |
| 安装事件可被保存，并在用户点击自定义按钮时触发浏览器安装确认 | C 端可做“添加到桌面 / 安装”按钮，但必须由用户点击触发，不做强制安装 |
| 安装提示只能对同一个安装事件调用一次；用户拒绝后需等待后续事件或使用自定义频控 | 用户本次未安装后，本次会话不再反复强提示，后续访问按频控规则提示 |
| iOS / iPadOS Safari 不按 `beforeinstallprompt` 方式工作 | iOS / iPadOS 仅展示“分享按钮 -> 添加到主屏幕”的操作引导 |
| 不支持安装事件的浏览器仍可能支持手动添加，或完全不支持 | C 端需按浏览器展示手动引导或不支持提示 |

来源：

1. MDN beforeinstallprompt：说明页面内安装按钮依赖浏览器安装事件，且该能力不是所有主流浏览器都支持。  
   https://developer.mozilla.org/en-US/docs/Web/API/Window/beforeinstallprompt_event
2. MDN Trigger installation from your PWA：说明可保存安装事件并通过自定义按钮触发浏览器安装确认。  
   https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/How_to/Trigger_install_prompt
3. web.dev Installation prompt：说明 iOS / iPadOS 上无法依赖安装事件，通常需要引导用户使用 Safari 分享菜单添加到主屏幕。  
   https://web.dev/learn/pwa/installation-prompt

### 9.3 Manifest 与启动信息

| 参考点 | 对本需求的影响 |
|---|---|
| Manifest 用于向浏览器提供 Web App 的名称、Icon、启动 URL、显示模式等信息 | C 端必须提供 Web App Manifest |
| 普通网页即使也能被某些系统添加为快捷方式，如果缺少 Manifest / Icon 等配置，体验和品牌展示不可控 | 本需求目标不是普通网页书签，而是具备基础 PWA 配置的项目快捷方式 |
| Manifest 的启动 URL 决定快捷方式打开后的默认页面 | 本需求定义快捷方式打开后进入对应项目 C 端首页，并携带顾客身份参数 |
| Manifest 的显示模式影响是否以类似 App 的独立窗口展示 | 本需求要求类 App 独立窗口体验，但不要求真正全屏 |
| 可通过 display-mode 判断当前页面是否以 standalone / browser 等模式运行 | C 端可识别本次访问是从桌面 / 主屏幕入口进入，还是普通浏览器方式访问 |
| PWA 运行本质仍由浏览器提供容器，系统只负责展示桌面 / 主屏幕入口 | 不能把本需求描述为原生 App 安装 |

来源：

1. web.dev Web App Manifest：说明 Manifest 会告诉浏览器 PWA 安装到桌面或移动设备后应如何表现。  
   https://web.dev/learn/pwa/web-app-manifest
2. MDN start_url：说明 Manifest 中的启动 URL 用于定义应用启动时打开的页面。  
   https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/start_url
3. MDN display：说明 Manifest 中的显示模式用于控制 Web App 启动后的浏览器 UI 展示方式。  
   https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/display
4. web.dev Detection：说明可通过 display-mode media query 判断 PWA 的启动显示模式。  
   https://web.dev/learn/pwa/detection

### 9.4 Safari 添加到主屏幕 / Add to Dock 边界

| 参考点 | 对本需求的影响 |
|---|---|
| iOS / iPadOS Safari 的“添加到主屏幕”是系统操作入口，不等同于网页天然具备完整 PWA 配置 | C 端仍需提供 Manifest、Icon、启动页面和显示模式配置 |
| 普通网页也可能被 Safari 添加到主屏幕或 Dock，但缺少 PWA 配置时更接近网页快捷方式 | 本需求要求添加后的入口使用项目别名、项目 Icon、项目 C 端首页 |
| macOS Safari 17+ / Sonoma 14+ 的 Add to Dock 可把网页保存为独立 Web App | macOS Safari 必须按 Add to Dock 路径单独验收 |
| Safari 不依赖 Chromium 的 `beforeinstallprompt` 安装事件 | Safari 端只做操作引导，不承诺页面按钮直接唤起系统弹窗 |

来源：

1. Apple Support - Use Safari web apps on Mac：说明 macOS Sonoma 14+ Safari 可通过 Add to Dock 创建 Web App，并可设置名称和图标。  
   https://support.apple.com/en-us/104996
2. Apple Safari User Guide - Turn a website into an app in Safari on Mac：说明 Safari 可将网页添加到 Dock 并以 Web App 方式打开。  
   https://support.apple.com/guide/safari/add-to-dock-ibrw9e991864/mac
3. Apple Safari Web Content：说明 iOS / iPadOS 添加到主屏幕时可通过 apple-touch-icon 指定 Web Clip 图标。  
   https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariWebContent/ConfiguringWebApplications/ConfiguringWebApplications.html

### 9.5 Icon 配置与缺失兜底

| 参考点 | 对本需求的影响 |
|---|---|
| Manifest icons 用于定义 Web App 在桌面、主屏幕、任务栏、Dock 等位置的代表图标 | A 端需提供快捷方式 LOGO / Icon 上传能力 |
| 如果没有提供合适 Icon，有些平台可能无法通过安装条件 | C 端不应依赖浏览器自动兜底作为正式结果 |
| 如果 Icon 缺失或尺寸不合适，有些平台会自动生成图标、使用截图、favicon 或通用图标 | 本需求要求未上传时使用系统默认图标（HOMEVISTA 默认 Icon），而不是浏览器自动生成图标 |
| Android 等系统可能对图标进行圆形、圆角矩形等裁切 | A 端上传区需提示图标主体预留安全区 |
| iOS / iPadOS 可使用 apple-touch-icon 影响添加到主屏幕后的图标 | iOS / iPadOS 需单独验收主屏幕 Icon 清晰度和裁切效果 |

来源：

1. MDN PWA App Icons：说明 PWA 通常需要定义一组不同尺寸、类型和用途的 icons，浏览器会按使用场景选择合适图标。  
   https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/How_to/Define_app_icons
2. MDN Manifest icons：说明 Manifest icons 用于定义代表 Web App 的图标资源。  
   https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/icons
3. web.dev Web App Manifest：说明未提供合适图标时，不同平台可能安装失败或自动生成图标。  
   https://web.dev/learn/pwa/web-app-manifest
4. Chrome Lighthouse PWA Installable Manifest：安装能力至少关注 192x192 与 512x512 图标，并建议具备 maskable 图标。  
   https://developer.chrome.com/docs/lighthouse/pwa/installable-manifest
5. Apple Safari Web Content：iOS / iPadOS 添加到主屏幕时可通过 apple-touch-icon 指定 Web Clip 图标，也可为不同分辨率提供不同尺寸。  
   https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariWebContent/ConfiguringWebApplications/ConfiguringWebApplications.html