model-platform/docs/项目推进/A卡运维模块-本周目标完成情况-V0.1.md

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. 设计文档与实现状态未同步：现有架构 V0.2 仍写着“接口尚未实现”，需要新版本勘误。

四、现在可以先写的文档

以下内容不依赖全部业务功能完成，可以立即起草：

1. 技术架构与实现说明 V0.3：以当前双数据库、FastAPI、React 和真实接口代码为准，标出已实现/待实现边界。
2. 数据库模型与外部写入协议 V0.2：列出模型方需要写入的表、字段、写入时机、批次状态、幂等和发布规则。
3. 运维 API 清单 V0.1：先固化已实现的 5 个接口，再把后续接口标为规划项。
4. 三角色登录/RBAC 验收说明 V0.1：列出角色、菜单、页面、接口和写操作验收项。
5. 首条纵向链路联调手册 V0.1：写清测试数据准备、请求顺序、预期响应和数值核对点。
6. 本周目标验收记录 V0.1：等模型方提供非空数据后，直接补充实际请求和截图结果。

五、建议本周剩余顺序

1. 先让模型方补一套最小非空数据，不等待全部页面完成。
2. 先完成列表—详情—单月结果的真实联调和数值核对。
3. 同时用三种角色做登录、菜单和接口权限验收。
4. 根据联调结果更新架构 V0.3、数据库外部写入协议 V0.2 和 API 清单 V0.1。
5. 最后再扩展工作台、监控明细、报告和流程等页面的接口。

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

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

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