# 峰/谷切换提醒功能说明

dsh-cost-meter 在进入峰时/谷时计价档位**切换前**会主动提醒,帮你把高成本调用安排到谷时、避免在峰时无意识地大量消耗。提醒有**网页弹窗**与**浏览器系统通知**两条通道,中英双语,样式与位置均可配置。

## 功能一览

| 项目 | 说明 |
|---|---|
| 触发时机 | 距下一次峰/谷档位切换不足设定提前量时(默认 **2 分钟**,可配 1-30 分钟) |
| 网页弹窗 | dsh 风格提醒卡片,峰=琥珀色顶边条,谷=蓝色顶边条;位置可选**右下角 / 屏幕中心** |
| 系统通知 | 走浏览器 Web Notification API,页面最小化/切走也能收到(需授权) |
| 提醒类型 | 可只提醒进入峰、只提醒进入谷,或峰和谷都提醒(默认) |
| 频率控制 | 同一切换点只提醒一次,手动点「知道了」即记点不再打扰 |
| 语言 | 跟随插件界面语言(简体中文 / English / 跟随浏览器) |

## 网页弹窗效果

进入峰时——琥珀色警示顶边条 + 「峰价提醒」徽标:

![峰时弹窗(中文)](screenshots/peak-alert-popup-zh-peak.png)

进入谷时——蓝色信息顶边条 + 「谷价提醒」徽标:

![谷时弹窗(中文)](screenshots/peak-alert-popup-zh-offpeak.png)

英文界面下的同一弹窗(文案跟随语言设置,样式完全一致):

| 进入峰(peak alert) | 进入谷(off-peak alert) |
|---|---|
| ![Peak popup (EN)](screenshots/peak-alert-popup-en-peak.png) | ![Off-peak popup (EN)](screenshots/peak-alert-popup-en-offpeak.png) |

弹窗卡片结构:顶部**色条**标识提醒级别 → **圆点徽标**标注峰价/谷价提醒 → 标题 → 倒计时正文(「约 2 分钟 后计费档位切换为峰时价…」)→「知道了」按钮。倒计时随实际切换点动态计算,切换完成后弹窗自动消失。

## 浏览器(系统)通知效果

开启「同步发送系统通知」后,弹窗触发的同时向操作系统发一条通知——**页面最小化、浏览器在后台也能收到**:

| 中文界面 | 英文界面 |
|---|---|
| ![峰时系统通知(中文)](screenshots/peak-alert-notify-zh-peak.png) | ![Peak system notification (EN)](screenshots/peak-alert-notify-en-peak.png) |
| ![谷时系统通知(中文)](screenshots/peak-alert-notify-zh-offpeak.png) | ![Off-peak system notification (EN)](screenshots/peak-alert-notify-en-offpeak.png) |

首次开启开关时浏览器会弹出通知权限申请,请选择「允许」;若曾拒绝过,需到地址栏左侧的站点设置中手动改回允许。通知标题/正文与网页弹窗一致,预览触发的通知标题会带「(预览)」标记。

## 设置项

全部集中在 **设置 → 费用 → 峰谷计价与提示** 面板(与峰谷时段条样式设置同处):

| 设置 | 取值 | 默认 |
|---|---|---|
| 峰/谷切换弹窗提醒 | 开 / 关 | 开 |
| 提前提醒量 | 1-30 分钟 | 2 分钟 |
| 提醒类型 | 进入峰 / 进入谷 / 峰和谷 | 峰和谷 |
| 弹窗位置 | 右下角 / 屏幕中心 | 右下角 |
| 同步发送系统通知 | 开 / 关 | 关 |
| 预览弹窗 | 预览 进入峰 / 预览 进入谷 | — |

**预览弹窗**按钮直接调用真实组件渲染:文案语言、弹窗位置、系统通知全部按当前配置生效,与实际触发时完全一致,无需等到真实切换点。

## 使用建议

- **提前量**建议 2-5 分钟:太短来不及调整,太长容易遗忘;长期任务可在峰前挂起、谷时续跑
- **只关心成本高的峰时**?提醒类型设为「进入峰」,谷时(降价)不打扰
- 通知权限被拒后想再开:地址栏左侧 → 网站设置 → 通知 → 允许,再回设置页点「预览 进入峰」验证链路
- 弹窗出现在任何页面(包括无会话的欢迎页与设置页);控制台也可用 `window.cmPeakAlertPreview('peak' | 'offpeak')` 直接触发真实预览

## 相关文档

- [README](../README.md) — 功能总览
- [模型与 Plan 适配说明](model-and-plan-adaptation.md) — 峰谷计价规则与厂商价格来源