# 变更提案: frontend-dev-api-theme-verification

## 元信息
```yaml
类型: 优化
方案类型: implementation
优先级: P1
状态: 已完成
创建: 2026-04-21
```

---

## 1. 需求

### 背景
用户要求将本地前端联调请求切到 `https://ssh.deiban.com`，重点验证
`/api/v1/settings/focus-switcher-sequence` 这类设置接口是否能通过本地前端正确访问，
并使用 `admin / @Micah.666` 登录后确认此前“默认前端白色主题”改动是否真实生效。

### 目标
- 仅调整本地开发联调入口，不改动前端生产默认 API 地址。
- 让本地 `packages/frontend` 在开发模式下统一代理远端 `https://ssh.deiban.com`。
- 完成一次真实浏览器登录与页面视觉验收，确认白色主题是否生效，并给出结论。

### 约束条件
```yaml
时间约束: 当前回合内完成代码改动与联调验证
性能约束: 不引入额外运行时开销，保持 Vite 代理方案
兼容性约束: 现有相对路径 API 调用保持不变，本地切换后仍可回退到 localhost:3001
业务约束: 仅作用于本地开发联调，不覆盖共享生产配置
```

### 验收标准
- [√] 本地前端开发环境可将 `/api`、`/uploads`、`/ws` 请求代理到 `ssh.deiban.com`
- [√] 使用 `admin / @Micah.666` 可从本地前端完成登录并访问登录后页面
- [√] 浏览器实测能判断白色主题是否生效，并能给出成功或失败的证据

---

## 2. 方案

### 技术方案
保留前端现有的相对路径请求方式，不改 `apiClient` 和 store 内部接口地址。
将 `packages/frontend/vite.config.ts` 改为支持从本地开发环境变量读取 dev proxy 目标，
默认仍指向 `localhost:3001`。同时新增忽略提交的
`packages/frontend/.env.development.local`，把本地开发代理目标切换到
`https://ssh.deiban.com` / `wss://ssh.deiban.com`，并显式设置 `VITE_API_BASE_URL`
供页面背景等直接拼接后端 URL 的逻辑使用。完成后启动本地 Vite，并用浏览器执行登录和主题验收。

### 影响范围
```yaml
涉及模块:
  - frontend: 调整本地开发代理配置与运行时联调环境变量
预计变更文件: 4
```

### 风险评估
| 风险 | 等级 | 应对 |
|------|------|------|
| 远端站点 WebSocket 目标与本地代理协议不兼容 | 中 | 同步提供 `VITE_DEV_WS_PROXY_TARGET`，保持与 HTTP 代理解耦 |
| 远端管理员账号存在用户级外观配置，导致白色主题判断受后端数据影响 | 中 | 同时检查登录页和登录后页面样式来源，区分默认主题与后端覆盖 |
| 本地环境变量文件被忽略后不在 Git 记录中 | 低 | 在最终结果中明确说明本地文件路径与用途 |

---

## 3. 技术设计（可选）

> 本次不涉及架构、API 或数据模型变更。

### 架构设计
N/A

### API设计
N/A

### 数据模型
N/A

---

## 4. 核心场景

> 执行完成后同步到对应模块文档

### 场景: 本地前端联调远端测试后端
**模块**: frontend
**条件**: 开发者在 `packages/frontend` 启动本地 Vite 开发服务器
**行为**: 前端通过本地代理将 `/api`、`/uploads`、`/ws` 请求转发到 `ssh.deiban.com`
**结果**: 无需改动业务代码中的相对路径接口即可完成远端联调

### 场景: 登录后验收默认白色主题
**模块**: frontend
**条件**: 使用管理员账号登录本地前端
**行为**: 检查登录页与登录后页面的背景、文字和主容器配色
**结果**: 能明确判断白色主题是否生效，以及是否被后端持久化外观配置覆盖

---

## 5. 技术决策

> 本方案涉及的技术决策，归档后成为决策的唯一完整记录

### frontend-dev-api-theme-verification#D001: 使用可配置的 dev proxy 而非写死远端 API
**日期**: 2026-04-21
**状态**: ✅采纳
**背景**: 需要将本地前端切到远端测试后端验证主题效果，但不应把共享开发默认值永久改成远端地址。
**选项分析**:
| 选项 | 优点 | 缺点 |
|------|------|------|
| A: 直接把 `vite.config.ts` 写死到 `ssh.deiban.com` | 改动最少，立刻可用 | 污染团队默认开发配置，回切需要再次改代码 |
| B: 让 `vite.config.ts` 读取环境变量，再用 `.env.development.local` 本地覆盖 | 保持默认本地后端联调，同时支持当前远端测试 | 需要新增一个本地环境变量文件 |
**决策**: 选择方案 B
**理由**: 既满足当前本地调试诉求，又不破坏仓库共享默认值，后续切回本地后端只需改本地环境变量。
**影响**: 影响 `packages/frontend/vite.config.ts` 的开发代理读取方式，以及本地开发环境变量文件组织方式

---

## 6. 成果设计

> 含视觉产出的任务由 DESIGN Phase2 填充。非视觉任务整节标注"N/A"。

本任务不新增视觉设计，仅验证既有白色主题是否已经生效。

### 设计方向
- **美学基调**: N/A
- **记忆点**: N/A
- **参考**: 现有前端默认白色主题实现

### 视觉要素
- **配色**: N/A
- **字体**: N/A
- **布局**: N/A
- **动效**: N/A
- **氛围**: N/A

### 技术约束
- **可访问性**: 保持现有主题变量与文本对比度，不在本任务中新增样式覆盖
- **响应式**: 仅做桌面浏览器联调验证