# A 卡模型运维模块：本周目标完成情况

> 版本：V0.1
> 日期：2026-09-02
> 用途：内部开发推进、联调和周目标验收基线

## 一、结论

本周目标目前属于“工程基础已具备，真实非空数据验收未完成”。

技术架构、数据库设计初稿、前后端工程骨架和首条接口代码已经形成；登录与角色适配能力已有基础；“模型列表—模型详情—单月监控结果”三条接口也已经接入前端真实请求。

当前不能直接宣称本周目标全部完成，主要原因是联调数据库中的模型、版本和监控结果目前没有非空业务数据。因此现在验证到的是接口注册、响应结构、空数据降级和前端调用链路，还没有验证真实业务数据下的完整页面展示及数值一致性。

## 二、目标逐项状态

### 1. 技术架构

状态：已完成初稿，进入实现校准阶段。

已具备：

1. 同一工程、平台库与运维库双数据库边界。
2. `model_platform` 作为现有认证、Workspace、平台基础能力来源。
3. `model_deploy` 作为模型部署、银行、版本等模型侧数据来源。
4. `model_operations` 作为监控结果和运维业务数据来源。
5. FastAPI、React、MySQL、对象存储和后续 Outbox/队列的职责边界。
6. 架构图、数据域关系图和数据库设计稿。

仍需补齐：

1. 把设计稿中的“计划实现”与当前已经实现的真实代码逐项对齐。
2. 明确模型方写入 `model_deploy`、`model_operations` 的最终字段及批次协议。
3. 补充部署环境的连接配置、账号权限和回滚方式。

### 2. 数据库模型初稿

状态：DDL 和表关系初稿已完成，等待 DBA/模型方确认和非空数据验证。

已具备：

1. `model_operations` 建库建表脚本及校验脚本。
2. 模型、版本、监控批次、监控结果、特征指标、分布、判级、复核、报告、流程和 Outbox 等表的初稿。
3. 页面—表—数据责任关系说明。
4. 模型方外部写入表的范围说明。

仍需补齐：

1. 确认 `model_deploy` 和 `model_operations` 的实际表结构与字段类型。
2. 确认银行表最终来源；当前银行主数据仍待模型方补充确认。
3. DBA 执行建库/授权，或确认现有表已满足接口查询。
4. 由模型方提供一组可追溯的非空测试数据。
5. 对模型、版本、监控月份、修订号和发布状态补充唯一性与幂等约束。

### 3. API 清单

状态：首条链路接口已实现，独立 API 清单已完成初稿。

当前已注册并可从 OpenAPI 查到：

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?month=YYYY-MM`
5. `GET /api/v1/operations/workbench`

仍需补齐：

1. 将运维接口从通用 `API.md` 中拆出独立清单。
2. 补充每个接口的请求参数、响应字段、状态码、错误码和权限要求。
3. 明确百分比单位、月份格式、空值规则和分页规则。
4. 增加模型大类、银行概览、监控明细、报告、流程、知识库和配置接口清单。

### 4. 前后端工程骨架

状态：已完成首期骨架。

已具备：

1. FastAPI 运维路由、依赖、服务和查询层目录。
2. React 运维路由、数据上下文、API service 和页面骨架。
3. 前端运维模块已关闭生产 Mock 数据，统一请求后端接口。
4. 缺少真实数据时，页面保留结构并显示 0、— 或空列表。
5. 5173 当前功能分支和 5174 `develop` 对照环境均可独立启动。

仍需补齐：

1. 其余页面从占位/空状态逐步接入后端资源接口。
2. 报告、流程、处理、导出和配置等写操作接口。
3. 前端统一处理接口错误、权限不足、空数据和加载状态。
4. CI 中固定执行前端 typecheck/build 和后端测试。

### 5. 三角色登录与 RBAC 基础能力

状态：登录、角色适配、权限读取和前后端基础校验已完成，三角色真实账号验收未完成。

已具备：

1. 继续复用现有登录接口和 Cookie 会话。
2. 登录返回 `role_code`、用户信息、Workspace 和权限集合。
3. 前端可区分业务团队、模型团队和管理员。
4. 系统管理的用户、角色、项目等既有功能继续复用。
5. 运维 API 使用 Workspace 访问校验和角色映射。

仍需补齐：

1. 分别使用业务团队、模型团队、管理员账号完成登录验收。
2. 验证三种角色的菜单可见范围、页面可见范围和按钮可见范围。
3. 验证后端不能仅依赖前端隐藏按钮，而是对写接口再次进行角色校验。
4. 明确运维模块与既有权限模块的最终责任边界。

### 6. 首条真实接口纵向链路

状态：代码链路已跑通，真实非空业务链路未验收。

目标链路：

`model_deploy / model_operations` 数据 → 后端模型查询 → 模型列表 → 模型详情 → 单月监控结果 → 前端详情展示。

已验证：

1. 三个接口已注册。
2. 前端已从 Mock 切换为真实 API 请求。
3. 缺表时后端可降级为空数据，页面不再跳转到说明页。
4. 空库时列表、工作台和相关页面能够保留结构并显示空状态。
5. 前端类型检查和生产构建通过。

未完成：

1. 模型方写入至少 1 个银行、1 个模型、1 个版本和 1 个月监控结果。
2. 使用登录会话从列表点击进入详情。
3. 从详情进入指定月份监控结果。
4. 核对列表、详情和监控结果中的模型名称、版本、KS、PSI、排序性和处理状态一致。
5. 验证不同 Workspace、无权限和不存在模型的返回结果。

## 三、当前最关键的三个缺口

1. **没有非空真实数据**：这是首条纵向链路还不能验收的首要原因。
2. **三角色没有完成真实账号矩阵验收**：现有代码具备基础，但还没有形成可签字的验收记录。
3. **三角色真实账号验收**：权限代码和 SQL 已准备完成，还需要用业务、模型和管理员账号实际验证菜单、页面、按钮和接口。

## 四、现在可以先写的文档

以下内容已先完成初稿，不依赖真实非空数据：

1. **技术架构与实现说明 V0.3**：已完成，标出当前双数据库、FastAPI、React 和真实接口边界。
2. **数据库外部写入协议 V0.1**：已完成，列出模型方写入表、字段、批次发布和关联要求。
3. **运维 API 清单 V0.1**：已完成，固化已实现的 5 个接口并列出规划接口。
4. **三角色登录/RBAC 验收说明 V0.1**：已完成，列出角色、菜单、页面、接口和操作验收项。
5. **首条纵向链路联调手册 V0.1**：已完成，写清测试数据、请求顺序、预期响应和核对点。
6. **本周目标验收记录 V0.1**：已完成基线，待非空数据后补实际请求和截图结果。

## 五、建议本周剩余顺序

1. 先让模型方补一套最小非空数据，不等待全部页面完成。
2. 先完成列表—详情—单月结果的真实联调和数值核对。
3. 同时用三种角色做登录、菜单和接口权限验收。
4. 根据联调结果补充本周目标验收记录，不再重复调整已冻结的基础文档。
5. 在首条链路验收后扩展工作台、监控明细、报告和流程等页面的接口。

## 六、当前不可对外承诺的内容

在非空数据和三角色验收完成前，不建议对外表述为“首条真实接口链路已完整跑通”。更准确的表述是：

> 已完成首条真实接口链路的工程实现、接口注册、前端接入和空数据验证；待模型方提供最小非空数据后完成业务数据联调验收。