# CF 命令设计（ops-assistant v1）

## 目标
为 ops-assistant 提供 Cloudflare DNS 管理能力，保证幂等、安全、可审计。

---

## 1. 命令清单

- `/cf zones`
  - 列出可用 Zone（name/id）

- `/cf dnslist <zone> [name] [type]`
  - 示例：`/cf dnslist example.com`
  - 示例：`/cf dnslist example.com www A`

- `/cf dnsadd <fqdn> <ip> [--type A/AAAA/CNAME] [--ttl 120] [--proxied on/off]`
  - 示例：`/cf dnsadd test.fnos.xx.kg 1.2.3.4`

- `/cf dnsset <fqdn> <ip> [--type A/AAAA/CNAME] [--ttl 120] [--proxied on/off]`
  - 存在则更新，不存在则创建

- `/cf dnsdel <fqdn> --type <A/AAAA/CNAME>`
  - **必须带 `--type`**
  - **需二次确认 `YES`**

- `/cf dnsproxy <fqdn> on|off`
  - 仅更新 proxied

- `/cf health`
  - Token/权限可用性检查

---

## 2. 权限与安全

- `read` 角色：仅允许 `zones / dnslist / health`
- `admin` 角色：允许所有命令
- `dnsdel` 必须二次确认 `YES`

---

## 3. 参数校验

- `fqdn` 必须属于某个 Zone（`<sub>.<zone>`）
- `ip` 校验：
  - `A` → IPv4
  - `AAAA` → IPv6
- `type` 默认 `A`
- `ttl` 默认 `120`
- `proxied` 默认保持原值（仅 dnsproxy/dnsset 明确修改）

---

## 4. 幂等与更新规则

### `/cf dnsadd`
1) 查询同名同类型记录
2) 存在 → 返回“已存在”
3) 不存在 → 创建

### `/cf dnsset`
- 若任一字段不同则更新：
  - `content`
  - `ttl`
  - `proxied`
- content 相同但 ttl/proxied 不同 → 仍执行更新

### `/cf dnsdel`
- 必须带 `--type`
- 仅删除指定 type 记录

---

## 5. 输出规范

### 成功
```
✅ DNS操作成功
- name: <fqdn>
- type: <type>
- content: <ip>
- ttl: <ttl>
- proxied: <true/false>
- id: <record_id>
```

### 已存在
```
ℹ️ DNS记录已存在（未变更）
- name: <fqdn>
- type: <type>
- content: <ip>
- id: <record_id>
```

### 失败
```
❌ DNS操作失败
- reason: <鉴权/参数/CF错误>
- detail: <error_message>
```

---

## 6. 审计日志（必写）

字段：
- `ts / actor / cmd / zone / fqdn / action / record_id / result / detail`

示例：
```json
{
  "ts": "2026-03-14T15:02:10+08:00",
  "actor": "kory",
  "cmd": "/cf dnsadd test.fnos.xx.kg 1.2.3.4",
  "zone": "fnos.xx.kg",
  "record_id": "xxxxx",
  "action": "create",
  "result": "ok",
  "detail": {"type":"A","ttl":120,"proxied":false}
}
```