feat(access-logs): 上报并展示边缘缓存状态 cache_status

OpenResty 日志输出 $upstream_cache_status；Agent/协议/ClickHouse 贯通入库。
明细列表与详情按 HIT/MISS 等推导命中、回源、未缓存三态标签。

docs/changelog/index.md

@@ -28,6 +28,7 @@ sidebar: false
 - 边缘访问日志现支持上报并存储 User-Agent；概览新增设备类型饼图，以及浏览器、操作系统、User-Agent 排行。
 - 访问日志明细支持查看单条请求详情，可查看 User-Agent、IP 访问趋势与分析，并快捷将 IP 加入或移出 IP 组。
 - 访问日志页签状态改为 URL 参数记忆，筛选后不会再跳回概览。
+- 访问日志支持边缘缓存状态（`cache_status`）：明细列表与详情可查看命中 / 回源 / 未缓存。
 - 优化访问日志概览的设备类型与状态码饼图布局，使设备类型与状态码饼图在 1024px（lg）以上屏幕保持双列并排展示，提升页面紧凑度。
 - 修复访问日志概览在 ClickHouse 查询发生错误时静默吞掉报错的缺陷，引入错误日志输出，方便定位问题。
 

docs/docs.go

@@ -14390,6 +14390,10 @@ const docTemplate = `{
                     "description": "body bytes = 已提供数据",
                     "type": "integer"
                 },
+                "cache_status": {
+                    "description": "$upstream_cache_status",
+                    "type": "string"
+                },
                 "host": {
                     "type": "string"
                 },
@@ -16511,6 +16515,9 @@ const docTemplate = `{
         "observability.AccessLogView": {
             "type": "object",
             "properties": {
+                "cache_status": {
+                    "type": "string"
+                },
                 "host": {
                     "type": "string"
                 },

docs/plan/20260718-access-log-cache-status.md

@@ -0,0 +1,62 @@
+# 访问日志 cache_status 明细可见 — 实现计划
+
+说明：对应设计 [observability-data-model.md §3.5.1](../design/observability-data-model.md)。第一期只做明细可见，不上报 upstream 地址。
+
+---
+
+## 1. 目标与背景
+
+* **需求背景**：访问日志无法判断请求是否命中边缘缓存、是否回源。
+* **开发范围 (Scope)**：
+  * **必做**：OpenResty 日志输出 `$upstream_cache_status`；Agent 上报；CH 入库；列表/详情展示三态标签。
+  * **Out of Scope**：命中率看板、hourly 维度、`upstream_addr`。
+
+---
+
+## 2. 设计与决策
+
+* **唯一字段**：`cache_status` string（原始值）。
+* **UI 三态（不落库）**：
+  * 命中：`HIT` / `STALE` / `REVALIDATED` / `UPDATING`
+  * 回源：`MISS` / `EXPIRED`
+  * 未缓存：`BYPASS` / `-` / 空
+* **数据流**：log_format → Agent parse → protocol → Server model → CH → API → 前端明细。
+
+---
+
+## 3. 修改清单
+
+### 边缘 / 协议
+
+* `pkg/render/openresty/types.go`、`internal/model/openflare_option.go`：`log_format` 增加 `cache_status`
+* `internal/apps/agent/observability/traffic.go`：解析与映射
+* `pkg/protocol/agent.go`：`NodeAccessLog.CacheStatus`
+
+### Server / CH
+
+* goose：`202607180005_access_log_cache_status.sql`
+* `internal/model/analytics/node_access_log.go`、writer、list/scan、store 映射
+* `internal/model/openflare_observability.go`、agent build records
+* API `AccessLogView` + list 响应带 `cache_status`
+
+### 前端
+
+* types / 明细列表标签 / 详情字段
+* 三态 helper：`resolveCacheOutcome(cache_status)`
+
+---
+
+## 4. 验证
+
+* `go test ./internal/apps/agent/observability/ ./internal/repository/analytics/ ./internal/apps/openflare/agent/`
+* `make swagger`（若 Handler 响应结构变更）
+* `make code-check` / `make prettier`
+
+---
+
+## 5. 落地进度
+
+* [x] log_format + protocol + agent parse
+* [x] CH migration + 写入/读取
+* [x] API + 前端明细展示
+* [ ] 测试与提交

docs/plan/index.md

@@ -16,6 +16,7 @@
 * [Zone 与域名资源重构](./20260712-zone-domain-refactor.md)：以 Zone 和正规化 Zone 域名替代托管域名及反代路由中的域名/证书冗余字段。
 * [WAF 可编排规则](./20260713-waf-orchestration.md)：使用 React Flow 编辑 DAG 规则，发布时编译并由 OpenResty 纯内存执行。
 * [边缘可观测与业务流量统计重构](./20260717-observability-redesign.md)：访问日志为业务唯一真相；Agent 只上报明细与主机读数；收敛「出站/已提供」双字段。
+* [访问日志 cache_status 明细可见](./20260718-access-log-cache-status.md)：上报 `$upstream_cache_status`，明细展示命中/回源/未缓存三态。
 
 ## 使用建议
 

docs/swagger.json

@@ -14383,6 +14383,10 @@
                     "description": "body bytes = 已提供数据",
                     "type": "integer"
                 },
+                "cache_status": {
+                    "description": "$upstream_cache_status",
+                    "type": "string"
+                },
                 "host": {
                     "type": "string"
                 },
@@ -16504,6 +16508,9 @@
         "observability.AccessLogView": {
             "type": "object",
             "properties": {
+                "cache_status": {
+                    "type": "string"
+                },
                 "host": {
                     "type": "string"
                 },

docs/swagger.yaml

@@ -657,6 +657,9 @@ definitions:
       bytes_sent:
         description: body bytes = 已提供数据
         type: integer
+      cache_status:
+        description: $upstream_cache_status
+        type: string
       host:
         type: string
       logged_at_unix:
@@ -2065,6 +2068,8 @@ definitions:
     type: object
   observability.AccessLogView:
     properties:
+      cache_status:
+        type: string
       host:
         type: string
       id: