# mall-web

**Repository Path**: wufengsheng/mall-web

## Basic Information

- **Project Name**: mall-web
- **Description**: 基于 Next.js 16 的多语言国际化电商前端项目，支持 10 种语言，集成 Mock 数据调试工具。
- **Primary Language**: TypeScript
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-26
- **Last Updated**: 2026-05-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Mall Web

基于 Next.js 16 的多语言国际化电商前端项目，支持 10 种语言，集成 Mock 数据调试工具。

- NextJS 文档：[https://www.nextjs.cn/docs](https://www.nextjs.cn/docs)
- React 文档：[https://www.reactjs.cn/](https://www.reactjs.cn/)
- Shadcn UI 文档：[https://www.shadcn-ui.cn/](https://www.shadcn-ui.cn/)
- TailwindCSS 文档：[https://tailwindcss.com/plus/ui-blocks](https://tailwindcss.com/plus/ui-blocks)
- next-intl 文档：[https://next-intl.dev/docs/getting-started](https://next-intl.dev/docs/getting-started)


## 技术栈

| 类别 | 技术 | 版本 |
|------|------|------|
| 框架 | Next.js (App Router + Turbopack) | 16.2.6 |
| UI 库 | React | 19.2 |
| 语言 | TypeScript | 5.x |
| 样式 | Tailwind CSS + tw-animate-css | 4.x |
| 组件库 | shadcn/ui (base-nova 风格) | 4.x |
| 基元组件 | @base-ui/react | 1.5 |
| 国际化 | next-intl | 4.12 |
| 数据请求 | TanStack React Query | 5.x |
| 表单 | react-hook-form + zod | 7.x / 4.x |
| 状态管理 | Zustand | 5.x |
| 轮播 | embla-carousel-react + autoplay | 8.x |
| 图标 | lucide-react | 1.x |
| Mock | MSW + @faker-js/faker | 2.x / 10.x |
| 工具 | clsx + tailwind-merge + class-variance-authority | — |

## 快速开始

```bash
# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 生产构建
npm run build

# 代码检查
npm run lint
```

启动后访问 `http://localhost:3000`，默认重定向到 `/en`。

## 国际化

支持 **10 种语言**，语言前缀路由（`/en`、`/zh`、`/ja` ...）：

| 代码 | 语言 | 币种 |
|------|------|------|
| `en` | English | USD ($) |
| `zh` | 简体中文 | CNY (¥) |
| `zh-TW` | 繁體中文 | TWD (NT$) |
| `ja` | 日本語 | JPY (¥) |
| `ko` | 한국어 | KRW (₩) |
| `fr` | Français | EUR (€) |
| `de` | Deutsch | EUR (€) |
| `ru` | Русский | RUB (₽) |
| `es` | Español | EUR (€) |
| `ar` | العربية | AED (د.إ) |

- 翻译文件：`src/messages/{locale}.json`
- 语言配置：`src/config.ts`
- 货币配置：`src/lib/currency.ts`（含市场价格系数和格式化）
- 中间件路由：`middleware.ts`

## Mock 调试工具

基于 **MSW (Mock Service Worker)** 拦截请求，开发时无需后端。

```bash
# .env.local 中控制开关
NEXT_PUBLIC_MOCK_ENABLED=true   # 启用 Mock
NEXT_PUBLIC_MOCK_ENABLED=false  # 关闭，使用真实 API
```

**可用 Mock API：**

| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/products` | GET | 产品列表（支持 `?page&pageSize&category`） |
| `/api/products/:id` | GET | 产品详情 |
| `/api/products` | POST | 创建产品 |
| `/api/user/profile` | GET | 用户信息 |
| `/api/user/login` | POST | 模拟登录 |
| `/api/user/logout` | POST | 模拟登出 |
| `/api/cart` | GET / POST | 购物车操作 |
| `/api/cart/:id` | DELETE | 移除购物车单品 |
| `/api/contact` | POST | 提交联系表单 |

## 目录结构

```
src/
├── app/                          # Next.js App Router 路由
│   ├── page.tsx                  # 根页面 → 重定向到默认语言
│   └── [locale]/                 # 语言路由
│       ├── layout.tsx            # 根布局（字体、i18n Provider、QueryProvider、MswProvider）
│       ├── page.tsx              # 首页（Home）
│       ├── about/page.tsx        # 关于页
│       ├── contact/page.tsx      # 联系页
│       └── products/page.tsx     # 产品列表页
│
├── components/
│   ├── ui/                       # shadcn/ui 基础组件
│   │   ├── button.tsx
│   │   ├── card.tsx
│   │   ├── carousel.tsx
│   │   ├── dropdown-menu.tsx
│   │   ├── input.tsx
│   │   ├── sheet.tsx
│   │   └── skeleton.tsx
│   ├── layout/                   # 布局组件
│   │   ├── navbar.tsx            # 顶部导航（语言切换 + 移动端菜单）
│   │   └── footer.tsx            # 页脚
│   ├── home/                     # 首页组件
│   │   ├── hero.tsx              # 轮播 Banner
│   │   ├── featured-products.tsx # 精选产品
│   │   └── product-card.tsx      # 产品卡片（含货币格式化）
│   ├── about/
│   │   └── about-content.tsx     # 关于页内容
│   ├── contact/
│   │   └── contact-content.tsx   # 联系表单 + 信息卡
│   └── products/
│       └── products-content.tsx  # 产品列表（分类筛选 + 分页）
│
├── hooks/                        # 自定义 Hooks
│   ├── use-products.ts           # 产品列表/详情（React Query）
│   └── use-user.ts               # 用户信息/登录/登出
│
├── mocks/                        # MSW Mock 数据
│   ├── browser.ts                # 浏览器端 Worker 启动
│   ├── utils.ts                  # 模拟延迟、分页类型
│   ├── data/                     # Faker 数据生成器
│   │   ├── products.ts
│   │   └── user.ts
│   └── handlers/                 # API Handler
│       ├── index.ts              # 聚合入口
│       ├── products.ts           # 产品 CRUD
│       ├── user.ts               # 用户认证
│       ├── cart.ts               # 购物车
│       └── contact.ts            # 联系表单
│
├── providers/                    # 全局 Provider
│   ├── query-provider.tsx        # TanStack React Query
│   └── msw-provider.tsx          # MSW 条件启用
│
├── stores/                       # Zustand 状态
│   └── user-store.ts
│
├── i18n/
│   └── request.ts                # next-intl 服务端配置
│
├── lib/                          # 工具库
│   ├── utils.ts                  # cn() 类名合并
│   ├── types.ts                  # 公共类型 (Product)
│   └── currency.ts               # 货币映射 + 市场价格转换 + 格式化
│
├── messages/                     # 国际化翻译文件（10 种语言）
│   ├── en.json  zh.json  zh-TW.json  ja.json  ko.json
│   ├── fr.json  de.json  ru.json  es.json  ar.json
│
└── config.ts                     # 语言和默认语言配置
```

## 项目特性

- **10 种语言**完整国际化，语言切换保留当前路径
- **按市场定价**，同一产品在不同语言下显示不同币种和价格
- **MSW Mock** 开发环境拦截请求，关闭即切真实 API
- **React Query** 数据缓存、分页、Loading/Error 状态管理
- **响应式设计**，移动端抽屉菜单、分类栏自适应图标/文字
- **shadcn/ui v4** 组件，基于 @base-ui/react 基元，完整 ARIA 可访问性
- **轮播 Banner** 自动播放，键盘导航支持
- **产品列表**分类筛选 + 分页 + 骨架屏加载态