# ADR-001 前端技术栈选型

- **状态**:已确认
- **日期**:2026-08-29
- **决策者**:产品负责人 + 技术负责人
- **关联**:TASK-前端 UI 体系、产品设计方案 §3 信息架构

## 背景

BossAI 面向中国中小企业老板,属 B 端专业工具(经营/法务/情绪支持)。MVP 后端已用 FastAPI 跑通 Kimi 云端模型闭环,现需构建专业前端 UI 体系。当前 `web.html` 为低保真单文件原型,无法支撑多模块信息架构(驾驶舱/法务参谋/经营决策/生活助理/情绪中心/设置)。

## 决策

采用 **React 18 + Vite + TypeScript + Tailwind CSS + shadcn/ui** 技术栈。

| 层 | 选型 | 理由 |
|---|---|---|
| 框架 | React 18 | 生态成熟,shadcn/ui 原生支持 |
| 构建 | Vite 5 | 启动快,HMR 流畅,产物为静态包,部署简单 |
| 语言 | TypeScript 5 | 类型安全,B 端信息密集场景必备 |
| 样式 | Tailwind CSS 3 | 原子化,符合全局规则 oklch/语义 token 要求 |
| 组件 | shadcn/ui | 复制即用,无运行时依赖锁死,可定制 |
| 图标 | lucide-react | 全局规则首选图标库 |
| 反馈 | sonner | 轻量 toast,替代 alert/confirm |
| 图表 | recharts | 驾驶舱风险/待办可视化 |
| 路由 | react-router-dom v6 | SPA 路由 |
| 请求 | 原生 fetch + 轻封装 | 避免引入 axios 等额外依赖 |

## 否决方案

- **Next.js**:SSR 对内网 SPA 工具价值有限,且需 Node 常驻进程,部署比 Vite 静态包复杂。
- **Vue + Element Plus**:与全局规则推荐的 shadcn 体系不一致,前后端生态割裂。

## 设计风格约束(B 端专业)

- 主色 `gray-900`,内容区 `bg-[#f8f9fb]`,信息密集
- 左 Sidebar `w-60 sticky`,Header `h-14 bg-white/95 backdrop-blur`
- 状态色三件套:`emerald(success) / amber(warning) / rose(destructive)`
- 风险等级色:`green / amber / orange / red`
- 禁硬编码 hex 主色,禁 alert/confirm,禁 div onClick,禁多 UI 库混用
- 容器 `container mx-auto max-w-7xl px-4`
- 符合中小企业老板审美:稳重、可信、克制,情绪中心模块适度加温

## 架构边界

- 前端工程独立目录 `web/`,与 Python 后端解耦
- 开发期 Vite 代理 `/api` → `http://127.0.0.1:8000`,生产期同源或反代
- 前端不持有密钥,所有模型调用经后端 `/sessions/{sid}/ask` 完成
- 公共组件放 `web/src/components/`,页面放 `web/src/pages/`

## 后果

- 需 Node 18+ 环境运行前端
- 前后端分离,部署需分别构建(后端 uvicorn,前端静态包)
- shadcn/ui 组件按需复制进仓库,不依赖外部运行时包