yinjianm
96d9950c6b
将 `packages/frontend` 的 Vite 开发代理改为可通过环境变量 切换目标地址，并补充本地联调所需的默认主题与样式更新。 同时同步更新前后端默认 UI 主题定义，便于在本地直接验证 远端接口、WebSocket 与视觉效果。
140 lines
5.2 KiB
Markdown
140 lines
5.2 KiB
Markdown
# 变更提案: 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
|
|
|
|
### 技术约束
|
|
- **可访问性**: 保持现有主题变量与文本对比度，不在本任务中新增样式覆盖
|
|
- **响应式**: 仅做桌面浏览器联调验证
|