# A 卡模型运维模块后端架构与数据库设计 V0.3

> 状态：工程实现基线；首条接口链路已实现，真实非空数据联调和三角色验收待完成
> 日期：2026-09-02
> 依据：当前 `feature/a-card-operations` 代码、`origin/develop` 基础工程、现有三库结构和当前运维前端原型

## 1. 本版本结论

本版本将 V0.2 设计稿与当前代码实现对齐，作为本周开发和联调基线。

1. 同一工程内继续保留平台能力和运维能力，不拆分微服务。
2. 登录、Workspace 和平台级 RBAC 继续复用 `model_platform`。
3. 模型部署、银行、模型版本的首条查询链路当前读取 `model_deploy`。
4. 月度监控结果、判级和复核快照当前读取 `model_operations`。
5. React 运维页面已切换为真实 API；没有数据时保留页面结构并显示 0、— 或空列表。
6. 当前已经完成接口代码、空数据验证和前端纵向调用；尚未用非空业务数据完成端到端验收。

## 2. 总体架构

```text
浏览器
  │ 同源请求 /api/v1/*
  ▼
Nginx / Vite 代理
  ▼
FastAPI
  ├─ 平台上下文：model_platform
  │    ├─ 登录、Cookie、用户、角色、权限、Workspace
  │    └─ 平台已有脚本、对象存储和调度能力
  ├─ 模型来源查询：model_deploy（只读）
  │    ├─ model_deploy
  │    ├─ model_bank
  │    ├─ model_deploy_bank_map
  │    ├─ model_version
  │    └─ sys_project_space
  └─ 运维数据查询/写入：model_operations
       ├─ ops_monitor_batches
       ├─ ops_monitor_results
       ├─ ops_monitor_evaluations
       ├─ ops_monitor_reviews
       └─ 后续报告、流程、知识库、配置和 Outbox
```

当前工作区代码目录：

- `backend/src/backend/api/operations/`：运维 API、Workspace/角色依赖和健康检查。
- `backend/src/backend/services/operations/deploy_model_queries.py`：跨 `model_deploy` 与 `model_operations` 的首条模型查询服务。
- `backend/src/backend/services/operations/workbench_queries.py`：工作台聚合查询。
- `frontend/app/services/operationsApi.ts`：运维 API 请求和 DTO 转换。
- `frontend/app/features/operations/OperationsDataContext.tsx`：统一加载真实接口数据并处理空数据。
- `frontend/app/features/operations/`：运维页面和展示组件。

## 3. 数据责任边界

### 3.1 平台库 `model_platform`

由现有平台和权限模块负责。运维模块只复用登录和 Workspace 上下文，不创建新的账号或 RBAC 表。

- 用户、角色、权限和 Workspace：现有认证/系统管理模块维护。
- `password_hash`：运维模块禁止读取。
- 运维页面的登录角色只使用统一认证返回的 `role_code`。

### 3.2 模型库 `model_deploy`

首条链路作为模型来源库只读查询。模型方负责维护：

- 银行：`model_bank`。
- 模型部署实例：`model_deploy`。
- 模型与银行关系：`model_deploy_bank_map`。
- 模型版本：`model_version`。
- Workspace/项目空间映射：`sys_project_space` 或 `deploy.group_code`。

### 3.3 运维库 `model_operations`

监控和运维模块维护：

- 月度批次、原始监控结果、特征指标和分布。
- 判级快照、模型团队初审、业务团队终审。
- 报告、流程、文档、Prompt、规则、配置、使用统计和 Outbox。

## 4. 当前首条真实接口链路

### 4.1 模型列表

`GET /api/v1/operations/models?workspace_id=<workspace_id>`

后端先从 `model_deploy` 查询模型、银行、版本和 Workspace 映射，再从 `model_operations` 查询最新已发布监控结果和当前判级，最后组装前端 DTO。

### 4.2 模型详情

`GET /api/v1/operations/models/{model_id}?workspace_id=<workspace_id>`

按 `deploy.code` 或部署 ID 识别模型，返回与模型列表相同的数据口径，避免列表和详情出现两套计算结果。

### 4.3 单月监控结果

`GET /api/v1/operations/models/{model_id}/monitor-results?month=YYYY-MM&workspace_id=<workspace_id>`

只读取 `batch_status='published'` 的批次，并按监控月份和修订号取当前结果。月份不存在或模型没有该月结果时返回业务层的“结果不存在”，前端保持详情页面结构。

### 4.4 结果关联要求

`ops_monitor_results` 需要能与 `model_deploy` 的部署行关联。当前查询服务支持以下任一关联标识：

- `model_instance_id = model_deploy.id`；
- `source_result_ref = model_deploy.code`；
- `source_result_ref = model_deploy.id`；
- 版本标识与 `model_version.id` 对应。

如果模型方采用其他来源 ID，需要在写入协议中明确映射，不能让前端自行猜测。

## 5. 当前 API 实现状态

已经实现：

1. `GET /api/v1/operations/health`
2. `GET /api/v1/operations/models`
3. `GET /api/v1/operations/models/{model_id}`
4. `GET /api/v1/operations/models/{model_id}/monitor-results`
5. `GET /api/v1/operations/workbench`

尚未实现的后续 API 包括模型大类汇总、银行汇总、监控明细筛选、特征分布、处理复核、报告、流程、知识库、规则、Prompt 和系统配置写接口。

## 6. 登录与 RBAC

- 登录继续使用现有 `/api/v1/auth/login` 和 Cookie 会话。
- `/api/v1/auth/me` 返回当前用户、Workspace、`role_code` 和权限集合。
- 前端将 `admin` 映射为管理员，将 `developer/model_team` 映射为模型团队，将 `business/business_team/biz` 映射为业务团队。
- 运维查询接口使用 `operations_context` 校验登录状态和 Workspace 访问范围。
- 平台用户、角色、权限接口继续使用现有 `system_admin_context`，不由运维模块重新实现。
- 前端隐藏菜单只负责展示，服务端仍必须对写接口进行授权校验。

## 7. 当前缺口与决策项

1. **表模型口径尚未完全统一**：V0.2 设计过 `ops_banks/ops_model_instances/ops_model_versions` 作为模型方外部写入表，但当前首条接口实际查询的是 `model_deploy` 及其关联表。需要模型方确认最终以哪套表为主，并在确认后统一代码、DDL和文档。
2. **非空数据缺口**：当前联调库模型和监控结果为空，尚未完成非空链路验收。
3. **Workspace 映射缺口**：需要确认 `sys_project_space.name`、`sys_project_space.id`、`deploy.group_code` 与认证 Workspace 的最终映射。
4. **监控结果关联缺口**：需要确认 `model_instance_id/model_version_id/source_result_ref` 的来源 ID 规则。
5. **三角色验收缺口**：需要准备三个真实账号并完成菜单、页面、查询和写操作验收。
6. **完整 API 文档缺口**：当前接口已注册，但请求/响应/错误码尚未形成独立对外清单。

## 8. 本周验收口径

本周目标只有在以下条件全部满足后才可标记完成：

1. 架构、数据库、API 和工程骨架文档与当前代码一致。
2. 三角色可以登录，角色展示和基础访问边界正确。
3. 模型方提供最小非空数据。
4. 列表、详情、单月结果三次请求成功。
5. 三个页面的模型、版本、月份、排序性、KS、PSI 等字段一致。
6. 空数据、无结果、不存在模型、无权限和跨 Workspace 请求均有明确结果。