# 前后端对接与交互重构日志（夜间无人值守）

> 任务：有凭据地补全前端空壳，实现极简透明、零污染的交互。
> 范围：扫描全前端（apps/ai-frontend、software/khyquant/frontend、TUI、Python CLI），
> 仅对「已存在后端逻辑、且直接响应用户意图或含 >1.5s 网络往返」的空壳补显示。
> 约束：只调用后端、不增删后端核心逻辑；每打通一个即独立提交。

---

## 一、扫描结论（空壳分布）

| 前端面 | 根目录 | 结论 |
|---|---|---|
| AI 网关/Agent UI | `apps/ai-frontend/src`（Vue3+Vite） | **无空壳**，全部运行时拉取真实数据 |
| KhyQuant 交易前端 | `software/khyquant/frontend/src`（Vue3+Vite） | 空壳集中于此，见下 |
| TUI | `services/backend/src/cli/tui`（Ink/React） | 无 UI 空壳（占位仅输入框 placeholder） |
| Python CLI | `platform/khy_platform`（启动器） | 无功能空壳 |

前端→后端通道：khyquant 经 `axios`（`utils/connectionMode.js` 的 `getApiBaseUrl()` 感知
local/cloud/lan）+ WebSocket；`request` 拦截器直接返回响应体（`response.success` 可用）。

---

## 二、已打通的空壳（按凭据强弱排序）

### 1. 订单详情 · `LiveTradingCenter.vue:310` ✅ 已对接
- **修改前**：`viewOrderDetail = (order) => ElMessage.info('订单详情功能开发中...')`（纯空壳）。
- **修改后**：绑定**已存在**的 `tradeAPI.getOrderDetail(order.id)` → 后端 `GET /trading/order/:id`
  （`software/khyquant/routes/trade.js:702`，真实存在）。
- **有凭据的 UI 显示及凭据**：
  - 单行 `ElLoading`「检索订单详情 {symbol}…」——**凭据：直接响应用户「查看详情」点击意图 + 含网络往返（可能 >1.5s）**。等待过程单行呈现、完成即自动消失，零残留。
  - 成功仅渲染**关键字段摘要**（合约/方向/状态/委托价/数量/已成交/策略/下单时间，状态走 `getStatusText` 转人话），**原始字段折叠进 `<details>`** 降噪。
  - 失败走精准报错闭环：`查看订单详情失败 · 订单 {symbol}：{人话原因}。请稍后重试或刷新列表`（404→「订单不存在或已被清理」），**不抛 stacktrace**。HTML 值统一转义防注入。
- **提交**：`feat: 对接订单详情空壳，实现单行Loading+折叠式透明反馈`

### 2. 交易记录导出 · `ProfessionalTradeHistory.vue:584` ✅ 已对接
- **修改前**：`exportTrades() { ElMessage.info('导出功能开发中...') }`（纯空壳）。
- **修改后**：基于**已就绪**的 `filteredTrades`（来自 `tradeAPI.getTrades()`）本地组装
  UTF-8(BOM) CSV 并触发浏览器下载（文件名带时间戳）。
- **有凭据的 UI 显示及凭据**：
  - **未加 Loading 控件**——**凭据：纯客户端组装 <1.5s**，按凭据原则不为快操作加状态位；
  - 完成仅一行结果摘要 `✔ 已导出 N 笔交易记录`，隐藏过程；
  - 空结果：`导出交易记录：当前筛选结果为空，请调整筛选条件后再试`；
  - 异常走精准报错闭环：`导出交易记录失败：{原因}。请改用 Chrome/Edge 或检查下载权限`。
  - 导出列与表格展示一致且转人话（买/卖、方式标签、状态文本、盈亏）。
- **提交**：`feat: 对接交易记录导出空壳，实现客户端CSV真导出`

### 3. 回放单步后退 · `DataReplay.vue:532` ⚠️ 后端缺失，标注待审
- **修改前**：`stepBack = () => ElMessage.info('暂不支持后退，请重新开始回放')`。
- **判定**：后端回放仅有 `GET /:sessionId/next`（`routes/replay.js:84`），**无 `/prev`**。
  按「不增删后端核心逻辑」约束，**不擅自补后端**。
- **修改后**：加 `// TODO: [Integration-Unresolved] 需人工审查` 标注（指明需人工评估为回放引擎
  补 `/prev` 步进或快照回滚），并将提示精准化为
  `单步后退暂未支持：回放引擎当前仅能前进，请点击「重新开始」从头回放`（动作+原因+建议）。
- **提交**：`chore: 回放后退空壳标注待人工审查并精准化降级提示`

---

## 三、已确认无需改动（容错型 mock，非空壳）

下列「mock」均为**成功路径已接真后端**的离线/失败降级，且**已自标注**，符合透明原则，未改动：

- `InstrumentSelector.vue:143 useMockData()` — 失败时已设 `dataSource='模拟数据'` +
  `ElMessage.warning('API不可用,使用模拟数据')`，真后端 `routes/instruments.js`。
- `SimpleTradingInterface.js` 持仓 mock、`RealTimeKLineChart/SimpleKLineChart/priceDataService/
  marketDataService` 的 K 线/行情 mock — 均为「真→缓存→模拟」三级降级，真后端
  `routes/klineData.js`/`marketData.js` 存在。

> 说明：这些是有意的离线韧性且已诚实标注数据来源，**强行加提示反成新的显示污染**，故保留。

---

## 四、留给你的 TODO

1. **`[Integration-Unresolved]` 回放后退**（`DataReplay.vue:532`）：如需真正单步后退，需人工决策为
   回放引擎补 `/replay/:sessionId/prev`（或基于快照回滚），再由前端对接。属后端能力新增，已按约束留给人工。
2. **基准收益率未实现**（`SimpleTradingInterface.js:5385` `benchmarkReturn: 0 // 暂未实现`）：
   回测结果中的内部指标，硬编码为 0。实算需拉取基准指数序列对比，属功能新增而非接线缺口；
   按「不暴露纯内部项 / 不擅自补后端」暂未处理，待你确认是否纳入路线。
3. **导出端点（可选增强）**：当前导出为客户端 CSV，已满足意图；若未来需服务端大批量导出/带签名，
   可另议在 `routes/trade.js` 增 `GET /trading/export`（后端改动，需你授权）。

---

## 五、验证与提交

- 三处改动均通过 `@vue/compiler-sfc` 编译校验（SFC compile OK）；订单详情对接经括号配平核对。
- 每个空壳独立 commit（共 3 笔），message 标明改动与凭据；**全程未触碰后端业务逻辑/数据库查询/核心算法**。
- 未运行整包 `vite build`（沙箱无网络，且与本轮改动解耦）；如需绿色基线请在 CI 跑全量构建。
