07 模型运行与回测端到端实现任务

执行要求：直接完成“模型运行与回测”只读治理页面。训练、回测和模型发布由调度链执行；HTTP 请求只展示运行、版本和已发布评估证据。

共同门禁：不执行数据库草案，不修改 V1，不 DROP/清库或插入客户测试数据；g5b2-mysql 仅用于 SHOW、SELECT 和 EXPLAIN。接口统一使用 X-Trace-Id，缺失时后端生成并写响应头；同一动作的前端日志、后端日志和错误响应必须同值。

1. 目标与完成判定

• 菜单：智能研判 / 模型运行与回测，仅 ROLE_ADMIN。
• 路由：/forecast/models。
• 支持按 CGI、metricCode、模型类型、运行/验证状态和时间范围筛选训练运行与模型版本，服务端分页和稳定排序。
• 展示训练范围/截止、样本数、完整率、特征覆盖、缺失特征、运行状态/失败原因、模型/特征版本、验证状态、MAE/RMSE/WAPE、发布时间和发布运行号。
• 选择运行后分页查看逐点回测证据。

2. 开工前必读与现状核对

1. 设置 PowerShell UTF-8，阅读仓库门禁、需求 V2.0 第 5.2.2 节、数据库设计第 9.4/10/12 节及模型/回测 DDL。
2. 阅读 ModelGovernancePage、types、api/http、PageFeedback、AppShell 和权限处理。
3. 阅读 modelState/modelRuns/backtest Controller/Service/Mapper/XML、DTO 和授权测试。
4. 用 rg 查找 modelRuns、publishedModelCount、backtestPoints 的全部调用方。
5. 当前已有三个 GET 接口，但列表未分页，且必须核对所有接口是否统一 ROLE_ADMIN。

3. 现有接口基线

能力	当前接口	必补项
模型状态	GET /api/v1/forecast/models/state	ROLE_ADMIN、稳定状态和原因
运行/版本列表	GET /api/v1/forecast/models	服务端分页、筛选、真实 total
逐点回测	GET /api/v1/forecast/models/{modelRunNo}/backtest	分页、稳定排序、PUBLISHED 评估限制

4. 业务规则与降级

• 页面可以读取训练/调度运行状态用于治理，但任何预测值和回测结论只能来自 PUBLISHED 评估结果；不得查询 STAGED 结果冒充可用模型。
• 模型粒度为 CGI+metricCode；同一对象只有一个当前 PUBLISHED 且 validationStatus=PASSED 的模型。
• MAE、RMSE、WAPE 由 JOB_FORECAST_EVALUATION 计算并发布；同步请求不重算。
• 逐点只使用 MATCHED 有效预测/实际对；无实际值或无预测值保留 pointStatus 和 N/A 原因。
• WAPE 分母为 0 时返回 N/A，不能返回 0。
• 应收计划未确认时完整率可以是 N/A；不得从记录条数猜完整率。
• 模型验证阈值未发布时，新候选不能发布；页面显示验证未配置/未通过。
• 本任务不新增手工训练、模型发布、回滚或停用接口，除非需求文档已有明确状态和页面消费者。

5. 后端实施

1. 三个接口统一后端 ROLE_ADMIN；前端菜单可见性不代替权限。
2. 列表请求加入白名单筛选、page、size、sort、direction；响应使用 Page 或等价真实 total。
3. 列表以 tb_model_run 为主表，LEFT JOIN tb_model_version、PUBLISHED tb_forecast_evaluation_result 和 tb_publish_run，使失败/未评估运行仍能显示自身状态和原因；不得返回堆栈。
4. backtest 以 modelRunNo 定位，确认权限和存在性；只返回已发布评估点，支持分页和 targetTime+id 稳定排序。
5. state 区分 NO_PUBLISHED_MODEL、VALIDATION_FAILED、TRAINING_INSUFFICIENT、NOT_CONFIGURED、NO_DATA 和 AVAILABLE。
6. 中文日志记录筛选、页码、运行/点数、模型状态和降级原因。

6. 数据追溯

页面字段	主要来源
训练运行/特征/失败原因	tb_model_run
模型版本、状态、训练截止、特征版本	tb_model_version
MAE/RMSE/WAPE、验证状态	tb_forecast_evaluation_result
逐点预测/实际/误差	tb_forecast_evaluation_point
验证阈值和训练门槛	tb_analysis_config_item/version
发布运行、时间、traceId	tb_publish_run

7. 前端适配

• 全部筛选、分页和排序真实进入请求；选择运行后再请求逐点证据。
• 完整率、特征覆盖率、WAPE 只按后端单位元数据展示，不前端换算业务结论。
• 展示失败代码和中文摘要，不显示内部堆栈。
• 403、NO_DATA、无发布模型和验证失败分别显示；切换筛选时清空旧回测明细。
• 管理菜单是否隐藏按现有会话能力实现，但无论可见与否均以后端 403 为准。

8. 最小验证门禁

1. 后端测试覆盖：普通用户 403、管理员空库、分页/筛选/稳定排序、WAPE 分母 0、失败运行脱敏、非发布评估不可见。
2. 只读 EXPLAIN 模型列表/count 和回测点查询。
3. 真实 HTTP 验证 401/403、NO_DATA、参数错误、成功读取和 traceId。
4. 运行相关 Maven 测试、Mapper XML 检查和注解 SQL 禁止扫描。
5. 运行 cd frontend; npm run build，验证权限态、分页、筛选和回测选择。

9. 交付报告

列出修改文件、契约、角色验证、追溯和实际测试结果。没有真实 PUBLISHED 模型/评估时，只能交付正确的不可用状态，不能声称模型训练或误差已验证。