makemd/docs/blueprints/frontend-integration/sandbox-roi-ui.md

前端集成蓝图：自治执行沙盒与 ROI 评估 (Sandbox & ROI UI)

[AI-2 @ 2026-03-14]：由后端 Agent 在完成 Batch 56 沙盒系列逻辑后产出，用于指导 Console 端全栈实现。

1. 业务意图 (Business Intent)

• 核心价值：为 AGI 决策提供“数字孪生”验证环境。在建议正式生效前，通过沙盒模拟执行并自动回测 ROI，降低全自动化带来的资金回撤风险。
• 关联后端 Service：AutonomousSandboxService.ts, SandboxROIAdvisor.ts

2. UI/UX 布局方案 (Layout Design)

• 页面入口：Console -> AI 控制台 -> 执行沙盒
• 展示组件：
  • 沙盒执行流展示：以时间轴形式展示模拟执行的步骤与结果。
  • ROI 回测仪表盘：对比“执行前”与“模拟后”的关键财务指标（毛利、周转率）。
  • 风险预警标记：若模拟结果触发业务红线（如 B2B 利润 < 15%），自动高亮显示。
• 交互草图：

  +-----------------------------------------------------------+
  | [Icon] AGI 执行沙盒回测 (Autonomous Sandbox)              |
  +-----------------------------------------------------------+
  | 建议 ID: SUG-882 | 模块: 动态调价 | 模拟状态: [ 成功 ]    |
  +-----------------------------------------------------------+
  | ROI 预估: +$150.50 (基于过去 30 天销量回测)               |
  | 利润率变化: 22% -> 24.5%                                  |
  +-----------------------------------------------------------+
  | [?] 模拟链路摘要 (Execution Trace)                        |
  | 1. 镜像当前 SKU 库存与成本数据...                         |
  | 2. 应用新价格 $29.9 -> $32.5...                           |
  | 3. 计算预估成交量漂移 (-2%)...                            |
  | 4. 汇总最终毛利提升...                                    |
  +-----------------------------------------------------------+
  | [ 重新模拟 ]                  [ 采纳建议并正式执行 ]      |
  +-----------------------------------------------------------+
  

3. API 交互契约 (API Integration)

• 数据获取：GET /api/v1/sandbox/executions (返回 cf_sandbox_executions 数据)
• 关键字段映射
  • simulated_output -> 模拟输出详情
  • estimated_roi -> 预估收益
  • status -> 执行状态 (SUCCESS/RISK_DETECTED)
• 状态流转：
  • 点击 [采纳] -> POST /api/v1/suggestions/approve -> 正式生效。

4. 生产校验项 (FE Readiness)

• 确保 estimated_roi 的货币单位跟随租户设置。
• 增加“沙盒隔离模式”标识，防止用户误以为是真实数据。
• 模拟执行期间显示加载动画 (Loading State)。