model-platform/docs/项目推进/A卡运维模块-数据库外部写入协议-V0.1.md

A 卡模型运维模块数据库外部写入协议 V0.1

状态：模型方评估稿；首条接口链路按本协议准备数据 日期：2026-09-02 目标：明确模型方写入哪些表，运维平台读取哪些字段，哪些字段由运维平台自行生成

一、当前首条链路的实际数据来源

当前后端首条链路不是读取 ops_banks/ops_model_instances/ops_model_versions，而是：

1. 模型部署和版本信息从 model_deploy 库读取。
2. 月度监控批次和监控结果从 model_operations 库读取。
3. 判级、复核和处理快照从 model_operations 库读取。

因此，模型方需要先按现有部署库表写入模型基础信息，再按运维库监控源表写入月度结果。ops_banks、ops_model_instances、ops_model_versions 如继续保留，应在后续确认后再接入，不能与当前链路同时作为模型主源。

二、模型方负责写入的部署库表

2.1 model_deploy

至少需要提供：

• id：部署实例主键。
• code：业务模型 ID，建议 Workspace 内唯一。
• name：模型名称。
• modelType：模型类型。
• status：部署状态；当前接口映射为正常/下线。
• role：部署角色；陪跑状态需要与现有枚举确认。
• currentVersion：当前版本号。
• group_code：Workspace 或模型大类映射信息。
• space_id：关联 sys_project_space.id。
• gmtCreated、gmtModified：创建和最后变更时间。

2.2 model_bank

• bankNo：银行编码。
• bankName：银行名称。
• isWuji：是否无极银行。
• status：银行是否有效。

2.3 model_deploy_bank_map

• deployId：对应 model_deploy.id。
• bankNo：对应 model_bank.bankNo。
• status：关系是否有效。

2.4 model_version

• id：版本主键。
• deployId：对应部署实例。
• version：版本号。
• versionName：版本展示名称。
• isCurrent：是否当前版本。
• gmtCreated、gmtModified：版本时间。

2.5 Workspace 映射

模型部署记录至少需要满足以下一种映射：

• sys_project_space.name = 认证 Workspace 名称；
• sys_project_space.name = 认证 Workspace code；
• model_deploy.group_code = 认证 Workspace code。

最终映射方式需要模型方和运维方共同确认。

三、模型方负责写入的运维库源表

3.1 ops_monitor_batches

模型方每次生成一个月度批次，至少写入：

• batch_id：批次 ID。
• workspace_id：认证 Workspace ID。
• source_system：来源系统。
• source_batch_no：来源批次号，必须幂等。
• monitor_month：监控月份，保存为该月第一天。
• revision_no：同月修订号，从 1 开始递增。
• batch_status：先写 writing，校验完成后改为 published。
• expected_model_count、written_model_count：模型数量校验。
• feature_row_count、distribution_row_count：明细行数校验。
• checksum_sha256、generated_at、published_at。

只有 published 批次对运维页面可见。

3.2 ops_monitor_results

每个模型每个月一行，至少写入：

• monitor_result_id：结果 ID。
• workspace_id：必须与批次和认证 Workspace 一致。
• batch_id：所属批次。
• model_instance_id：建议写 model_deploy.id，以便当前接口直接关联。
• model_version_id：对应 model_version.id。
• monitor_month：监控月份。
• source_result_ref：来源结果编号，可辅助追溯。
• ranking_result：matched、unmatched 或 not_applicable。
• ks_value、psi_value：数据库保存 0～1 比率。
• sample_count、good_count、bad_count。
• source_result_json、source_calculated_at：可选追溯字段。

当前查询服务兼容用 model_deploy.id、model_deploy.code 或版本 ID 作为关联标识，但生产环境必须固定一种主规则。

3.3 ops_monitor_feature_metrics

后续特征级页面需要时写入：特征编码、名称、IV、CSI、前期值、变化率以及来源 JSON。该表不用于首条三页面链路的最低验收。

3.4 ops_monitor_distributions

后续评分分布和特征分布页面需要时写入：分箱顺序、分箱标签、基准期/当期账户数和占比、好坏账户数、坏账率、PSI/CSI 分量。该表不用于首条三页面链路的最低验收。

四、运维平台自行生成的数据

以下数据不由模型方写入：

1. A/B/C 监控结果等级。
2. 一级/二级/三级异常等级。
3. 命中原因、处理建议和阈值解释。
4. 模型团队初审、业务团队终审和默认不处理记录。
5. 报告正文、报告版本、Prompt 版本和发送状态。
6. 流程进度、材料确认、知识库索引和平台使用统计。

模型方只负责提供原始指标及其追溯信息，不能直接写入判级和处理结果字段。

五、发布协议

1. 创建 writing 批次。
2. 写入模型月度结果和后续明细。
3. 校验模型数量、结果数量、指标范围、Workspace 和关联 ID。
4. 完成校验后将批次改为 published。
5. 同月旧批次改为 superseded，不覆盖历史数据。
6. 失败批次保留 failed 状态并记录原因。

六、最小联调数据

首条链路只需要：

• 1 条有效银行。
• 1 条有效模型部署。
• 1 条有效银行关系。
• 1 条有效模型版本。
• 1 条 published 监控批次。
• 1 条对应月份的监控结果。

如果需要展示等级和处理状态，再补 1 条当前判级记录及对应复核记录。