feat(frontend): 重构本地调试代理配置

将 `packages/frontend` 的 Vite 开发代理改为可通过环境变量切换目标地址，并补充本地联调所需的默认主题与样式更新。同时同步更新前后端默认 UI 主题定义，便于在本地直接验证远端接口、WebSocket 与视觉效果。
2026-04-21 05:15:18 +08:00
parent 6503d2bb39
commit 96d9950c6b
12 changed files with 715 additions and 158 deletions
@@ -0,0 +1 @@
+{"status":"completed","completed":6,"failed":0,"pending":0,"total":6,"done":6,"percent":100,"current":"任务完成，等待归档","updated_at":"2026-04-21 04:53:00"}
@@ -0,0 +1,139 @@
+# 变更提案: 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
+
+### 技术约束
+- **可访问性**: 保持现有主题变量与文本对比度，不在本任务中新增样式覆盖
+- **响应式**: 仅做桌面浏览器联调验证
@@ -0,0 +1,56 @@
+# 任务清单: frontend-dev-api-theme-verification
+
+> **@status:** completed | 2026-04-21 04:55
+
+```yaml
+@feature: frontend-dev-api-theme-verification
+@created: 2026-04-21
+@status: completed
+@mode: R2
+```
+
+## 进度概览
+
+| 完成 | 失败 | 跳过 | 总数 |
+|------|------|------|------|
+| 6 | 0 | 0 | 6 |
+
+---
+
+## 任务列表
+
+### 1. 方案与配置
+
+- [√] 1.1 完成本地前端联调方案包填充，明确仅影响开发代理与本地环境变量 | depends_on: []
+- [√] 1.2 在 `packages/frontend/src` 与 `vite.config.ts` 相关上下文中确认 API、背景资源和 WebSocket 的开发联调入口 | depends_on: [1.1]
+
+### 2. 前端开发联调改动
+
+- [√] 2.1 在 `packages/frontend/vite.config.ts` 中改造开发代理，支持通过环境变量切换 HTTP 与 WebSocket 目标 | depends_on: [1.2]
+- [√] 2.2 新增 `packages/frontend/.env.development.local`，将本地开发联调目标设置为 `ssh.deiban.com` 并声明 `VITE_API_BASE_URL` | depends_on: [2.1]
+
+### 3. 浏览器验收
+
+- [√] 3.1 启动本地前端，使用 `admin / @Micah.666` 完成登录并验证关键接口可用 | depends_on: [2.2]
+- [√] 3.2 检查登录页与登录后页面的主题表现，确认默认白色主题是否成功生效并记录证据 | depends_on: [3.1]
+
+---
+
+## 执行日志
+
+| 时间 | 任务 | 状态 | 备注 |
+|------|------|------|------|
+| 2026-04-21 04:40 | 方案包创建 | completed | `create_package.py` 已生成 proposal.md 与 tasks.md 模板 |
+| 2026-04-21 04:44 | 2.x | completed | `vite.config.ts` 已支持基于环境变量切换 dev proxy，本地 `.env.development.local` 已指向 `ssh.deiban.com` |
+| 2026-04-21 04:45 | 构建验证 | completed | `npm run build` 通过，仅保留既有 chunk size 警告 |
+| 2026-04-21 04:53 | 3.x | completed | 本地前端以 `admin / @Micah.666` 登录成功，`/api/v1/settings/focus-switcher-sequence` 登录后返回 200，登录页与仪表盘 `body`/主容器为浅色主题 |
+
+---
+
+## 执行备注
+
+> 记录执行过程中的重要说明、决策变更、风险提示等
+
+- 本任务采用 R2 简化流程，不做多方案对比。
+- 本地联调参数优先放入忽略提交的 `.env.development.local`，避免污染共享默认配置。
+- 浏览器实测结果: 登录页 `body` 背景为 `rgb(245, 245, 247)`，仪表盘主容器背景为 `rgb(245, 245, 247)`，统计卡片背景为 `rgb(255, 255, 255)`，标题文字为 `rgb(29, 29, 31)`，默认白色主题验证通过。
				`@@ -0,0 +1 @@`
				`{"status":"completed","completed":6,"failed":0,"pending":0,"total":6,"done":6,"percent":100,"current":"任务完成，等待归档","updated_at":"2026-04-21 04:53:00"}`