init: ops-assistant codebase

docs/cf-commands-design.md

@@ -0,0 +1,123 @@
+# 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}
+}
+```