Project.Fengling.QoderVersion/docs/frontend/C端功能文档.md

# 一物一码会员营销系统 - C端功能文档

## 项目概述

这是一套基于Vue 3 + TypeScript + Vite + Tailwind CSS构建的一物一码会员营销系统C端应用，提供完整的移动端会员服务体验。

## 技术栈

- **框架**: Vue 3 Composition API
- **语言**: TypeScript
- **构建工具**: Vite
- **CSS框架**: Tailwind CSS
- **状态管理**: Pinia
- **路由**: Vue Router 4
- **HTTP客户端**: Axios
- **UI组件**: Lucide Vue Icons
- **通知**: Vue Sonner

## 功能模块

### 1. 用户认证系统

#### 登录注册
- 手机号验证码登录/注册
- JWT Token认证机制
- Token自动刷新和持久化
- 路由守卫保护

#### 相关文件
```
src/pages/auth/Login.vue
src/pages/auth/Register.vue
src/stores/member.ts
src/services/api.ts
```

### 2. 首页 (Home)

#### 功能特性
- 会员信息展示（积分、等级）
- 快捷功能入口
- 最近活动展示
- 响应式移动端设计

#### 页面结构
```vue
<UserLayout>
  <Header />
  <div class="px-4 pt-4">
    <!-- 会员欢迎区域 -->
    <!-- 快捷功能网格 -->
    <!-- 最近活动列表 -->
  </div>
</UserLayout>
```

### 3. 积分商城 (Mall)

#### 商品浏览
- 商品分类筛选
- 商品搜索功能
- 商品详情展示
- 积分价格显示

#### 购物车功能
- 商品加入购物车
- 购物车商品管理
- 数量调整
- 商品选择/取消选择
- 全选功能
- 积分实时计算

#### 相关文件
```
src/pages/mall/GiftList.vue    # 商品列表
src/pages/mall/GiftDetail.vue  # 商品详情
src/pages/mall/Cart.vue        # 购物车
src/pages/mall/Checkout.vue    # 确认订单
```

### 4. 个人中心 (Profile)

#### 个人信息
- 会员基本信息展示
- 积分统计概览
- 会员等级显示

#### 功能菜单
- 积分明细查看
- 我的订单管理
- 账户设置
- 退出登录

#### 相关文件
```
src/pages/profile/Profile.vue  # 个人中心主页
src/pages/profile/Points.vue   # 积分明细
```

### 5. 订单管理 (Orders)

#### 订单列表
- 订单状态筛选（待发货、已发货、已完成、已取消）
- 订单基本信息展示
- 订单操作（取消、确认收货）

#### 订单详情
- 详细订单信息
- 物流跟踪信息
- 收货地址展示

#### 相关文件
```
src/pages/orders/OrderList.vue    # 订单列表
src/pages/orders/OrderDetail.vue  # 订单详情
```

### 6. 积分明细 (Points)

#### 功能特性
- 积分收支记录展示
- 按类型筛选（收入/支出）
- 时间维度统计
- 积分规则说明

### 7. 扫码积分 (Scan)

#### 功能特性
- 营销码扫描功能
- 积分奖励发放
- 扫描历史记录

## 组件架构

### 布局组件
```
src/components/layout/
├── UserLayout.vue    # 用户页面通用布局
├── Header.vue        # 顶部导航栏
└── BottomNav.vue     # 底部导航栏
```

### UI组件
```
src/components/ui/
├── Button.vue        # 按钮组件
├── Input.vue         # 输入框组件
└── Toast.vue         # 消息提示组件
```

## 路由配置

```typescript
const routes = [
  { path: '/', redirect: '/home' },
  { path: '/home', component: Home, meta: { requiresAuth: true } },
  { path: '/login', component: Login, meta: { guestOnly: true } },
  { path: '/register', component: Register, meta: { guestOnly: true } },
  { path: '/profile', component: Profile, meta: { requiresAuth: true } },
  { path: '/points', component: Points, meta: { requiresAuth: true } },
  { path: '/mall', component: GiftList, meta: { requiresAuth: true } },
  { path: '/cart', component: Cart, meta: { requiresAuth: true } },
  { path: '/checkout', component: Checkout, meta: { requiresAuth: true } },
  { path: '/orders', component: OrderList, meta: { requiresAuth: true } },
  { path: '/scan', component: Scan, meta: { requiresAuth: true } }
]
```

## 状态管理

### Member Store
```typescript
interface MemberState {
  isAuthenticated: boolean
  token: string | null
  memberInfo: MemberInfo | null
}

// 主要方法
- login(credentials): Promise<void>
- register(data): Promise<void>  
- logout(): void
- fetchMemberInfo(): Promise<void>
```

## API服务

### 认证相关
```typescript
// 登录
POST /api/members/login
// 注册
POST /api/members/register
// 获取当前会员信息
GET /api/members/me
```

### 商城相关
```typescript
// 获取商品列表
GET /api/gifts
// 获取商品详情
GET /api/gifts/{id}
// 创建订单
POST /api/orders
```

## 样式规范

### 响应式设计
- 移动优先的设计理念
- 使用Tailwind CSS的响应式工具类
- 适配各种移动设备屏幕尺寸

### 颜色主题
```css
/* 主色调 */
blue-500: #3b82f6    /* 主要按钮 */
yellow-500: #f59e0b  /* 积分相关 */
green-500: #10b981   /* 成功状态 */
red-500: #ef4444     /* 错误/危险 */

/* 背景色 */
white: #ffffff       /* 卡片背景 */
gray-50: #f9fafb     /* 页面背景 */
```

### 组件间距
- 使用Tailwind的spacing scale (p-4, m-4, gap-4等)
- 保持一致的视觉节奏

## 开发规范

### 代码组织
```
src/
├── pages/           # 页面组件
├── components/      # 可复用组件
├── stores/          # 状态管理
├── services/        # API服务
├── router/          # 路由配置
├── composables/     # 组合式函数
└── types/           # TypeScript类型定义
```

### 命名约定
- 组件文件名：PascalCase (UserProfile.vue)
- 组合式函数：use开头 (useAuth.ts)
- 存储文件：描述性名称 (member.ts)
- 路由路径：kebab-case (/user-profile)

### TypeScript最佳实践
- 为所有props定义类型
- 使用接口定义复杂对象结构
- 合理使用泛型
- 启用严格模式

## 部署配置

### 环境变量
```bash
# .env.development
VITE_API_BASE_URL=http://localhost:5000

# .env.production  
VITE_API_BASE_URL=https://api.yourdomain.com
```

### 构建命令
```bash
# 开发环境
pnpm dev

# 生产构建
pnpm build

# 预览构建结果
pnpm preview
```

## 测试要点

### 功能测试
1. 用户认证流程（登录/注册/退出）
2. 商品浏览和购物车操作
3. 订单创建和管理流程
4. 积分查询和明细查看
5. 个人中心功能完整性

### 兼容性测试
- iOS Safari
- Android Chrome
- 微信内置浏览器
- 各种屏幕尺寸适配

## 性能优化

### 加载优化
- 代码分割和懒加载
- 图片懒加载
- 骨架屏加载状态
- 缓存策略优化

### 用户体验
- 平滑的过渡动画
- 及时的操作反馈
- 合理的加载状态提示
- 错误处理和重试机制

## 安全考虑

### 认证安全
- JWT Token加密存储
- 请求拦截器添加Authorization头
- 敏感操作二次确认
- 会话超时处理

### 数据安全
- XSS防护
- CSRF保护
- 输入验证和过滤
- HTTPS强制使用

---

*文档最后更新：2024年*
*版本：1.0.0*