# A 卡模型运维模块首条纵向链路联调手册 V0.1

> 状态：接口和前端调用已完成；真实非空数据到位后即可执行
> 日期：2026-09-02

## 一、联调目标

验证以下链路使用同一套模型和监控结果口径：

```text
model_deploy / model_operations
  → GET 模型列表
  → GET 模型详情
  → GET 指定月份监控结果
  → React 页面展示
```

## 二、前置条件

1. 后端已配置 `model_platform`、`model_deploy` 和 `model_operations` 三个数据库连接。
2. 前端 `VITE_OPERATIONS_API_MODE=api`。
3. 已执行数据库初始化和角色权限 SQL。
4. 已有一个可访问目标 Workspace 的登录账号。
5. 模型方按《数据库外部写入协议》提供最小非空数据。

## 三、请求顺序

以下命令中的 `<workspace_id>`、`<model_id>` 和 `<cookie>` 替换为实际值。

### 3.1 检查服务

```bash
curl -i http://127.0.0.1:8010/api/v1/health
curl -i http://127.0.0.1:8010/api/v1/operations/health
```

### 3.2 获取当前会话和权限

```bash
curl -sS \
  -H 'Cookie: access_token=<cookie>' \
  http://127.0.0.1:8010/api/v1/auth/me
```

确认返回 `role_code`、`permissions` 和目标 Workspace。

### 3.3 查询模型列表

```bash
curl -sS \
  -H 'Cookie: access_token=<cookie>' \
  'http://127.0.0.1:8010/api/v1/operations/models?workspace_id=<workspace_id>'
```

记录返回的 `model_id`、模型名称、版本和银行。

### 3.4 查询模型详情

```bash
curl -sS \
  -H 'Cookie: access_token=<cookie>' \
  'http://127.0.0.1:8010/api/v1/operations/models/<model_id>?workspace_id=<workspace_id>'
```

核对列表与详情的银行、模型名称、模型 ID、版本、KS、PSI 和排序性。

### 3.5 查询单月监控结果

```bash
curl -sS \
  -H 'Cookie: access_token=<cookie>' \
  'http://127.0.0.1:8010/api/v1/operations/models/<model_id>/monitor-results?workspace_id=<workspace_id>&month=2026-07'
```

核对详情页和单月接口的监控月份、KS、PSI、排序性、环比降幅和异常命中次数。

## 四、前端验收路径

1. 打开 `/operations/models`。
2. 从模型列表点击目标模型。
3. 进入模型监控详情。
4. 选择目标监控月份。
5. 检查页面顶部模型信息和单月监控结果。
6. 打开浏览器 Network，确认三次请求均为 `/api/v1/operations/*`，没有本地 Mock 请求。

## 五、空数据验收

在模型方数据未到位前，也应确认：

- 模型列表页面正常展示空列表，不跳转说明页。
- 工作台 KPI 卡片保留且显示 0。
- 缺表时返回明确的 `OPERATIONS_SCHEMA_NOT_READY`。
- 不存在月份返回 `MONITOR_RESULT_NOT_FOUND`，详情页面保持结构。
- 前端没有硬编码模型、银行、报告和流程示例数据。

## 六、最终验收标准

真实非空数据到位后，以下内容必须全部满足：

1. 列表返回至少 1 个模型。
2. 列表点击可以进入详情。
3. 详情可以获取指定月份结果。
4. 三个接口中的模型 ID、版本、月份、KS、PSI、排序性一致。
5. `published` 批次可见，`writing`、`failed` 和 `superseded` 批次不可作为当前结果展示。
6. 业务团队、模型团队和管理员分别通过权限验收。