# AI Chat Frontend

一个用于智能体比赛的前端主入口原型项目。当前阶段聚焦于聊天首页体验，使用 `React + Vite + TypeScript + Tailwind CSS` 构建，提供两套可切换主题：

- `柔和`：更偏 Kawaii Minimal 的浅色柔和风格
- `简洁`：更接近 `shadcn-admin / ChatGPT` 的中性简洁风格

目前未接入真实 API，聊天内容使用本地模拟数据渲染。

## 目标

- 作为智能体系统的前端主入口
- 后续承接聊天、多轮对话、知识库、复习流等功能
- 先把布局、主题、交互骨架稳定下来，再接真实后端能力

## 技术栈

- React 19
- Vite 6
- TypeScript
- Tailwind CSS
- React Router
- `class-variance-authority`
- `clsx`
- `tailwind-merge`

## 本地启动

```bash
npm install
npm run dev
```

生产构建：

```bash
npm run build
```

预览构建结果：

```bash
npm run preview
```

## 当前已完成

- 贴边式聊天主界面
- 左侧可折叠侧边栏
- 会话记录列表
- 固定底部输入框
- 聊天消息流展示
- `聊天 / 复习` 两个页面路由
- `柔和 / 简洁` 两套主题一键切换
- 主题切换结果持久化到 `localStorage`

## 当前未完成

- 真实聊天 API 接入
- 流式输出
- 会话创建、切换、删除的真实数据逻辑
- 用户鉴权
- 消息持久化
- 复习页面实际业务功能

## 目录结构

```text
src/
  App.tsx
  main.tsx
  index.css
  components/
    chat/
      chat-page.tsx
      chat-composer.tsx
      message-bubble.tsx
      mock-data.ts
      types.ts
    layout/
      app-shell.tsx
      sidebar.tsx
      theme-switcher.tsx
      theme.ts
    ui/
      avatar.tsx
      badge.tsx
      button.tsx
      card.tsx
      input.tsx
    icons.tsx
  pages/
    review-page.tsx
  lib/
    utils.ts
```

## 页面说明

### 聊天页

文件：
- `src/components/chat/chat-page.tsx`
- `src/components/chat/chat-composer.tsx`
- `src/components/chat/message-bubble.tsx`

特点：
- 消息区独立滚动
- 输入框固定在底部
- 会话记录放在侧边栏，不单独拆出中栏

### 复习页

文件：
- `src/pages/review-page.tsx`

当前仅做跳转占位，后续可扩展复习计划、知识卡片、错题归档等模块。

## 主题系统

主题状态定义：
- `src/components/layout/theme.ts`

主题切换组件：
- `src/components/layout/theme-switcher.tsx`

主题挂载位置：
- `src/components/layout/app-shell.tsx`

主题变量定义：
- `src/index.css`

说明：
- 主题通过 `data-theme="soft" | "classic"` 挂在最外层容器上
- 视觉差异主要通过 CSS 变量控制
- 页面、侧边栏、聊天气泡、输入框、按钮、头像都会跟随主题变化

协作时建议：
- 新增颜色时优先扩展 CSS 变量，不要在组件里继续堆硬编码颜色
- 如果是主题相关样式，优先落在 `index.css`
- 如果是单个组件结构调整，再改对应 `tsx`

## 数据约定

当前聊天内容来自：
- `src/components/chat/mock-data.ts`

后续接真实接口时建议：
- 把 `mock-data.ts` 替换为独立的 `services/` 或 `api/` 层
- 页面组件只负责展示，不直接拼接请求逻辑
- 消息结构沿用 `src/components/chat/types.ts`，避免重复定义

## 开发约定

### 1. 保持布局原则

- 聊天页采用贴边布局
- 会话记录保留在侧边栏
- 输入框固定底部
- 主聊天区尽量保持留白，不堆无关卡片

### 2. 保持主题策略

- `柔和` 主题：低饱和、轻甜、不杂乱
- `简洁` 主题：接近 ChatGPT / shadcn-admin 的中性灰白
- 不要出现带性别暗示的主题命名

### 3. 样式修改优先级

建议按这个顺序处理：

1. 先看是否能通过 CSS 变量解决
2. 再决定是否需要新增主题类
3. 最后才在组件里写临时颜色类

### 4. 组件复用建议

- 通用样式放 `src/components/ui`
- 页面组合逻辑放 `src/components/chat` 或 `src/components/layout`
- 路由页面只做页面级组合，不堆太多视觉细节

## 后续建议任务

推荐下一步按这个顺序推进：

1. 接入真实聊天 API
2. 支持流式回复
3. 接会话列表真实数据
4. 增加会话创建与切换逻辑
5. 补复习页的业务模块
6. 增加异常状态、空状态、加载态

## 说明

如果团队继续迭代这个项目，建议先统一以下内容再开发：

- API 返回格式
- 会话与消息的数据结构
- 主题变量命名规范
- 页面级组件与业务逻辑的拆分边界

这样可以避免后面出现样式、状态、接口三套逻辑交叉污染的问题。