# Cloud WAF — 企业 Web 防护管理平台

> Cloud WAF 是面向企业的 Web 安全防护管理平台，提供域名接入、WAF 规则、证书管理、流量分析、告警通知、CLI 自动化能力。后端 Go + Gin REST API，前端 Vue 3 SPA，CLI 工具 zcloud（Cobra 框架）。所有 REST 接口返回统一 JSON 信封 `{code, message, data}`；受保护接口支持 Bearer 会话 token 与 ApiKey 机器调用凭证双通道认证。

## 产品归属
- 平台名称：Cloud WAF
- CLI 工具：zcloud
- API 风格：REST + JSON 信封 {code, message, data}
- 认证：账号密码登录 → Bearer Token (session)；机器对接 → API Key (`Authorization: ApiKey zck_<prefix>.<secret>`)

## 5 大模块
- guard: 域名 / 策略 / 证书 / 黑白名单 / WAF / CC / ACL / 转发 / 定时计划
- sys: 用户 / 角色 / OEM / 会话 / 审计
- analytics: 概览 / 访问 / 防护 / AI / Bot / 告警 / 监测（7 子页）
- cli_release: CLI 二进制分发
- auth: 登录 / 登出

## 关键文档（人类可读）
- [快速开始](/docs/quickstart): 30 秒接入指南
- [API 文档](/docs/api): REST 接口完整索引
- [CLI 工具](/docs/cli): zcloud 命令清单
- [认证说明](/docs/auth): Bearer Token 与 API Key 双通道认证
- [示例代码](/docs/examples): curl / Python / Go
- [权限矩阵](/docs/permissions): RBAC 资源 × 动作
- [错误码总览](/docs/errors): 业务错误码完整列表（与 codes.go 一一对账）

## 机器可读端点
- OpenAPI Spec: /api/openapi.json（每个 path.<method> 节点带 `x-permissions` 数组，可直接 codegen 客户端 scope 映射）
- 文档清单: /api/docs/index.json
- 全量文档: /llms-full.txt
- Markdown 原文: /api/docs/{slug}.md（slug ∈ {quickstart,cli,api,auth,examples,permissions,errors}）
- 站点地图: /sitemap.xml

## 关键 API 端点
- GET  /api/cli/version          — 公开，CLI 版本与多平台下载链接
- GET  /api/cli/install.sh       — 公开，一行安装脚本
- GET  /api/cli/checksums.txt    — 公开，二进制 SHA256
- POST /api/auth/login           — 登录拿 Bearer Token
- POST /api/sys/api-keys         — 签发 API Key 机器调用凭证（需登录）
- POST /api/auth/logout          — 登出销毁 session
- GET  /api/sys/users            — 用户列表（需登录）
- GET  /api/guard/domains        — 域名列表（需登录）
- GET  /api/analytics/overview/kpi — 概览 KPI 图表数据（需登录，遵循 Analytics 统一调用契约）

## 多语言
- 默认语言：zh-CN
- 可用语言：zh-CN, en-US
- 切换：URL 加 `?lang=en-US` 或请求头 `Accept-Language: en-US`

## 抓取建议（给 AI agent）
1. 首选 /llms-full.txt 一次性下载全量文档
2. 需结构化时拉 /api/docs/index.json + 按需 /api/docs/{slug}.md
3. 需调用接口时拉 /api/openapi.json
4. /robots.txt 已声明全站 Allow，无 rate-limit 软门槛

## API 文档阅读规则
- `/docs/api` 前部先讲认证、JSON 信封、错误码和机器可读入口。
- 单接口详解包含 Header、参数、响应示例、权限。
- Analytics 等同构接口采用“统一调用契约 + 接口索引表 + 特殊接口展开”：表格里的路径/权限/说明需要结合该模块开头的通用 Header、Query、响应结构和 curl 模板理解。

## Analytics 调用速记
- 单图 GET 模板：`GET /api/analytics/<page>/<chart>?window=last_24h&site_id=<site_id>&top=10`，Header 使用 `Authorization: Bearer <token>` 或 `Authorization: ApiKey zck_<prefix>.<secret>`。
- Batch 模板：`POST /api/analytics/<page>/batch`，请求体形如 `{"time_window":"last_24h","charts":[{"key":"kpi"},{"key":"traffic_trend","params":{"interval":"5m"}}]}`。
- 通用查询参数：`page`、`site_id`、`domain_id`、`window`、`from`、`to`、`compare`、`top`、`order`、`granularity`；完整定义见 `/api/docs/api.md` 的 `11.1 通用查询参数`。
- D4/D7/D8/D10 是跨模块真值边界标记：D4=percentile 字段边界，D7=报表模板枚举，D8=缓存价值字段，D10=告警/风险处置闭环字段。