85 lines
3.0 KiB
Markdown
85 lines
3.0 KiB
Markdown
# COS Extension Update Design
|
|
|
|
## Goal
|
|
|
|
Use COS as the release source for extension updates. When the popup opens, it checks a public `latest.json` on COS. If the COS version is newer than the installed extension version, the popup shows an update card with download actions for the ZIP and the PDF guide, plus manual reload instructions.
|
|
|
|
## Confirmed Scope
|
|
|
|
- Update prompt appears only in the extension popup.
|
|
- No star chart page banner in this change.
|
|
- The user keeps the current manual install flow: download, unzip, replace the folder, then reload in `chrome://extensions`.
|
|
|
|
## Reusable Implementation
|
|
|
|
The current repo already has most of the flow:
|
|
|
|
- `src/shared/update-check.ts` parses the manifest and compares versions.
|
|
- `src/popup/index.ts` checks for updates when the popup boots.
|
|
- `src/popup/view.ts` renders the update status and download actions.
|
|
- `src/background/index.ts` downloads the ZIP/PDF through `chrome.downloads`.
|
|
- `scripts/write-latest-manifest.mjs` generates `release/latest.json`.
|
|
|
|
This change is mostly activation and configuration, not a rewrite.
|
|
|
|
## Manifest Contract
|
|
|
|
The public COS manifest must keep these fields:
|
|
|
|
- `latestVersion`
|
|
- `minSupportedVersion`
|
|
- `publishedAt`
|
|
- `releaseNotes`
|
|
- `zipUrl`
|
|
- `guideUrl`
|
|
|
|
Rules:
|
|
|
|
- All asset URLs must be public HTTPS URLs.
|
|
- Version comparison stays numeric dotted comparison.
|
|
- Popup logic only needs `latestVersion` to decide whether to show the update card.
|
|
- `minSupportedVersion` stays in the manifest for forward compatibility.
|
|
|
|
## COS Layout
|
|
|
|
Use a fixed release layout like:
|
|
|
|
- `https://<cos-domain>/star-chart-search-enhancer/releases/<version>/latest.json`
|
|
- `https://<cos-domain>/star-chart-search-enhancer/releases/<version>/star-chart-search-enhancer-internal.zip`
|
|
- `https://<cos-domain>/star-chart-search-enhancer/releases/<version>/星图增强插件-超简单安装使用指南.pdf`
|
|
|
|
## User Flow
|
|
|
|
1. User opens the popup.
|
|
2. Popup reads the current extension version.
|
|
3. Popup fetches COS `latest.json` with `no-store`.
|
|
4. If `latestVersion` is not newer, show “当前已是最新版本”.
|
|
5. If `latestVersion` is newer, show “发现新版本” plus release notes.
|
|
6. User clicks:
|
|
- `下载更新包` for the ZIP
|
|
- `下载使用说明` for the PDF
|
|
7. Popup shows the manual upgrade instructions after download starts.
|
|
|
|
## Error Handling
|
|
|
|
- If the manifest is missing, invalid, or unreachable, the popup should show a non-blocking update error.
|
|
- If download fails, the popup should show a download error and keep the plugin usable.
|
|
- Update check failures must not block auth or normal plugin behavior.
|
|
|
|
## Release Process
|
|
|
|
1. Build the release package.
|
|
2. Package the internal ZIP.
|
|
3. Generate `latest.json` with the real COS base URL.
|
|
4. Upload `latest.json`, the ZIP, and the PDF to the COS folder.
|
|
5. Replace the placeholder manifest URL in `src/shared/update-config.ts`.
|
|
6. Rebuild and verify the popup update card.
|
|
|
|
## Out of Scope
|
|
|
|
- Automatic in-place extension updates.
|
|
- Auto-reload after download.
|
|
- Star chart page update prompts.
|
|
- Chrome Web Store publishing.
|
|
|