# Ops-Assistant 前端对接文档（给 Gemini）

> 目的：让前端可独立完成 ops-assistant 新后台页面，不依赖旧 xiaji 记账页面心智。  
> 基址：同源（已登录后直接请求 `/api/v1/*`）  
> 鉴权：Cookie Session（`ops_user` + `ops_token`）

---

## 0. 统一响应约定（必须）

### 成功
```json
{
  "code": "OK",
  "message": "ok",
  "data": { ... }
}
```

### 失败
```json
{
  "code": "ERR_XXX",
  "message": "可读错误信息"
}
```

### 前端统一处理建议
- `if (!res.ok)`: 显示 `message`
- `if (res.ok)`: 使用 `data`
- 不再使用 `error/status` 老字段

> 例外：`GET /api/v1/export` 成功是文件流下载，不是 JSON。

---

## 1. 权限与用户信息

### 1.1 获取当前用户
**GET** `/api/v1/me`

### data 字段
- `username`
- `role`
- `user_id`
- `permissions[]`
- `flags{}`
- `effective_capabilities{}`

### capability 常用键
- `can_view_ops`
- `can_cancel_ops`
- `can_retry_ops`
- `can_view_flags`
- `can_edit_flags`
- `can_view_channels`
- `can_edit_channels`
- `can_test_channels`
- `can_view_audit`

前端应以 capability 驱动按钮显隐。

---

## 2. Dashboard（新后台首页主数据）

### 2.1 获取总览
**GET** `/api/v1/dashboard/overview`

### 返回 data
```json
{
  "jobs": {
    "recent": [OpsJob...],
    "status_count": {
      "pending": 0,
      "running": 0,
      "success": 0,
      "failed": 0,
      "cancelled": 0
    }
  },
  "modules": [
    {"module":"cpa","enabled":true},
    {"module":"cf","enabled":false},
    {"module":"mail","enabled":false}
  ],
  "channels": [
    {"platform":"telegram","enabled":true,"status":"ok"}
  ]
}
```

### 2.2 获取轻量摘要（推荐首页首屏）
**GET** `/api/v1/dashboard/summary`

### 返回 data
```json
{
  "jobs": {
    "total": 120,
    "running": 2,
    "failed": 5,
    "success": 98
  },
  "modules": {
    "cpa": true,
    "cf": false,
    "mail": false
  }
}
```

---

## 3. 模块管理（Module Center）

### 3.1 模块列表
**GET** `/api/v1/modules`

### 返回 data
```json
{
  "modules": [
    {
      "module":"cpa",
      "display_name":"CPA 管理",
      "flag_key":"enable_module_cpa",
      "enabled":true
    }
  ]
}
```

### 3.2 切换模块开关
**POST** `/api/v1/modules/:module/toggle`

- `:module` 仅支持：`cpa|cf|mail`

### body
```json
{
  "enabled": true,
  "reason": "前端联调启用"
}
```

### 成功 data
```json
{
  "module": "cf",
  "flag_key": "enable_module_cf",
  "old": false,
  "new": true
}
```

### 交互建议
- 操作前确认弹窗
- 必填 reason
- 成功后刷新 `/api/v1/modules` 与 `/api/v1/dashboard/overview`

---

## 4. Ops 任务中心

### 4.1 任务列表
**GET** `/api/v1/ops/jobs?limit=50`

支持筛选 query：
- `status`（pending|running|success|failed|cancelled）
- `target`（如 hwsg）
- `runbook`（如 cpa_usage_backup）
- `request_id`
- `operator`（操作者 user_id，int64）
- `risk_level`（low|medium|high 等）
- `q`（模糊检索，命中 command/runbook/target/request_id）
- `from`（RFC3339，按 created_at 下界过滤）
- `to`（RFC3339，按 created_at 上界过滤）

### data
```json
{
  "jobs": [OpsJob...],
  "filters": {
    "limit": 50,
    "status": "failed",
    "target": "hwsg",
    "runbook": "cpa_usage_restore",
    "request_id": "ops-u1-1741563000",
    "operator": "1",
    "risk_level": "high",
    "q": "restore",
    "from": "2026-03-10T07:00:00+08:00",
    "to": "2026-03-10T08:00:00+08:00"
  }
}
```

### 4.2 按 request_id 反查任务
**GET** `/api/v1/ops/jobs/request/:requestID?limit=50`

### data
```json
{
  "request_id":"req-20260310-abc",
  "total": 3,
  "jobs":[OpsJob...]
}
```

### 4.3 任务详情（含步骤 + 聚合统计）
**GET** `/api/v1/ops/jobs/:id`

### data
```json
{
  "job": { ... },
  "steps": [
    {
      "step_id":"...",
      "action":"ssh.exec",
      "status":"success|failed|running",
      "stdout_tail":"...",
      "stderr_tail":"..."
    }
  ],
  "step_stats": {
    "running": 0,
    "success": 3,
    "failed": 1,
    "skipped": 0
  },
  "step_total": 4,
  "duration": {
    "job_ms": 5321,
    "steps_ms_sum": 4870
  }
}
```

### 4.4 取消任务
**POST** `/api/v1/ops/jobs/:id/cancel`

body:
```json
{"reason":"人工终止，参数配置错误"}
```

### data
```json
{"id":123,"reason":"人工终止，参数配置错误"}
```

### 4.5 重试任务
**POST** `/api/v1/ops/jobs/:id/retry`

body:
```json
{"reason":"修复配置后重试"}
```

### data
```json
{"old_job_id":123,"new_job_id":456,"reason":"修复配置后重试"}
```

### 前端权限
- cancel 按钮：`can_cancel_ops`
- retry 按钮：`can_retry_ops`

### 交互约束
- cancel/retry 必须填写 reason（后端强校验）
- retry 仅允许 failed 状态任务
- cancel 仅允许 pending/running 状态任务
- `from/to` 参数必须是 RFC3339（如 `2026-03-10T07:00:00+08:00`）

---

## 5. 通道管理（Channels）

### 5.1 通道列表
**GET** `/api/v1/admin/channels`

### data
```json
{
  "channels": [
    {
      "platform":"telegram",
      "name":"Telegram Bot",
      "enabled": true,
      "status":"ok",
      "config_json":"{}",
      "draft_config_json":"{}",
      "secrets":"{\"token\":\"***\"}",
      "draft_secrets":"{}",
      "has_draft": false
    }
  ]
}
```

### 5.2 更新草稿
**PATCH** `/api/v1/admin/channels/:platform`

body 可包含：
- `name`
- `enabled`
- `config`
- `secrets`

### 5.3 发布草稿
**POST** `/api/v1/admin/channels/:platform/publish`

### 5.4 热加载
**POST** `/api/v1/admin/channels/reload`

### 5.5 一键全禁用
**POST** `/api/v1/admin/channels/disable-all`

### 5.6 启用/禁用单通道
- **POST** `/api/v1/admin/channels/:platform/enable`
- **POST** `/api/v1/admin/channels/:platform/disable`

### 5.7 连通性测试
**POST** `/api/v1/admin/channels/:platform/test`

### 5.8 原子应用（patch + publish + reload）
**POST** `/api/v1/admin/channels/:platform/apply`

> apply 失败 message 中可能包含 stage 信息（patch/publish/reload）。

---

## 6. 审计日志

### 6.1 查询审计
**GET** `/api/v1/admin/audit`

支持 query：
- `action`
- `target_type`
- `result`
- `actor_id`
- `from` (RFC3339)
- `to` (RFC3339)
- `limit` (默认100，最大500)
- `offset`

### data
```json
{ "logs": [AuditLog...] }
```

---

## 7. 风险开关（Flags）

### 7.1 列表
**GET** `/api/v1/admin/settings/flags`

### data
```json
{ "flags": [FeatureFlag...] }
```

### 7.2 修改
**PATCH** `/api/v1/admin/settings/flags/:key`

body:
```json
{ "enabled": true, "reason": "..." }
```

> 部分 flag `RequireReason=true`，reason 为空会失败。

---

## 8. 兼容层（前端新代码不要用）

以下仅兼容旧页面：
- `GET /api/records`
- `POST /delete/:id`
- `GET /export`

新前端一律使用 `/api/v1/*`。

### 8.1 Legacy 使用统计（用于迁移观察）
**GET** `/api/v1/admin/legacy/usage`

### data
```json
{
  "summary": [
    {"route":"/api/records","count":12},
    {"route":"/delete/:id","count":3},
    {"route":"/export","count":1}
  ],
  "recent": [AuditLog...]
}
```

### 8.2 Legacy 调用趋势（按天）
**GET** `/api/v1/admin/legacy/trend?days=7`

- `days` 范围：`1~90`，默认 `7`

### data
```json
{
  "days": 7,
  "from": "2026-03-04T00:00:00+08:00",
  "trends": [
    {
      "route": "/api/records",
      "points": [
        {"day":"2026-03-04","count":2},
        {"day":"2026-03-05","count":1}
      ]
    }
  ]
}
```

### 8.3 Legacy 响应头（便于前端观察迁移）
访问旧路由时，响应头会包含：
- `X-API-Deprecated: true`
- `X-API-Replacement: <对应新路由>`
- `Warning: 299 - "legacy API deprecated, use ..."`

### 8.4 Legacy 下线就绪评估
**GET** `/api/v1/admin/legacy/readiness?days=7&zero_days=3`

- `days`：观察窗口（1~90，默认 7）
- `zero_days`：要求连续 0 调用天数（1~30，默认 3）

### data
```json
{
  "days": 7,
  "zero_days": 3,
  "window_total": 0,
  "route_totals": {
    "/api/records": 0,
    "/delete/:id": 0,
    "/export": 0
  },
  "consecutive_zero_days": {
    "/api/records": 7,
    "/delete/:id": 7,
    "/export": 7
  },
  "ready": true,
  "recommendation": "可考虑下线 legacy 路由（已满足连续0调用阈值）"
}
```

---

## 9. 前端落地建议（给 Gemini）

1. 建立统一 `apiClient`：
   - `request(url, options)`
   - 自动解析 `{code,message,data}`
   - 非 2xx 抛 message

2. 页面优先级：
   - P1：Dashboard（overview + summary）
   - P1：Ops Jobs
   - P1：Modules
   - P2：Channels
   - P2：Audit

3. 权限驱动 UI：
   - 所有按钮显隐由 `effective_capabilities` 控制

4. 状态刷新策略：
   - dashboard 每 10~20s 轮询
   - ops jobs running 状态 5~10s 轮询

5. 错误展示：
   - toast + message 文本
   - 不展示后端堆栈

---

## 10. 已知限制

- export 成功仍为文件流（设计如此）。
- gojieba 编译 warning 可忽略（非功能错误）。