# HomeVista PWA 技术难点与开发周期评估

> 适用场景：HomeVista 是一个面向房地产 / 项目销售场景的定制类 SaaS 工具，采用 **自研 CRM / Notification Service + 第三方 Push 通道** 的方式实现 PWA 能力。  
> 本文档用于评估 HomeVista 升级 PWA 的技术难点、风险点、实施周期和建议开发节奏。

---

# 一、总体判断

PWA 本身不算特别难，难点主要在：

> **PWA + Push + 多租户权限隔离 + 真实业务上线稳定性**

对于 HomeVista 来说，真正的复杂度不只是“让网页可以添加到桌面”或“让浏览器收到通知”，而是要保证：

- 客户 A 的通知不能发给客户 B。
- 项目 A 的消息不能混到项目 B。
- 用户退出项目后不能继续收到该项目通知。
- 用户点击旧通知时，仍然必须重新校验权限。
- Push 内容不能暴露敏感客户信息、报价信息、房源细节。
- 第三方 Push 服务只能作为投递通道，不能承担权限判断。

因此，HomeVista 的 PWA 技术难点应从 **安装体验、Service Worker、Push 链路、subscription 管理、多租户隔离、测试矩阵** 六个方面评估。

---

# 二、PWA 的主要技术难点

## 1. 安装体验不统一

PWA 的基础安装依赖以下能力：

- `manifest.json`
- Service Worker
- HTTPS
- 应用图标
- 浏览器安装能力支持

技术本身不复杂，但不同平台的体验差异较大。

| 平台 | 难点 |
|---|---|
| Android Chrome | 可以通过 `beforeinstallprompt` 做安装引导，但触发时机由浏览器控制 |
| iOS Safari | 不能像 Android 那样自动弹安装弹窗，通常要引导用户手动“添加到主屏幕” |
| 桌面 Chrome / Edge | 支持安装，但入口和交互与移动端不同 |
| Safari 桌面端 | Push、安装体验和 Chrome 系浏览器有差异 |

### 产品上需要分别设计

```txt
Android：显示“安装 HomeVista”按钮
iOS：显示“点击分享按钮 → 添加到主屏幕”的图文引导
桌面端：显示“安装为桌面应用”的提示
```

### 难点总结

这部分技术难度不高，主要难点是：

- 不同平台的安装入口不同。
- iOS 不能自动触发安装弹窗。
- 用户是否已经安装 PWA 的判断需要做兼容处理。
- 安装引导不能打扰用户，需要控制展示频率。
- 安装后需要确保进入 standalone 模式。

---

## 2. Service Worker 缓存策略容易出问题

Service Worker 是 PWA 的核心能力之一，它可以处理：

- 静态资源缓存
- 离线访问
- 网络请求拦截
- Push 事件接收
- 通知点击处理
- 应用版本更新

真正的难点不是注册 Service Worker，而是 **缓存策略设计**。

HomeVista 不能简单地“全部缓存”，因为系统中存在大量敏感业务数据：

```txt
客户线索
客户手机号
报价信息
房源资料
销售跟进记录
项目内部消息
预约信息
```

如果缓存策略设计不好，可能出现严重问题：

```txt
用户退出项目后，浏览器缓存里还能看到旧项目数据
客户 A 的缓存页面展示了客户 B 的旧数据
版本发布后用户还在用旧 JS，导致白屏或接口不兼容
用户切换项目后，旧缓存数据被误展示
```

### 推荐缓存策略

| 数据类型 | 建议策略 |
|---|---|
| App Shell | 可缓存 |
| JS / CSS / 图标 | 可缓存，使用 hash 版本 |
| 登录态接口 | 不缓存 |
| 用户信息接口 | 不缓存或 Network Only |
| 客户数据 | 不缓存或极短缓存 |
| 报价数据 | 不缓存 |
| 项目列表 | Network First |
| 房源公开素材 | 可按需缓存 |
| 3D / VR 大文件 | 使用 CDN 缓存，不建议 Service Worker 全量缓存 |
| 离线页 | 可缓存 |

### 难点总结

Service Worker 的主要风险是：

- 缓存旧版本导致页面异常。
- 缓存敏感业务数据导致安全风险。
- 多项目切换时旧数据误展示。
- 发布新版本时用户端没有及时更新。
- 离线状态下要避免展示过期或无权限数据。

---

## 3. Push 通知链路比看起来复杂

Web Push 不是“后端调一个接口就完成”。

完整链路如下：

```txt
用户点击开启通知
        ↓
浏览器授权 Notification Permission
        ↓
Service Worker 注册成功
        ↓
PushManager 生成 subscription
        ↓
前端把 subscription 发给 HomeVista 后端
        ↓
HomeVista 后端绑定 tenant / project / user / device
        ↓
业务事件触发通知
        ↓
HomeVista 后端筛选接收人
        ↓
调用第三方 Push 通道
        ↓
浏览器唤醒 Service Worker
        ↓
Service Worker 展示通知
        ↓
用户点击通知
        ↓
打开目标页面并重新做权限校验
```

任何一环出问题，用户都可能收不到通知。

### 常见失败点

```txt
Service Worker 未注册成功
用户拒绝通知权限
浏览器不支持 Push
iOS 用户没有从主屏幕打开 PWA
subscription 未保存成功
subscription 已失效
第三方 Push 发送失败
通知 payload 格式异常
Service Worker 中 push 事件处理失败
通知点击后目标页面无权限
```

### iOS 特别注意

iOS 上 Web Push 有更多限制，需要特别关注：

- 用户是否使用支持 Web Push 的 iOS 版本。
- 用户是否已经将 HomeVista 添加到主屏幕。
- 用户是否从主屏幕打开 HomeVista。
- 用户是否主动点击按钮开启通知。
- 用户是否允许通知权限。

### 难点总结

Push 的主要难点是：

- 链路长，任何环节失败都会影响送达。
- iOS 真机调试成本高。
- 用户授权状态不可控。
- subscription 可能失效或变化。
- 通知点击后必须重新做权限校验。

---

## 4. Subscription 管理是 HomeVista 的重点难点

普通产品可以简单存储：

```txt
user_id + subscription
```

但 HomeVista 不能这么做。

HomeVista 是多租户、多项目 SaaS，一个用户可能同时属于多个客户、多个项目，并且在不同项目中可能有不同角色。

因此，subscription 必须绑定：

```txt
tenant_id
project_id
user_id
device_id
provider
subscription / token
permission_status
is_active
```

### 为什么不能只绑定 user_id

错误设计：

```txt
user_id = 100
subscription = xxx
```

风险：

```txt
用户 100 同时属于项目 A 和项目 B
项目 A 的通知可能错误发送到项目 B 场景
用户退出项目 A 后仍可能收到项目 A 通知
无法判断某个设备订阅属于哪个项目
无法做项目级通知开关
```

### 推荐绑定方式

```txt
tenant_id + project_id + user_id + device_id + subscription
```

### Subscription 管理需要处理的问题

```txt
一个用户多个设备
一个设备多个项目
用户退出项目后停止该项目通知
用户重新授权后 subscription 可能变化
subscription 失效后自动标记
浏览器清缓存后重新订阅
同一个 endpoint 重复提交时去重
不同 Push Provider 的 token 格式不同
```

### 难点总结

Subscription 管理是 HomeVista PWA 的核心业务难点，应独立放入 Notification Service 中，不建议散落在 CRM 各业务模块里。

---

## 5. 多租户隔离比 Push 本身更重要

HomeVista 的真正难点是：

> 发通知之前，必须确定这个人现在仍然有这个 tenant / project 的权限。

不能出现：

```txt
客户 A 的项目通知发给客户 B
项目 A 的报价更新发给项目 B 的销售
用户已被移出项目但仍收到项目通知
点击旧通知后还能看到已无权限的数据
```

### 发送前必须校验

```txt
tenant 校验
project 校验
role 校验
用户状态校验
通知偏好校验
设备订阅状态校验
```

### 点击通知后必须再次校验

```txt
登录态校验
tenant 权限校验
project 权限校验
目标数据是否存在
通知是否过期
用户是否仍属于该项目
```

### 第三方 Push 的边界

第三方 Push 服务只能负责：

```txt
把通知送到设备
返回发送状态
```

不能负责：

```txt
判断谁应该收到
判断用户是否有项目权限
判断通知是否跨租户
判断通知内容是否敏感
```

### 推荐原则

```txt
HomeVista 决定“谁应该收到通知”
第三方 Push 服务只负责“把通知送达”
```

### 难点总结

多租户隔离是 SaaS 安全底线。对于 HomeVista 来说，这部分比 Push 技术本身更重要。

---

## 6. 测试矩阵比较大

PWA + Push 的测试不能只测一个浏览器。

至少要测试：

```txt
Android Chrome
iOS Safari
Desktop Chrome
Desktop Edge
Desktop Safari
```

还要测试不同状态组合：

```txt
未安装 PWA
已安装 PWA
未授权通知
已授权通知
用户拒绝通知
用户清除浏览器数据
用户退出项目
用户被移除项目
subscription 失效
第三方 Push 发送失败
点击通知时未登录
点击通知时无权限
项目已删除
通知已过期
```

### 多租户测试必须覆盖

```txt
客户 A 用户不能收到客户 B 通知
项目 A 用户不能收到项目 B 通知
用户被移出项目后不能继续收到通知
用户点击旧通知后不能访问无权限数据
同一个用户在多个项目中的订阅互不影响
不同项目的通知偏好互不影响
```

### 难点总结

测试成本高，尤其是：

- iOS 真机测试。
- 多设备测试。
- 多租户隔离测试。
- subscription 失效场景测试。
- 第三方 Push 失败场景测试。

---

# 三、技术难度排序

| 难度 | 模块 | 说明 |
|---|---|---|
| 低 | Manifest / 图标 / 基础安装 | 主要是配置和适配 |
| 中 | Service Worker 注册与版本更新 | 要避免缓存旧版本导致白屏 |
| 中 | Android / 桌面安装体验 | 技术成熟，但交互要打磨 |
| 中高 | Push 订阅与第三方通道接入 | 链路长，状态多 |
| 高 | iOS Push 兼容与引导 | 限制多，真机测试成本高 |
| 高 | 多租户 subscription 管理 | HomeVista 的核心难点 |
| 高 | 通知权限、偏好、日志审计 | 关系到产品化和客户排错 |
| 很高 | 权限隔离与防串项目 | 这是 SaaS 安全底线 |

---

# 四、一般完整实施需要多久

实施周期取决于目标范围。

---

## 方案 A：最小 PWA 安装版

### 范围

只做：

```txt
manifest
图标
Service Worker 注册
Android 添加到桌面
iOS 添加到主屏幕引导
基础离线页
```

### 开发周期

```txt
3 - 7 个工作日
```

### 适合目标

适合先验证：

```txt
HomeVista 可以像 App 一样添加到手机桌面
```

---

## 方案 B：PWA + 基础 Push MVP

### 范围

包含：

```txt
PWA 安装能力
Service Worker
通知权限申请
Push subscription 保存
第三方 Push 通道接入
单用户推送
通知点击跳转
基础发送日志
```

### 开发周期

```txt
2 - 4 周
```

### 适合目标

适合验证：

```txt
用户可以安装 HomeVista
用户可以开启通知
后端可以向指定用户发送通知
通知点击后可以跳转到指定页面
```

---

## 方案 C：适合 HomeVista 的可上线版本

### 范围

建议 HomeVista 至少做到这个级别：

```txt
PWA 安装
iOS / Android 引导
Service Worker 稳定更新策略
第三方 Push Provider 接入
tenant + project + user + device 绑定
通知偏好设置
项目级通知开关
新客户咨询通知
项目公告通知
预约提醒
通知点击权限校验
基础通知日志
失效 subscription 处理
基础 CRM 通知管理页面
```

### 开发周期

```txt
4 - 8 周
```

### 适合目标

适合正式上线第一版：

```txt
能安装
能授权
能订阅
能按项目发通知
不能串租户 / 串项目
能查到发送记录
```

---

## 方案 D：完整产品化通知中台

### 范围

包含：

```txt
通知规则管理
通知模板管理
多项目通知配置
角色级接收人配置
用户级通知偏好
设备管理
发送记录
失败重试
Provider Adapter
测试发送
定时推送
统计报表
审计日志
多语言模板
客户级配置
告警监控
```

### 开发周期

```txt
8 - 12 周，甚至更长
```

### 适合目标

适合把通知系统做成完整产品模块：

```txt
客户管理员可以配置通知规则
项目管理员可以查看发送记录
平台可以管理 Push Provider
系统可以支持审计、统计、失败排查和扩展
```

---

# 五、按 HomeVista 推荐的开发节奏

建议不要一口气做完整通知中台，而是分三期推进。

---

## 第一期：PWA + Push MVP

### 周期建议

```txt
3 - 4 周
```

### 范围

```txt
1. PWA manifest
2. Service Worker
3. Android 安装引导
4. iOS 添加到主屏幕引导
5. 通知权限申请
6. subscription 保存
7. 绑定 tenant_id + project_id + user_id + device_id
8. 接入第三方 Push 通道
9. 新客户咨询通知
10. 项目公告通知
11. 通知点击跳转
12. 基础发送日志
```

### 目标

```txt
能安装
能授权
能订阅
能按项目发通知
不能串租户 / 串项目
能查到发送记录
```

---

## 第二期：通知设置和业务规则

### 周期建议

```txt
2 - 4 周
```

### 范围

```txt
1. 用户端通知设置页
2. 项目级通知开关
3. 通知类型开关
4. 预约提醒
5. 报价更新提醒
6. 房源状态变更提醒
7. 设备解绑
8. 失效 subscription 清理
9. 通知点击统计
```

### 目标

```txt
让通知能力从“可用”变成“可管理”。
```

---

## 第三期：CRM 通知管理后台

### 周期建议

```txt
3 - 6 周
```

### 范围

```txt
1. 通知概览
2. 通知规则
3. 通知模板
4. 用户订阅
5. 设备管理
6. 发送记录
7. Provider 配置
8. 审计日志
9. 测试发送
10. 统计报表
```

### 目标

```txt
让客户管理员 / 项目管理员可以在 CRM 内管理通知。
```

---

# 六、人员配置建议

## 小团队配置

如果团队配置是：

```txt
1 名前端
1 名后端
0.5 名测试
0.5 名产品 / 设计
```

比较合理的时间是：

```txt
MVP：3 - 5 周
可上线版本：5 - 8 周
完整通知中台：8 - 12 周+
```

---

## 标准团队配置

如果团队配置是：

```txt
2 名前端
2 名后端
1 名测试
1 名产品 / 设计
```

周期可以压缩到：

```txt
MVP：2 - 3 周
可上线版本：4 - 6 周
完整通知中台：6 - 10 周
```

但前提是：

```txt
现有 CRM 权限体系已经比较完善
tenant / project / role 数据模型已经存在
第三方 Push Provider 不需要复杂定制
```

---

# 七、HomeVista 正式开发前需要确认的问题

在正式开发前，建议先确认以下问题，否则容易返工：

1. HomeVista 现在是否已经有明确的 `tenant_id` 和 `project_id` 数据模型？
2. 用户是否可能同时属于多个客户或多个项目？
3. 一个用户在不同项目里的角色是否可能不同？
4. 通知是按“用户”订阅，还是按“项目”订阅？
5. 哪些通知属于 MVP？
6. Push 内容是否必须全部脱敏？
7. 客户管理员是否需要自己配置通知规则？
8. 是否有未来私有化部署或客户独立部署需求？
9. 用户退出项目时，是否需要自动解绑该项目 subscription？
10. 是否需要为不同客户配置不同 Push Provider？
11. 是否需要支持多语言通知？
12. 通知日志需要保存多久？
13. 客户是否可以导出通知发送记录？
14. 是否需要对失败通知进行重试？
15. 是否需要对通知频率做限制，避免打扰用户？

---

# 八、推荐的实施结论

对 HomeVista 来说：

```txt
PWA 基础能力：不难，约 1 周内可完成
Push MVP：中等难度，约 2 - 4 周
多租户通知系统：真正难点，约 4 - 8 周
完整 CRM 通知中台：产品化工程，约 8 - 12 周+
```

如果要做一个可上线、可靠、不串项目的版本，建议按：

```txt
第一期 4 - 6 周
```

来规划比较稳妥。

如果只做演示版或内部验证版：

```txt
2 - 3 周
```

可以做出 MVP。

但如果要做成客户可配置、可审计、可长期维护的 HomeVista 通知中台：

```txt
至少按 2 - 3 个月规划
```

更合理。

---

# 九、最终建议

HomeVista 的 PWA 升级不应被看作单纯的前端功能，而应看作：

> **一个面向多租户 SaaS 的通知基础设施建设项目。**

推荐路线：

```txt
第一阶段：完成 PWA 安装 + Push MVP
第二阶段：完成项目级通知偏好和核心业务通知
第三阶段：完成 CRM 通知管理后台和审计体系
```

技术架构建议：

```txt
HomeVista CRM 业务事件
        ↓
Notification Service
        ↓
租户 / 项目 / 用户 / 设备 / 权限校验
        ↓
通知模板与脱敏处理
        ↓
发送日志与审计
        ↓
第三方 Push Provider
        ↓
PWA Service Worker
        ↓
用户设备通知
```

核心原则：

```txt
HomeVista 自己决定谁应该收到通知
第三方 Push 只负责投递
所有通知必须带 tenant_id 和 project_id
所有 Push 内容默认脱敏
通知点击后必须重新做权限校验
```