# ADR-002: 前端架构选型

## 修改记录

| 日期 | 变更 |
|------|------|
| 2026-07-18 | ADR-002++ 表格化，LLM Agent 拆为 ✅ SSE / ⏸ WebSocket，补充交叉引用 |

## ADR-002++

| 状态 | 项 | 说明 | 验证 |
|------|-----|------|------|
| ✅ | LLM Agent SSE 流式 | `fetch + ReadableStream` 手动解析 SSE，逐 token 追加 | `AgentPage.vue:76-106` |
| ⏸ | LLM Agent WebSocket | SSE 升级为全双工通信 | 未开始 |
| ⏸ | 方案对比视图 | 多方案并排对比 UI | 数据就绪，未实现 |
| ⏸ | 离线 PWA 支持 | Service Worker + IndexedDB | 未开始 |

## 状态

✅ 已采纳（原毕设 Streamlit 方案已废弃）

## 背景

后端引擎（TSPTW 求解器）已构建完成，LLM Agent 规划模块待实现，需要前端界面进行交互展示。核心需求：

1. 2D 地图可视化（高德 AMap JS API）——展示每日行程路径（[详见 `frontend.md §4 AmapMap`](../structure/frontend.md#4-可复用组件)）
2. LLM Agent 对话面板——自然语言交互、流式输出（SSE）（[详见 `frontend.md §3 AgentPage`](../structure/frontend.md#3-页面组件)）
3. 方案选择与行程编辑（选择：[`frontend.md §3 SuggestPage`](../structure/frontend.md#3-页面组件)；编辑：输入阶段 `HomePage.vue` 可编辑，规划结果 `PlanPage.vue` 只读）
4. 后期可扩展更多 Agent 交互功能

## 三方案对比

| 方案 | 优点 | 缺点 | 结论 |
|------|------|------|------|
| **Streamlit**（原毕设方案） | 纯 Python，快速原型，无需前端知识 | 高级地图功能嵌入困难（需 iframe/组件），Agent 实时交互不灵活，样式受限 | ❌ 已废弃 |
| **FastAPI + HTMX + Jinja2 + SSE** | 纯 Python，SSE 原生支持 stream，无构建步骤 | 复杂前端状态管理混乱，地图仍需手写 JS，两个世界拼凑感强 | ❌ 不推荐 |
| **Vue 3 + Vite 前端分离** | 组件化清晰，地图/Agent 集成自然，生态成熟 | 需要前端构建流程 | ✅ 采纳（[现状：9 文件 100% Composition API](../structure/frontend.md#1-架构总览)） |

## 框架选型：Vue 3 而非 React

| 维度 | Vue 3 | React |
|------|-------|-------|
| 学习曲线 | 低（SFC 直观，Composition API 简洁） | 高（JSX + Hooks 心智负担大） |
| 集成高德 JS API | vue-amap / 直接挂载 | 需自行封装 |
| 项目体积 | 轻量 | 生态碎片需自行组合 |
| 构建工具 | Vite（官方推荐，零配置） | CRA/Vite（选路迷茫） |