Initial TrueGrowth source import
This commit is contained in:
@@ -0,0 +1,14 @@
|
||||
## Context
|
||||
发版窗口中存在“服务器已切到新版本、npm CDN 还未完全可用”的短暂不一致窗口。此前的 CDN 绝对优先会触发 404 或错误页，改成源站优先后又牺牲了正常流量下的加载速度。
|
||||
|
||||
## Goals
|
||||
- 对版本化静态资源尽可能优先使用 CDN
|
||||
- 对入口链路保持同源优先，避免版本错配
|
||||
- CDN 异常时快速熔断并回源，避免一个页面内重复踩坑
|
||||
- 允许 Service Worker 复用已校验过的 CDN 缓存响应
|
||||
|
||||
## Decisions
|
||||
- 使用已有 `cdn-config.js` 的测速结果作为偏好输入，但真正的资源选择由 Service Worker 执行
|
||||
- 偏好数据持久化到独立 Cache Storage，避免引入新的 IndexedDB 表
|
||||
- 静态缓存统一写入 `x-sw-source`、`x-sw-revision`、`x-sw-app-version`
|
||||
- 非 HTML 的预缓存与运行时静态请求共享同一套智能加载路径
|
||||
@@ -0,0 +1,14 @@
|
||||
# Change: 智能 CDN 优先加载
|
||||
|
||||
## Why
|
||||
当前静态资源策略为同源优先、CDN 仅在异常时兜底。该策略在发版窗口更稳，但会让大量正常流量绕过 CDN，导致已反馈的加载变慢问题。
|
||||
|
||||
## What Changes
|
||||
- 将版本化静态资源切换为 `Cache First -> 智能 CDN 优先 -> 源站快速兜底`
|
||||
- 保留 `index.html`、`version.json`、`manifest.json`、`sw.js` 等入口链路的同源优先
|
||||
- 让主线程的 CDN 探测结果同步到 Service Worker，并持久化为轻量偏好记录
|
||||
- 为静态缓存写入统一元数据，允许复用已校验的 CDN 响应
|
||||
|
||||
## Impact
|
||||
- Affected specs: `smart-cdn-loading`
|
||||
- Affected code: `apps/web/src/sw/index.ts`, `apps/web/src/sw/cdn-fallback.ts`, `apps/web/src/main.tsx`
|
||||
@@ -0,0 +1,45 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 智能 CDN 优先静态资源加载
|
||||
系统 SHALL 对版本化静态资源采用 `Cache First -> 智能 CDN 优先 -> 源站快速兜底` 的加载顺序，同时对入口链路保持同源优先。
|
||||
|
||||
#### Scenario: 版本化静态资源优先走 CDN
|
||||
- **WHEN** Service Worker 处理未命中缓存的脚本、样式、字体、图片、图标或其他版本化静态 JSON 请求
|
||||
- **THEN** 系统优先尝试健康且匹配当前版本的 CDN
|
||||
- **AND** CDN 成功返回后将结果写入静态缓存
|
||||
|
||||
#### Scenario: 入口链路保持同源优先
|
||||
- **WHEN** 请求资源为 `index.html`、导航文档、`version.json`、`manifest.json`、`sw.js` 或 `precache-manifest.json`
|
||||
- **THEN** 系统优先从当前服务器获取资源
|
||||
- **AND** 不因 CDN 偏好而改写该优先级
|
||||
|
||||
#### Scenario: CDN 在发版窗口不可用时快速回源
|
||||
- **WHEN** CDN 对当前版本静态资源返回超时、404/5xx、错误 HTML 或明显异常内容
|
||||
- **THEN** 系统快速回退到当前服务器
|
||||
- **AND** 失败的 CDN 在短时间内被降级，避免同一页面重复优先命中该 CDN
|
||||
|
||||
### Requirement: CDN 偏好同步与持久化
|
||||
系统 SHALL 将主线程探测到的 CDN 偏好同步给 Service Worker，并允许后续刷新在主线程尚未启动前复用该偏好。
|
||||
|
||||
#### Scenario: 主线程同步 CDN 偏好
|
||||
- **WHEN** 主线程已得到 CDN 探测结果
|
||||
- **THEN** 主线程发送 `SW_CDN_SET_PREFERENCE`
|
||||
- **AND** 消息体包含 `cdn`、`latency`、`timestamp`、`version`
|
||||
|
||||
#### Scenario: Service Worker 复用持久化偏好
|
||||
- **WHEN** 用户刷新页面且主线程尚未重新完成 CDN 探测
|
||||
- **THEN** Service Worker 可读取上次持久化的偏好
|
||||
- **AND** 仅在偏好版本与当前应用版本一致时作为排序依据
|
||||
|
||||
### Requirement: 已校验 CDN 缓存可复用
|
||||
系统 SHALL 允许复用已校验的 CDN 静态缓存响应，而不是将所有非源站缓存一律视为异常。
|
||||
|
||||
#### Scenario: 合法 CDN 缓存直接命中
|
||||
- **WHEN** 静态缓存项包含有效的 `x-sw-source`、`x-sw-revision`、`x-sw-app-version`
|
||||
- **AND** `x-sw-app-version` 与当前应用版本一致
|
||||
- **THEN** Service Worker 直接返回该缓存项
|
||||
|
||||
#### Scenario: 异常缓存项被清理
|
||||
- **WHEN** 缓存项缺少必需元数据、版本不匹配，或静态资源缓存实际返回 HTML 错页
|
||||
- **THEN** Service Worker 删除该缓存项
|
||||
- **AND** 重新按智能加载策略获取资源
|
||||
@@ -0,0 +1,6 @@
|
||||
## 1. Implementation
|
||||
- [x] 1.1 定义智能 CDN 优先的行为边界与缓存元数据规则
|
||||
- [x] 1.2 实现 Service Worker 中的 CDN 偏好持久化与优先级选择
|
||||
- [x] 1.3 调整运行时静态资源与预缓存的加载策略
|
||||
- [x] 1.4 同步主线程 CDN 探测结果到 Service Worker
|
||||
- [x] 1.5 增加针对 CDN 优先、回源和缓存复用的测试
|
||||
Reference in New Issue
Block a user