郑龙捷
74dd97428f
- 新增 model_deploy 与 model_operations 双库查询，支持模型列表、模型详情、单月监控结果和运维工作台真实接口。 - 关闭运维模块生产 Mock 数据，补充缺表/空数据降级、工作台空状态和首条纵向链路测试。 - 按业务团队、模型团队、管理员权限矩阵接入菜单、页面、操作按钮和后端接口权限校验，支持 business_team 角色。 - 更新工作台布局、深色欢迎卡片、全宽页面适配、顶部回退，以及权限分组展示。 - 新增架构实现基线、周目标完成情况和角色权限矩阵初始化 SQL 文档。
152 lines
7.2 KiB
Markdown
152 lines
7.2 KiB
Markdown
# 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 请求均有明确结果。
|