model-platform/docs/architecture/A卡模型运维模块-后端架构与数据库设计-V0.3.md

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. 总体架构

浏览器
  │ 同源请求 /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 请求均有明确结果。