Merge pull request #1076 from flashcatcloud/feat/statuspage-widget-generated-at

docs(statuspage): widget summary.json field and caching corrections

Author: ysyneu

en/on-call/statuspage/widgets.mdx

@@ -128,7 +128,7 @@ GET {status page URL}/api/widget/v1/summary.json
 
 - **Public access**: no authentication, no API key
 - **Cross-origin**: responses carry `Access-Control-Allow-Origin: *`, so browsers can call it directly; `GET`, `HEAD`, and `OPTIONS` (preflight) are supported
-- **Caching**: responses include `Cache-Control: public, max-age=30, s-maxage=30, stale-while-revalidate=120, stale-if-error=3600` and an `ETag` — send `If-None-Match` and receive `304` when nothing changed
+- **Caching**: responses include `Cache-Control: no-cache`, so browsers revalidate with the server before each use, and an `ETag` — send `If-None-Match` and receive `304` when nothing changed
 - **Freshness**: the `X-Status-Validated-At` response header records when the snapshot was last successfully validated; use it to judge whether data is stale
 
 <Warning>
@@ -142,7 +142,7 @@ The response is a single JSON object whose `schema_version` is currently fixed a
 | Field | Type | Description |
 | --- | --- | --- |
 | `schema_version` | string | Schema version, currently `"1.0"` |
-| `generated_at` | string | Data version timestamp (ISO 8601); only advances when the data changes |
+| `generated_at` | string | Data version identifier (ISO 8601 timestamp). Not guaranteed to increase: it can move back, for example when an incident resolves, and it doesn't change on every data change. Don't compare values for ordering; use `ETag` to detect changes |
 | `poll_after_seconds` | number | Suggested polling interval in seconds, currently `30` |
 | `max_stale_seconds` | number | Freshness window in seconds; treat data as stale beyond this, currently `120` |
 | `page` | object | Status page info: `name`, `url` |

zh/on-call/statuspage/widgets.mdx

@@ -128,7 +128,7 @@ GET {状态页地址}/api/widget/v1/summary.json
 
 - **公开访问**：无需鉴权、无需 API Key
 - **跨域**：响应携带 `Access-Control-Allow-Origin: *`，浏览器可直接调用；支持 `GET`、`HEAD` 与 `OPTIONS`（预检）
-- **缓存**：响应头 `Cache-Control: public, max-age=30, s-maxage=30, stale-while-revalidate=120, stale-if-error=3600`，并返回 `ETag`——携带 `If-None-Match` 且数据未变化时返回 `304`
+- **缓存**：响应头 `Cache-Control: no-cache`，浏览器每次使用前都要向服务端重新校验；响应同时返回 `ETag`，携带 `If-None-Match` 且数据未变化时返回 `304`
 - **时效**：响应头 `X-Status-Validated-At` 表示快照最近一次成功校验的时间，可据此判断数据是否过期
 
 <Warning>
@@ -142,7 +142,7 @@ GET {状态页地址}/api/widget/v1/summary.json
 | 字段 | 类型 | 说明 |
 | --- | --- | --- |
 | `schema_version` | string | 数据结构版本，当前为 `"1.0"` |
-| `generated_at` | string | 快照的数据版本时间（ISO 8601），数据有变化才会更新 |
+| `generated_at` | string | 数据版本标识（ISO 8601 时间）。不保证递增，例如故障恢复后可能回到更早的时间；数据变化时也不一定更新。请勿比较先后，判断数据是否变化请使用 `ETag` |
 | `poll_after_seconds` | number | 建议的轮询间隔（秒），当前为 `30` |
 | `max_stale_seconds` | number | 数据保鲜期（秒），超过未校验成功应视为过期，当前为 `120` |
 | `page` | object | 状态页信息：`name`（名称）、`url`（地址） |