ShadeMarket 前端

光影集市前端项目，基于 Vue 3 + TypeScript + Vite 构建

技术栈

核心框架

技术	版本	说明
Vue.js	3.5.22	渐进式 JavaScript 框架
TypeScript	5.9	JavaScript 超集，提供类型安全
Vite	7.1.7	新一代前端构建工具

UI 框架

技术	版本	说明
Element Plus	2.11.4	Vue 3 企业级 UI 组件库
Element Plus Icons	2.3.2	Element Plus 图标库
FontAwesome	-	图标字体库

路由与状态

技术	版本	说明
Vue Router	4.5.1	Vue 官方路由管理器
Pinia	3.0.3	Vue 官方状态管理库

HTTP 客户端

技术	版本	说明
Axios	1.12.2	Promise HTTP 客户端
openapi-typescript	7.10.1	OpenAPI 类型生成器

开发工具

技术	说明
ESLint	代码检查工具
Prettier	代码格式化工具
Vue DevTools	Vue 开发调试工具

测试框架

技术	说明
Vitest	单元测试框架
Playwright	端到端测试框架
@testing-library/vue	Vue 组件测试工具
MSW	API Mock 工具

快速开始

环境要求

Node.js ^20.19.0 || >=22.12.0
npm 10.x 或更高

安装依赖

npm install

生成 API 类型

npm run gen:api

启动开发服务器

npm run dev

访问 http://localhost:5173

其他命令

# 类型检查
npm run type-check

# 代码检查
npm run lint

# 代码格式化
npm run format

# 构建生产版本
npm run build

# 预览生产构建
npm run preview

# 运行单元测试
npm run test:unit

# 运行 E2E 测试
npm run test:e2e

项目结构

frontend/
├── src/
│   ├── api/                 # API 接口封装
│   │   ├── generated/       # 自动生成的 API 类型
│   │   │   └── schema.ts    # TypeScript 类型定义
│   │   ├── client-axios.ts  # Axios API 客户端
│   │   └── axios.ts         # Axios 实例配置
│   ├── assets/              # 静态资源
│   │   ├── base.css         # 基础样式
│   │   └── main.css         # 主样式文件
│   ├── components/          # 公共组件
│   │   ├── __tests__/       # 组件测试
│   │   ├── ImageCarousel.vue        # 图片轮播
│   │   ├── ImageDetailDialog.vue    # 图片详情对话框
│   │   ├── PostDetailDialog.vue     # 帖子详情对话框
│   │   └── SaveMaterialDialog.vue   # 素材保存对话框
│   ├── composables/         # Vue 可组合函数
│   │   ├── usePosts.ts             # 帖子操作
│   │   ├── useFileUpload.ts        # 文件上传
│   │   ├── useCommentSystem.ts     # 评论系统
│   │   └── useUserProfile.ts       # 用户资料
│   ├── router/              # 路由配置
│   │   └── index.ts         # 路由定义和守卫
│   ├── stores/              # Pinia 状态管理
│   │   ├── user.ts          # 用户状态
│   │   └── editorParams.ts  # 编辑器参数
│   ├── types/               # TypeScript 类型定义
│   ├── utils/               # 工具函数
│   │   └── filetype.ts      # RAW 格式检测
│   ├── views/               # 页面组件
│   │   ├── LoginView.vue    # 登录页
│   │   ├── RegisterView.vue # 注册页
│   │   ├── Community.vue    # 社区主页
│   │   ├── Edit.vue         # 图片编辑页
│   │   ├── Mine.vue         # 个人主页
│   │   └── Post.vue         # 发帖组件
│   ├── App.vue              # 根组件
│   └── main.ts              # 应用入口
├── mock/                    # Mock 数据（MSW）
│   └── handlers.ts          # API 拦截器
├── e2e/                     # E2E 测试
├── public/                  # 静态资源
├── .prettierrc.json         # Prettier 配置
├── eslint.config.ts         # ESLint 配置
├── vite.config.ts           # Vite 配置
├── vitest.config.ts         # Vitest 配置
├── playwright.config.ts     # Playwright 配置
├── tsconfig.json            # TypeScript 配置
└── package.json             # 依赖和脚本

核心模块

1. 应用入口 (main.ts)

初始化 Vue 应用及相关插件：

Pinia 状态管理
Vue Router 路由
Element Plus UI 框架（中文本地化）
全局 Element Plus 图标

2. 根组件 (App.vue)

提供全局布局和样式，采用 Flexbox 布局防止横向滚动。

路由系统

路由配置

路径	名称	组件	说明
`/login`	Login	LoginView	登录页
`/register`	Register	RegisterView	注册页
`/`	-	-	重定向到 /community
`/community`	Community	Community	社区主页（需认证）
`/edit`	Edit	Edit	图片编辑页（需认证）
`/mine`	Mine	Mine	个人主页

路由守卫

基于 meta.requiresAuth 实现路由保护，未登录用户自动重定向到登录页。

状态管理

用户状态 (stores/user.ts)

使用 Pinia Composition API 风格管理：

Token 持久化（localStorage）
用户信息存储
登录/登出逻辑

API 集成

技术方案

Axios + openapi-typescript

✅ 成熟稳定的 HTTP 客户端
✅ 自动生成 TypeScript 类型
✅ 完全类型安全
✅ MSW 完全兼容
✅ 进度监听、请求取消
✅ 统一错误处理

使用示例

import apiClient from '@/api/client-axios'
import type { components } from '@/api/generated/schema'

type LoginRequest = components['schemas']['LoginRequest']

// 登录
const { data, error } = await apiClient.auth.login({
  username: 'john_doe',
  password: '12345678'
})

if (data) {
  const { token, user } = data
  localStorage.setItem('token', token)
}

开发工作流

编辑 API 规范：doc/api/shademarket-api.yaml
生成代码：npm run gen:api
使用 API：导入 apiClient 和类型
享受类型提示

详细文档请参考 API 集成指南

测试

测试策略

层级	工具	覆盖目标
单元测试	Vitest	核心（Utils, Composables, Stores）≥ 80%
集成测试	@testing-library/vue	关键组件 ≥ 60%
E2E 测试	Playwright	核心业务路径 100%

运行测试

# 单元测试
npm run test:unit

# E2E 测试
npm run test:e2e

# 测试覆盖率
npm run test:coverage

详细测试文档请参考：

前端测试文档

代码规范

ESLint 配置

使用 ESLint v9+ Flat Config 格式：

Vue 基础规则
Vue + TypeScript 推荐规则
Vitest 测试规则
Playwright E2E 规则
忽略自动生成的 API 代码

Prettier 配置

{
  "semi": false,
  "singleQuote": true,
  "printWidth": 100
}

类型检查

npm run type-check

构建部署

开发环境

npm run dev

生产构建

npm run build

输出到 dist/ 目录，可部署到任意静态服务器。

预览构建

npm run preview

环境变量

变量名	说明	默认值
`VITE_API_BASE_URL`	API 基础路径	`/api/v1`

NPM 脚本说明

{
  "dev": "vite",                           // 启动开发服务器
  "build": "run-p type-check build-only", // 构建生产版本
  "preview": "vite preview",               // 预览生产构建
  "test:unit": "vitest",                   // 单元测试
  "test:e2e": "playwright test",           // E2E 测试
  "build-only": "vite build",              // 仅构建
  "type-check": "vue-tsc --build",         // 类型检查
  "lint": "eslint . --fix",                // 代码检查
  "format": "prettier --write src/",       // 代码格式化
  "gen:api": "openapi-typescript ../doc/api/shademarket-api.yaml -o src/api/generated/schema.ts"
}

FilesExpand file tree

README.md

Latest commit

History