# ushop

**Repository Path**: xiaopinglongxia/ushop

## Basic Information

- **Project Name**: ushop
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-20
- **Last Updated**: 2026-03-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 贵香淳小程序 - 项目文档

> 技术栈：UniApp + Vue3 + TypeScript + Pinia + Vite

---

## 📚 目录

1. [项目概述](#项目概述)
2. [快速开始](#快速开始)
3. [项目结构](#项目结构)
4. [核心概念](#核心概念)
5. [开发规范](#开发规范)
6. [API 使用](#api-使用)
7. [常见问题](#常见问题)

---

## 项目概述

### 技术栈

| 技术 | 版本 | 说明 |
|------|------|------|
| UniApp | 3.x | 跨端开发框架 |
| Vue | 3.4.x | 前端框架 |
| TypeScript | 5.x | 类型系统 |
| Pinia | 2.1.x | 状态管理 |
| Vite | 5.x | 构建工具 |
| SCSS | - | CSS 预处理器 |

### 功能模块

- **首页**：商品推荐、分类入口、轮播图
- **分类**：商品分类浏览
- **购物车**：商品管理、结算
- **我的**：个人中心、订单管理、地址管理

---

## 快速开始

### 环境要求

- Node.js >= 18
- HBuilderX 或 VSCode
- 微信开发者工具

### 安装依赖

```bash
cd test/ushop
npm install
```

### 开发运行

```bash
# 微信小程序
npm run dev:mp-weixin

# H5
npm run dev:h5
```

### 构建发布

```bash
# 微信小程序
npm run build:mp-weixin

# H5
npm run build:h5
```

---

## 项目结构

```
src/
├── api/                    # API 接口
│   ├── auth.ts            # 认证相关
│   ├── goods.ts           # 商品相关
│   ├── order.ts           # 订单相关
│   ├── user.ts            # 用户相关
│   └── index.ts           # 统一导出
├── components/             # 公共组件
├── config/                 # 配置文件
│   └── index.ts           # 全局配置
├── hooks/                  # 组合式函数
│   ├── useCountdown.ts    # 倒计时
│   ├── useAuthPhone.ts    # 手机号授权
│   └── useList.ts         # 列表分页
├── pages/                  # 主包页面
│   ├── start/             # 启动页
│   ├── login/             # 登录页
│   ├── webview/           # WebView页
│   └── tabbar/            # TabBar页面
│       ├── home/          # 首页
│       ├── category/      # 分类
│       ├── cart/          # 购物车
│       └── mine/          # 我的
├── stores/                 # Pinia Store
│   ├── user.ts            # 用户状态
│   ├── app.ts             # 应用状态
│   ├── cart.ts            # 购物车状态
│   └── index.ts           # 统一导出
├── styles/                 # 全局样式
│   └── index.scss         # 样式入口
├── subpkg/                 # 分包
│   ├── goods/             # 商品相关
│   ├── order/             # 订单相关
│   └── user/              # 用户相关
├── types/                  # TypeScript 类型
│   └── index.ts           # 类型定义
├── utils/                  # 工具函数
│   ├── request.ts         # 请求封装
│   └── index.ts           # 工具函数
├── App.vue                 # 应用入口
├── main.ts                 # 主入口
└── pages.json              # 页面配置
```

---

## 核心概念

### 1. 状态管理 (Pinia)

#### User Store

```typescript
import { useUserStore } from '@/stores/user'

const userStore = useUserStore()

// 获取状态
const isLoggedIn = userStore.isLoggedIn
const userInfo = userStore.userInfo

// 调用 Action
await userStore.loginAction({ code: 'xxx' })
userStore.logout()
```

#### App Store

```typescript
import { useAppStore } from '@/stores/app'

const appStore = useAppStore()

// 设置全局参数
appStore.setGlobalParams({ storeId: '123' })

// 获取主题色
const theme = appStore.themeColor.primary
```

#### Cart Store

```typescript
import { useCartStore } from '@/stores/cart'

const cartStore = useCartStore()

// 添加商品
cartStore.addItem(product, 1)

// 获取总价
const total = cartStore.totalPrice
```

### 2. 请求封装

```typescript
import { request, get, post } from '@/utils/request'

// 通用请求
const res = await request({
  url: '/api/goods',
  method: 'GET',
  data: { pageNum: 1 }
})

// 快捷方法
const data = await get('/api/goods', { pageNum: 1 })
const result = await post('/api/order', { productId: 'xxx' })
```

### 3. 组合式函数 (Hooks)

#### useCountdown - 倒计时

```typescript
import { useCountdown } from '@/hooks/useCountdown'

const { formatted, start, stop } = useCountdown({
  seconds: 60,
  autoStart: true,
  onComplete: () => console.log('倒计时结束')
})
```

#### useList - 列表分页

```typescript
import { useList } from '@/hooks/useList'

const { list, loading, finished, loadMore, refresh } = useList({
  fetchFn: ({ pageNum, pageSize }) => fetchGoodsList({ pageNum, pageSize }),
  pageSize: 10,
  immediate: true
})
```

### 4. 工具函数

```typescript
import { 
  showToast, 
  showLoading, 
  validatePhone, 
  formatPhone,
  copyText,
  previewImage 
} from '@/utils'

// 显示提示
showToast({ title: '操作成功', icon: 'success' })

// 验证手机号
const isValid = validatePhone('13800138000')

// 格式化手机号
const masked = formatPhone('13800138000') // 138****8000
```

---

## 开发规范

### 1. 文件命名

- 组件：PascalCase，如 `UserCard.vue`
- 页面：kebab-case，如 `user-profile/index.vue`
- 工具函数：camelCase，如 `formatDate.ts`
- Store：camelCase，如 `userStore.ts`

### 2. 代码风格

```vue
<template>
  <!-- 使用双引号 -->
  <view class="container">
    <!-- 事件使用 @ -->
    <button @click="handleClick">点击</button>
  </view>
</template>

<script setup lang="ts">
// 类型导入放最前面
import type { UserInfo } from '@/types'

// 然后导入 Vue 相关
import { ref, computed } from 'vue'

// 然后导入组件/工具
import { useUserStore } from '@/stores/user'

// 定义 Props
interface Props {
  userId: string
  showAvatar?: boolean
}
const props = withDefaults(defineProps<Props>(), {
  showAvatar: true
})

// 定义 Emits
const emit = defineEmits<{
  click: [id: string]
}>()

// 响应式数据
const count = ref(0)

// 计算属性
const doubled = computed(() => count.value * 2)

// 方法
const handleClick = () => {
  count.value++
  emit('click', props.userId)
}
</script>

<style lang="scss" scoped>
// 使用 SCSS
.container {
  padding: 30rpx;
  
  .title {
    font-size: 32rpx;
    color: #333;
  }
}
</style>
```

### 3. 类型定义

```typescript
// 所有类型定义在 types/index.ts
export interface UserInfo {
  userId: string
  userName: string
  avatar: string
  mobile: string
  userType: number
}

// 组件中使用
cost userInfo = ref<UserInfo | null>(null)
```

### 4. API 定义

```typescript
// api/user.ts
import { request } from '@/utils/request'
import type { ApiResponse, UserInfo } from '@/types'

/**
 * 获取用户信息
 * @param userId 用户ID
 */
export const fetchUserInfo = (userId: string): Promise<ApiResponse<UserInfo>> => {
  return request({
    url: '/mini/user/info',
    method: 'GET',
    data: { userId }
  })
}
```

---

## API 使用

### 认证相关

```typescript
import { login, refreshToken, authPhoneNumber } from '@/api/auth'

// 登录
const res = await login({ code: 'wx_code' })

// 刷新 Token
await refreshToken()

// 手机号授权
await authPhoneNumber({ code, encryptedData, iv })
```

### 商品相关

```typescript
import { fetchGoodsList, fetchGoodsDetail } from '@/api/goods'

// 获取商品列表
const { list, total } = await fetchGoodsList({ pageNum: 1, pageSize: 10 })

// 获取商品详情
const detail = await fetchGoodsDetail({ productId: 'xxx' })
```

### 订单相关

```typescript
import { createOrder, fetchOrderList, payOrder } from '@/api/order'

// 创建订单
const { orderId } = await createOrder({
  productId: 'xxx',
  quantity: 1,
  addressId: 'xxx'
})

// 支付
await payOrder({ orderId })
```

---

## 常见问题

### 1. 如何添加新页面？

1. 在 `src/pages` 或 `src/subpkg` 创建页面目录
2. 在 `src/pages.json` 中配置页面路径
3. 如果是分包，需要在 `subPackages` 中配置

### 2. 如何添加新的 API？

1. 在 `src/api` 目录下创建或修改对应文件
2. 使用 `request` 函数封装请求
3. 在 `src/types/index.ts` 添加返回类型
4. 在 `src/api/index.ts` 导出

### 3. 如何使用全局状态？

```typescript
// 在组件中使用
import { useUserStore, useAppStore } from '@/stores'

const userStore = useUserStore()
const appStore = useAppStore()

// 读取状态
console.log(userStore.isLoggedIn)

// 调用 Action
userStore.setUserInfo({ userName: '张三' })
```

### 4. 如何调试？

- **H5**: 浏览器开发者工具
- **微信小程序**: 微信开发者工具
- **App**: HBuilderX 真机调试

### 5. 如何发布？

1. 执行构建命令
2. 微信小程序：导入 `dist/build/mp-weixin` 到微信开发者工具
3. 上传代码并提交审核

---

## 更新日志

### v1.0.0 (2024-03-20)

- ✨ 项目初始化
- ✨ 完成基础架构搭建
- ✨ 完成首页、分类、购物车、我的页面
- ✨ 集成 Pinia 状态管理
- ✨ 完成请求封装

---

## 联系方式

如有问题，请联系开发团队。

---

*文档版本：v1.0.0*  
*最后更新：2024-03-20*