# A 卡模型运维模块运维 API 清单 V0.1

> 状态：首条真实接口链路已实现；其余业务接口列为后续实现项
> 日期：2026-09-02
> 鉴权：复用登录 Cookie；需要 Workspace 的接口必须传 `workspace_id`

## 一、统一约定

1. 浏览器请求使用同源 `/api/v1/*`，Cookie 由浏览器自动携带。
2. 成功响应统一使用 `{ request_id, data, meta }` 包装。
3. `workspace_id` 为 26 位 Workspace ID；后端同时校验登录身份、Workspace 成员关系和运维权限。
4. 月份参数格式固定为 `YYYY-MM`，数据库月份使用当月第一天保存。
5. 数据库中的 KS、PSI、IV、CSI 等比率按 0～1 保存，API 返回前端展示百分数。
6. 没有数据时返回空数组或业务层空结果，不使用演示数据填充页面。

## 二、已实现接口

### 2.1 运维健康检查

`GET /api/v1/operations/health`

- 用途：检查运维库、部署只读库和关键表状态。
- 鉴权：服务健康检查接口，是否要求登录以部署配置为准。
- 返回：服务状态、数据库状态、关键表检查结果。

### 2.2 模型列表

`GET /api/v1/operations/models`

查询参数：

- `workspace_id`：必填。
- `bank`：可选，银行名称。
- `category`：可选，`std`、`bai`、`big`、`afd`。
- `status`：可选，模型状态。
- `keyword`：可选，匹配银行、模型名称、模型 ID 或版本。

权限：`operations:model-overview:view`。

数据来源：

- `model_deploy.model_deploy`
- `model_deploy.model_bank`
- `model_deploy.model_deploy_bank_map`
- `model_deploy.model_version`
- `model_operations.ops_monitor_batches`
- `model_operations.ops_monitor_results`
- 当前判级和处理快照表（存在时读取）

返回字段包括：银行、模型大类、模型名称、模型 ID、模型版本、模型状态、最近迭代日期、排序性、KS、PSI、KS 环比降幅、异常命中次数、最近处理日期和历史处理建议。

### 2.3 模型详情

`GET /api/v1/operations/models/{model_id}`

查询参数：

- `workspace_id`：必填。

权限：`operations:monitoring-detail:view`。

模型 ID 当前支持使用 `model_deploy.code`；后端同时兼容部署表主键和版本关联标识。模型不存在返回：

```json
{
  "detail": {
    "code": "MODEL_NOT_FOUND",
    "message": "模型不存在"
  }
}
```

### 2.4 单月监控结果

`GET /api/v1/operations/models/{model_id}/monitor-results`

查询参数：

- `workspace_id`：必填。
- `month`：必填，格式 `YYYY-MM`。

权限：`operations:monitoring-detail:view`。

返回字段：模型实例 ID、监控月份、排序性、KS、PSI、KS 环比降幅和近 6 个月二级异常命中次数。

错误码：

- `INVALID_MONITOR_MONTH`：月份格式不正确。
- `MODEL_NOT_FOUND`：模型不存在。
- `MONITOR_RESULT_NOT_FOUND`：该月份没有已发布监控结果。
- `OPERATIONS_SCHEMA_NOT_READY`：关键数据表未完成初始化。

### 2.5 运维工作台

`GET /api/v1/operations/workbench`

查询参数：

- `workspace_id`：必填。

权限：`operations:workbench:view`。

返回工作台的提醒、KPI、我的待办、我的关注和最近动态。空数据时各数组为空，KPI 数值为 0。

## 三、权限与页面映射

- `operations:workbench:view`：运维工作台。
- `operations:usage:view`：平台使用统计。
- `operations:model-overview:view`：模型大类概览。
- `operations:bank-overview:view`：细分银行概览。
- `operations:deployed-models:view`：已上线模型详情。
- `operations:monitoring-overview:view`：模型监控概览/监控明细。
- `operations:monitoring-detail:view`：模型监控详情。
- `operations:report:view`、`operations:report:edit`、`operations:report:export`、`operations:report:send`：监控诊断报告。
- `operations:report-summary:view`：历史报告汇总。
- `operations:workflow:view`：全流程进度。
- `operations:knowledge:view`：文档知识库。
- `operations:rules:view`、`operations:rules:publish`、`operations:rules:rollback`、`operations:rules:simulate`：监控等级规则。
- `operations:prompt:view`、`operations:prompt:edit`、`operations:prompt:regression`：报告 Prompt 管理。
- `operations:settings:view`：运维系统配置。

## 四、规划接口

后续按页面逐步实现：

1. 模型大类和银行概览查询接口。
2. 监控明细多条件筛选、特征指标和评分分布接口。
3. 模型团队初审、业务团队终审和默认不处理接口。
4. 报告生成、编辑、发送、历史汇总和文件导出接口。
5. 流程、阶段材料、知识库、规则、Prompt 和系统配置接口。

规划接口必须沿用本文件的鉴权、Workspace、错误码、空数据和百分比单位约定。