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

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

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`，明细展示命中/回源/未缓存三态。
 
 ## 使用建议