docs/v1.0/.archive/client/phase1-infrastructure.md

第一阶段：基础架构搭建

执行日期：2026-01-09
状态：✅ 已完成

上下文

根据 development-plan.md 开发计划文档，第一阶段的目标是：

• 完成项目初始化和技术栈配置
• 搭建开发环境和工具链
• 集成 UI 组件库和样式系统
• 定义项目目录结构和代码规范

完成的任务

1. 项目初始化 (1.1.x)

#	任务	状态
1.1.1	使用 Vite 创建 React + TypeScript 项目	✅
1.1.2	配置 ESLint + Prettier	✅
1.1.3	配置 Husky + lint-staged	✅
1.1.4	配置路径别名 (tsconfig.json + vite.config.ts)	✅
1.1.5	创建目录结构	✅
1.1.6	配置环境变量 (.env.development, .env.production)	✅

2. 样式系统 (1.2.x)

#	任务	状态
1.2.1	安装配置 Tailwind CSS v4	✅
1.2.2	配置 @theme（颜色、字体、动画）	✅
1.2.3	创建 globals.css（CSS 变量、全局样式）	✅
1.2.4	配置深色主题变量	✅
1.2.5	配置亮色主题变量	✅
1.2.6	实现主题切换逻辑（防闪烁）	✅

3. 组件库集成 (1.3.x)

#	任务	状态
1.3.1	安装 Radix UI 组件	✅
1.3.2	创建 shadcn/ui 风格基础组件	✅
1.3.3	安装 lucide-react 图标库	✅
1.3.4	创建 lib/utils.ts（cn 函数）	✅

4. 核心依赖安装 (1.4.x)

#	任务	状态
1.4.1	安装 React Router	✅
1.4.2	安装 Zustand	✅
1.4.3	安装 TanStack Query	✅
1.4.4	安装 Axios	✅
1.4.5	安装 React Hook Form + Zod	✅
1.4.6	安装 date-fns	✅
1.4.7	安装 @dnd-kit/core + @dnd-kit/sortable	✅
1.4.8	安装 react-i18next + i18next	✅

5. 基础配置 (1.5.x)

#	任务	状态
1.5.1	配置 TanStack Query Provider	✅
1.5.2	配置 Router	✅
1.5.3	创建基础 Zustand Stores	✅
1.5.4	配置 API Client (Axios)	✅
1.5.5	创建类型定义文件	✅
1.5.6	配置 i18n（语言文件结构、Provider）	✅
1.5.7	配置 ThemeProvider（主题切换）	✅
1.5.8	创建 settingsStore（语言、主题状态）	✅

项目结构

client/
├── src/
│   ├── app/                      # 应用入口层
│   │   ├── App.tsx              # 根组件
│   │   ├── Router.tsx           # 路由配置
│   │   └── providers/           # Provider 组件
│   ├── components/              # 组件层
│   │   ├── ui/                  # 基础 UI 组件 (shadcn/ui)
│   │   ├── layout/              # 布局组件
│   │   ├── features/            # 功能组件
│   │   └── common/              # 通用组件
│   ├── hooks/                   # 自定义 Hooks
│   ├── stores/                  # Zustand 状态管理
│   ├── services/                # 服务层
│   ├── types/                   # TypeScript 类型定义
│   ├── utils/                   # 工具函数
│   ├── constants/               # 常量定义
│   ├── styles/                  # 全局样式
│   ├── assets/                  # 静态资源
│   ├── lib/                     # 第三方库配置
│   └── pages/                   # 页面组件
├── public/
│   └── locales/                 # 国际化语言文件
│       ├── zh-CN/
│       └── en-US/
└── package.json

技术栈

• 框架：React 19 + TypeScript 5.9
• 构建工具：Vite 7
• 样式：Tailwind CSS v4
• UI 组件：Radix UI + shadcn/ui 风格
• 状态管理：Zustand 5
• 数据请求：TanStack Query 5 + Axios
• 路由：React Router 7
• 国际化：react-i18next
• 拖拽：@dnd-kit

验收结果

检查项	验收条件	结果
开发服务器	npm run dev 可正常启动	✅
生产构建	npm run build 可正常构建	✅
代码检查	npm run lint 0 个 error	✅
类型检查	npm run type-check 通过	✅

下一阶段

第二阶段：静态数据展示 - 开发所有 UI 组件，使用 Mock 数据展示界面