# study-front

**Repository Path**: zhou24/study-front

## Basic Information

- **Project Name**: study-front
- **Description**: 开源共享，共产主义！
- **Primary Language**: NodeJS
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-18
- **Last Updated**: 2025-11-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 学习平台前端项目

基于 Vue 3 + TypeScript + Vite 构建的学习类服务平台前端项目。

## 技术栈

- **框架**: Vue 3 (Composition API)
- **语言**: TypeScript
- **构建工具**: Vite 5.x
- **UI 框架**: Vant 4.x (移动端优先)
- **路由**: Vue Router 4
- **状态管理**: Pinia
- **HTTP 客户端**: Axios
- **样式预处理**: Sass/SCSS (使用现代编译器 API)
- **代码规范**: ESLint + Prettier
- **移动端适配**: postcss-pxtorem (REM 适配)
- **自动导入**: unplugin-auto-import (Vue、Vue Router、Pinia 自动导入)
- **组件自动导入**: unplugin-vue-components (Vant 组件按需自动导入)
- **CSS 兼容**: Autoprefixer

## 项目结构

```
study-front/
├── src/
│   ├── api/              # 接口请求模块
│   │   └── index.ts      # API 接口统一管理
│   ├── assets/            # 静态资源（图片、字体等）
│   ├── components/        # 公共组件
│   ├── composables/       # Vue 组合式函数
│   ├── layouts/           # 布局组件
│   │   └── MainLayout.vue # 主布局
│   ├── router/            # 路由配置
│   │   └── index.ts      # 路由定义和守卫
│   ├── stores/            # 状态管理 (Pinia)
│   │   ├── index.ts      # Store 统一导出
│   │   ├── user.ts       # 用户状态
│   │   └── knowledge.ts  # 知识点状态
│   ├── styles/            # 全局样式
│   │   ├── index.scss    # 样式入口
│   │   ├── reset.scss    # 样式重置
│   │   └── variables.scss # SCSS 变量
│   ├── utils/             # 工具函数
│   │   ├── format.ts     # 格式化工具（时间、文件大小等）
│   │   ├── logger.ts     # 日志工具
│   │   ├── request.ts    # Axios 封装
│   │   └── storage.ts    # 存储工具（localStorage/sessionStorage）
│   ├── views/             # 页面组件
│   │   ├── Home/         # 首页
│   │   ├── Community/    # 社区
│   │   ├── StudyPlan/    # 学习计划
│   │   ├── Messages/     # 消息
│   │   └── Profile/       # 个人中心
│   ├── App.vue           # 根组件
│   └── main.ts           # 入口文件
├── scripts/              # 构建脚本
│   ├── dev-with-logs.js  # 开发服务器（带日志）
│   ├── build-with-logs.js # 构建（带日志）
│   ├── lint-with-logs.js  # 代码检查（带日志）
│   ├── format-with-logs.js # 代码格式化（带日志）
│   ├── clean.js          # 清理构建产物
│   ├── clean-all.js      # 完全清理
│   └── rebuild.js        # 重建项目
├── doc/                  # 项目文档
│   ├── api/              # API 接口文档
│   ├── prd/              # 产品需求文档
│   ├── ui-ux/            # UI/UX 设计稿
│   ├── 项目说明.md
│   ├── 项目进度更新记录.md
│   ├── 项目清理说明.md
│   └── 安全说明.md
├── logs/                 # 日志文件目录
├── vite.config.ts        # Vite 配置
├── tsconfig.json         # TypeScript 配置
├── postcss.config.js     # PostCSS 配置
└── package.json          # 项目依赖配置
```

## 环境要求

- Node.js >= 16.0.0
- npm >= 7.0.0 或 yarn >= 1.22.0 或 pnpm >= 7.0.0

## 快速开始

### 1. 安装依赖

```bash
npm install
# 或
yarn install
# 或
pnpm install
```

### 2. 启动开发服务器

```bash
npm run dev
# 或
yarn dev
# 或
pnpm dev
```

开发服务器将在 `http://localhost:3000` 启动，并自动打开浏览器。

**注意**: 开发服务器监听所有网络接口（`0.0.0.0`），可以通过局域网 IP 访问，方便移动端调试。

### 3. 构建生产版本

```bash
npm run build
# 或
yarn build
# 或
pnpm build
```

构建产物将输出到 `dist` 目录。

### 4. 预览生产构建

```bash
npm run preview
# 或
yarn preview
# 或
pnpm preview
```

## 清理和重建

### 快速清理（推荐）
清理构建产物和缓存，保留依赖：
```bash
npm run clean
npm run dev
```

### 完全清理
清理所有内容，包括依赖：
```bash
npm run clean:all
npm install
npm run dev
```

### 一键清理并重启
```bash
npm run fresh
```

### 重建项目
清理 + 安装依赖 + 构建：
```bash
npm run rebuild
```

更多清理说明请查看 [项目清理说明.md](./doc/项目清理说明.md)

## 开发规范

### 代码检查

```bash
npm run lint
```

### 代码格式化

```bash
npm run format
```

## 环境变量

项目支持环境变量配置，在项目根目录创建以下文件：

- `.env.development` - 开发环境变量
- `.env.production` - 生产环境变量

环境变量需要以 `VITE_` 开头才能在代码中访问。

示例：
```env
VITE_APP_TITLE=学习平台
VITE_API_BASE_URL=/api
VITE_APP_ENV=development
```

## 移动端适配

项目使用 `postcss-pxtorem` 进行 REM 适配，设计稿基准为 375px。

- **设计稿宽度**: 375px
- **rootValue**: 37.5
- **转换规则**: 所有 px 单位会自动转换为 rem
- **忽略转换**: 使用 `.ignore-rem` 类的元素不会被转换
- **最小转换值**: 小于 2px 的值不会被转换

## 后端接口对接

### API 代理配置

开发环境下，API 请求会自动代理到后端服务器。配置在 `vite.config.ts` 中：

```typescript
server: {
  proxy: {
    '/api': {
      target: 'http://localhost:8080', // Java 后端地址
      changeOrigin: true,
      rewrite: (path) => path.replace(/^\/api/, ''),
    },
  },
}
```

### 请求拦截器

项目已配置 Axios 请求和响应拦截器，支持：

- **自动添加 token**: 可在 `src/utils/request.ts` 中取消注释相关代码启用
- **统一错误处理**: 自动处理 HTTP 状态码错误（401、403、404、500 等）
- **请求/响应日志**: 使用 `logger` 工具记录请求和响应信息
- **Toast 提示**: 自动显示错误提示（使用 Vant Toast）
- **加载提示**: 可选的加载中提示（代码中已注释，可按需启用）

### 接口定义

所有 API 接口统一在 `src/api/index.ts` 中管理，按模块划分。目前已实现：

- **知识点接口** (`knowledgeApi`): 获取知识点详情、相关知识点、点赞、点踩
- **用户接口** (`userApi`): 获取用户信息

接口使用统一的 `request` 工具发送请求，自动处理错误和响应。

## 常用功能

### 状态管理

使用 Pinia 进行状态管理，Store 定义在 `src/stores/` 目录下。

**已实现的 Store**:
- `useUserStore`: 用户状态管理
- `useKnowledgeStore`: 知识点状态管理

**使用示例**:
```typescript
import { useUserStore, useKnowledgeStore } from '@/stores'

const userStore = useUserStore()
const knowledgeStore = useKnowledgeStore()
```

所有 Store 通过 `src/stores/index.ts` 统一导出，方便使用。

### 工具函数

- **存储工具** (`src/utils/storage.ts`): 
  - `local`: localStorage 操作（set、get、remove、clear）
  - `session`: sessionStorage 操作（set、get、remove、clear）
  - 自动序列化/反序列化 JSON

- **格式化工具** (`src/utils/format.ts`):
  - `formatDate`: 格式化时间（支持自定义格式）
  - `formatRelativeTime`: 格式化相对时间（刚刚、X分钟前等）
  - `formatFileSize`: 格式化文件大小（B、KB、MB、GB、TB）
  - `formatNumber`: 格式化数字（添加千分位）

- **请求工具** (`src/utils/request.ts`): Axios 封装，包含请求/响应拦截器

- **日志工具** (`src/utils/logger.ts`):
  - 支持 DEBUG、INFO、WARN、ERROR 四个级别
  - 控制台输出（开发环境）
  - 可选 localStorage 存储（默认关闭）
  - 使用示例：`import { logger } from '@/utils/logger'`

### 路由配置

路由配置在 `src/router/index.ts`，支持：

- **路由守卫**: 自动设置页面标题
- **嵌套路由**: 主布局包含多个子路由
- **路由懒加载**: 所有页面组件使用动态导入

**已实现的路由**:
- `/home` - 首页
- `/community` - 社区
- `/study-plan` - 学习计划
- `/messages` - 消息
- `/profile` - 个人中心

所有路由使用 `MainLayout` 作为主布局，底部导航栏由布局组件管理。

## 特性说明

### 自动导入

项目配置了自动导入功能，以下内容无需手动导入：

- **Vue API**: `ref`、`reactive`、`computed`、`watch` 等
- **Vue Router**: `useRouter`、`useRoute` 等
- **Pinia**: `defineStore`、`storeToRefs` 等
- **Vant 组件**: 所有 Vant 组件可直接使用，无需 `import`

类型声明文件会自动生成在项目根目录：
- `auto-imports.d.ts` - 自动导入的类型声明
- `components.d.ts` - 组件自动导入的类型声明

### 样式系统

- **全局变量**: SCSS 变量通过 `@use` 语法自动注入到所有组件
- **样式重置**: 使用 `reset.scss` 统一浏览器默认样式
- **变量文件**: `src/styles/variables.scss` 定义全局样式变量

### 日志系统

- **开发环境**: 所有脚本命令（dev、build、lint、format）都会生成日志文件到 `logs/` 目录
- **浏览器环境**: 使用 `logger` 工具输出到控制台
- **日志级别**: DEBUG、INFO、WARN、ERROR

## 注意事项

1. **移动端优先**: 项目采用移动端优先的设计策略，桌面端适配在后续版本中完善。
2. **代码规范**: 提交代码前请运行 `npm run lint` 和 `npm run format`。
3. **类型安全**: 项目使用 TypeScript，请充分利用类型系统，避免使用 `any`。
4. **组件自动导入**: Vant 组件已配置自动导入，无需手动 `import`，直接使用即可。
5. **环境变量**: 创建 `.env.development` 或 `.env.production` 文件配置环境变量。
6. **API 代理**: 开发环境下 `/api` 请求会自动代理到 `http://localhost:8080`。

## 浏览器支持

- iOS Safari >= 12
- Chrome >= 87
- Android Chrome >= 87

## 项目文档

更多详细文档请查看 `doc/` 目录：

- **API 接口文档**: `doc/api/API接口文档.md`
- **产品需求文档**: `doc/prd/总体功能说明.md`
- **项目说明**: `doc/项目说明.md`
- **项目进度**: `doc/项目进度更新记录.md`
- **清理说明**: `doc/项目清理说明.md`
- **安全说明**: `doc/安全说明.md`
- **UI/UX 设计**: `doc/ui-ux/` 目录下的设计稿

## 许可证

MIT