<div align="center">
  <h1>🚀 WebSoft 小程序</h1>
  <p><strong>基于 Taro + React + TypeScript 的跨平台小程序应用</strong></p>

  <p>
    <img src="https://img.shields.io/badge/Taro-4.0.8-blue" alt="Taro">
    <img src="https://img.shields.io/badge/React-18.3.1-61DAFB" alt="React">
    <img src="https://img.shields.io/badge/TypeScript-5.7.2-3178C6" alt="TypeScript">
    <img src="https://img.shields.io/badge/NutUI-3.0.16-orange" alt="NutUI">
    <img src="https://img.shields.io/badge/TailwindCSS-3.4.17-38B2AC" alt="TailwindCSS">
    <img src="https://img.shields.io/badge/License-MIT-blue" alt="License">
  </p>
</div>

## 📖 项目简介

WebSoft 小程序是一个基于 **Taro + React + TypeScript** 构建的现代化跨平台小程序应用，支持多端发布：

- **核心框架**：Taro 4.0.8 + React 18.3.1 + TypeScript 5.7.2
- **UI组件库**：NutUI React Taro 2.7.4 + NutUI Icons
- **样式方案**：Sass + TailwindCSS 3.4.17
- **状态管理**：React Hooks + Context API
- **工具库**：Day.js、Crypto-js、React Router DOM

## 🎯 支持平台

本项目基于 Taro 框架，支持一套代码多端运行：

- **微信小程序** (weapp)
- **支付宝小程序** (alipay)
- **百度智能小程序** (swan)
- **字节跳动小程序** (tt)
- **QQ小程序** (qq)
- **京东小程序** (jd)
- **H5网页** (h5)
- **React Native** (rn)
- **快应用** (quickapp)



## 项目演示
| 后台管理系统 | https://mp.websoft.top                                                                                                              |
|--------|-------------------------------------------------------------------------------------------------------------------------------------|
| 演示账号   | 请联系开发者获取演示账号
| 正式账号 | [立即注册](https://mp.websoft.top/register/?inviteCode=github)                                                                          |
| 关注公众号  | ![输入图片说明](https://oss.wsdns.cn/20240327/f1175cc5aae741d3af05484747270bd5.jpeg?x-oss-process=image/resize,m_fixed,w_150/quality,Q_90) |




## 🛠️ 技术栈

### 核心框架
| 技术 | 版本 | 说明 |
|------|------|------|
| Taro | 4.0.8 | 跨平台开发框架 |
| React | 18.3.1 | 前端UI框架 |
| TypeScript | 5.7.2 | 类型安全的JavaScript |
| Webpack | 5.78.0 | 模块打包工具 |
| Babel | 7.26.0 | JavaScript编译器 |
| PostCSS | 8.4.49 | CSS后处理器 |
| ESLint | 8.57.1 | 代码质量检查 |

### UI组件库
| 技术 | 版本 | 说明 |
|------|------|------|
| NutUI React Taro | 2.7.4 | 移动端组件库 |
| NutUI Icons | 2.0.1 | 图标库 |
| NutUI Biz | 1.0.0-beta.2 | 业务组件库 |

### 样式方案
| 技术 | 版本 | 说明 |
|------|------|------|
| Sass | - | CSS预处理器 |
| TailwindCSS | 3.4.17 | 原子化CSS框架 |
| Autoprefixer | 10.4.20 | CSS自动前缀 |

### 功能组件
- **React Router DOM** - 路由管理
- **Day.js** - 日期时间处理
- **Crypto-js** - 加密解密工具
- **js-base64** - Base64编码解码
- **React Markdown** - Markdown渲染
- **ECharts Taro3 React** - 图表组件

## 📋 环境要求

### 基础环境
- 📦 **Node.js 16+**
- 📱 **微信开发者工具** (开发微信小程序)
- 🔧 **支付宝开发者工具** (开发支付宝小程序)
- 🌐 **现代浏览器** (开发H5应用)

### 包管理器
- **npm** / **yarn** / **pnpm** (推荐使用pnpm)

### 开发工具
- **推荐**：VS Code / WebStorm
- **插件**：ES7+ React/Redux/React-Native snippets、TypeScript Importer

## 🚀 快速开始

### 1. 克隆项目
```bash
git clone https://github.com/websoft-top/mp-taro.git
cd mp-taro
```

### 2. 安装依赖
```bash
# 使用 pnpm (推荐)
pnpm install

# 或使用 npm
npm install

# 或使用 yarn
yarn install
```

### 3. 配置开发环境

#### 环境变量配置
项目支持多环境配置，通过 `config/env.ts` 文件管理不同环境的配置：

```typescript
// config/env.ts
export const ENV_CONFIG = {
  // 开发环境
  development: {
    API_BASE_URL: 'http://localhost:3000/api',
    APP_NAME: 'Taro App Dev',
    DEBUG: 'true',
  },
  // 生产环境
  production: {
    API_BASE_URL: 'https://api.example.com',
    APP_NAME: 'Taro App',
    DEBUG: 'false',
  },
  // 测试环境
  test: {
    API_BASE_URL: 'https://test-api.example.com',
    APP_NAME: 'Taro App Test',
    DEBUG: 'true',
  }
}
```

#### 应用配置
编辑 `config/app.ts` 文件，配置租户ID等信息：
```typescript
export const TenantId = 'your_tenant_id'
export const BaseUrl = API_BASE_URL  // 自动从环境配置读取
```

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

#### 微信小程序开发
```bash
# 开发环境（默认）
npm run dev:weapp

# 生产环境
NODE_ENV=production npm run dev:weapp

# 测试环境
NODE_ENV=test npm run dev:weapp
```
然后使用微信开发者工具打开 `dist` 目录

#### H5开发
```bash
# 启动H5开发模式
npm run dev:h5
```
访问 `http://localhost:10086` 查看H5版本

#### 其他平台
```bash
# 支付宝小程序
npm run dev:alipay

# 百度智能小程序
npm run dev:swan

# 字节跳动小程序
npm run dev:tt

# QQ小程序
npm run dev:qq

# 京东小程序
npm run dev:jd
```

## ⚙️ 配置说明

### 项目配置
主要配置文件位于 `config/` 目录：

- `config/index.ts` - Taro主配置文件
- `config/dev.ts` - 开发环境配置
- `config/prod.ts` - 生产环境配置
- `config/env.ts` - 环境变量配置（新增）
- `config/app.ts` - 应用配置（API地址、租户ID等）

### 环境变量配置
项目支持多环境配置，在 `config/env.ts` 中管理：

```typescript
// 环境变量配置
export const ENV_CONFIG = {
  development: {
    API_BASE_URL: 'http://localhost:3000/api',
    APP_NAME: 'Taro App Dev',
    DEBUG: 'true',
  },
  production: {
    API_BASE_URL: 'https://api.example.com',
    APP_NAME: 'Taro App',
    DEBUG: 'false',
  },
  test: {
    API_BASE_URL: 'https://test-api.example.com',
    APP_NAME: 'Taro App Test',
    DEBUG: 'true',
  }
}

// 获取当前环境配置
export function getEnvConfig() {
  const env = process.env.NODE_ENV || 'development'
  if (env === 'production') {
    return ENV_CONFIG.production
  } else if (env === 'test') {
    return ENV_CONFIG.test
  } else {
    return ENV_CONFIG.development
  }
}

// 导出环境变量
export const { API_BASE_URL, APP_NAME, DEBUG } = getEnvConfig()
```

### 应用配置
在 `config/app.ts` 中配置：
```typescript
import { API_BASE_URL } from './env'

// 租户ID
export const TenantId = 'your_tenant_id'

// API基础地址（自动从环境配置读取）
export const BaseUrl = API_BASE_URL

// 其他配置...
```

### 环境切换
通过设置 `NODE_ENV` 环境变量来切换不同环境：

```bash
# 开发环境（默认）
npm run dev:weapp

# 生产环境
NODE_ENV=production npm run dev:weapp

# 测试环境
NODE_ENV=test npm run dev:weapp
```

## 🌍 环境变量详细说明

### 环境变量文件结构
```
config/
├── env.ts               # 环境变量配置文件
├── app.ts               # 应用配置（使用环境变量）
└── index.ts             # Taro配置（注入环境变量）
```

### 支持的环境变量
| 变量名 | 说明 | 开发环境默认值 | 生产环境建议值 |
|--------|------|---------------|---------------|
| `API_BASE_URL` | API基础地址 | `http://localhost:3000/api` | `https://api.yourdomain.com/api` |
| `APP_NAME` | 应用名称 | `Taro App Dev` | `Your App Name` |
| `DEBUG` | 调试模式 | `true` | `false` |

### 环境变量使用方法

#### 1. 修改环境配置
编辑 `config/env.ts` 文件：
```typescript
export const ENV_CONFIG = {
  development: {
    API_BASE_URL: 'http://localhost:3000/api',  // 修改为你的开发环境API地址
    APP_NAME: 'My App Dev',
    DEBUG: 'true',
  },
  production: {
    API_BASE_URL: 'https://api.yourdomain.com/api',  // 修改为你的生产环境API地址
    APP_NAME: 'My App',
    DEBUG: 'false',
  }
}
```

#### 2. 在代码中使用环境变量
```typescript
// 在 config/app.ts 中
import { API_BASE_URL, APP_NAME, DEBUG } from './env'

export const BaseUrl = API_BASE_URL
export const AppName = APP_NAME
export const IsDebug = DEBUG === 'true'

// 在其他文件中使用
import { BaseUrl } from '@/config/app'
console.log('API地址:', BaseUrl)
```

#### 3. 运行时环境切换
```bash
# 开发环境（默认）
npm run dev:weapp

# 生产环境
NODE_ENV=production npm run dev:weapp

# 测试环境
NODE_ENV=test npm run dev:weapp

# 构建生产版本
NODE_ENV=production npm run build:weapp
```

### 环境变量最佳实践

1. **敏感信息处理**：不要在代码中硬编码敏感信息，使用环境变量管理
2. **环境隔离**：确保不同环境使用不同的API地址和配置
3. **默认值设置**：为所有环境变量提供合理的默认值
4. **类型安全**：使用TypeScript确保环境变量的类型安全

### 路径别名配置
项目已配置路径别名，可以使用以下方式导入：
```typescript
import Component from '@/components/Component'
import { request } from '@/utils/request'
import { useCart } from '@/hooks/useCart'
import config from '@/config/app'
```

### 样式配置
- **Sass**: 支持嵌套、变量、混入等特性
- **TailwindCSS**: 原子化CSS，配置文件为 `tailwind.config.js`
- **PostCSS**: 自动处理CSS兼容性，配置文件为 `postcss.config.js`

## 🎯 核心功能

### 🔐 用户认证与授权
- **微信登录**：基于微信OpenID的用户认证
- **短信登录**：支持手机号短信验证登录
- **用户注册**：完整的用户注册流程
- **密码找回**：支持手机号找回密码

### 📝 内容管理系统(CMS)
- **文章浏览**：支持文章列表和详情查看
- **分类管理**：内容分类浏览
- **富文本渲染**：支持Markdown内容渲染
- **媒体展示**：图片、视频等媒体文件展示

### 🛒 电商系统
- **商品展示**：商品列表、详情、分类浏览
- **购物车**：商品加入购物车、数量管理
- **订单管理**：订单创建、查看、状态跟踪
- **地址管理**：收货地址的增删改查
- **支付集成**：支持微信支付等支付方式

### 👤 用户中心
- **个人资料**：用户信息查看和编辑
- **实名认证**：用户身份验证功能
- **帮助中心**：常见问题和帮助文档
- **关于我们**：应用介绍和联系方式
- **设置中心**：个人偏好设置

### 📊 数据可视化
- **图表展示**：基于ECharts的数据可视化
- **统计分析**：业务数据统计展示
- **实时更新**：动态数据更新

## 🏗️ 项目结构

```
src/
├── app.config.ts           # 应用配置文件
├── app.scss               # 全局样式
├── app.ts                 # 应用入口文件
├── api/                   # API接口定义
│   ├── cms/              # 内容管理相关API
│   ├── shop/             # 商城相关API
│   ├── system/           # 系统相关API
│   ├── passport/         # 用户认证相关API
│   └── index.ts          # API统一导出
├── assets/               # 静态资源
│   └── tabbar/          # 底部导航图标
├── components/           # 公共组件
│   ├── Header.tsx       # 页面头部组件
│   ├── TabBar.tsx       # 底部导航组件
│   ├── GoodsList.tsx    # 商品列表组件
│   └── ...
├── hooks/                # 自定义Hooks
│   └── useCart.ts       # 购物车Hook
├── pages/                # 页面文件
│   ├── index/           # 首页
│   ├── cart/            # 购物车页面
│   ├── order/           # 订单页面
│   └── user/            # 用户中心页面
├── passport/             # 用户认证页面
│   ├── login.tsx        # 登录页面
│   ├── register.tsx     # 注册页面
│   └── ...
├── cms/                  # 内容管理页面
│   ├── category/        # 分类页面
│   └── detail/          # 详情页面
├── shop/                 # 商城页面
│   ├── category/        # 商品分类
│   ├── goodsDetail/     # 商品详情
│   ├── orderConfirm/    # 订单确认
│   └── orderDetail/     # 订单详情
├── user/                 # 用户相关页面
│   ├── profile/         # 个人资料
│   ├── address/         # 地址管理
│   ├── setting/         # 设置
│   └── ...
└── utils/                # 工具函数
    ├── request.ts       # 网络请求封装
    ├── common.ts        # 通用工具函数
    ├── time.ts          # 时间处理工具
    └── server.ts        # 服务端相关工具

config/                   # 配置文件目录
├── index.ts             # Taro主配置
├── dev.ts               # 开发环境配置
├── prod.ts              # 生产环境配置
├── env.ts               # 环境变量配置
└── app.ts               # 应用配置

types/                    # 类型定义
└── global.d.ts          # 全局类型定义
```

## 🔧 开发规范

### 代码结构
- **Pages**：页面组件，负责页面逻辑和UI展示
- **Components**：公共组件，可复用的UI组件
- **Hooks**：自定义Hooks，封装业务逻辑
- **Utils**：工具函数，通用的功能函数
- **API**：接口定义，与后端API的交互

### 命名规范
- **组件名**：使用大驼峰命名法（PascalCase）
- **文件名**：使用小驼峰命名法（camelCase）或短横线命名法（kebab-case）
- **变量名**：使用小驼峰命名法（camelCase）
- **常量**：使用全大写，下划线分隔
- **CSS类名**：使用短横线命名法（kebab-case）

### TypeScript规范
- 优先使用接口（interface）定义类型
- 为函数参数和返回值添加类型注解
- 使用泛型提高代码复用性
- 避免使用 `any` 类型

## 📚 构建与部署

### 构建命令
```bash
# 构建微信小程序
npm run build:weapp

# 构建H5应用
npm run build:h5

# 构建支付宝小程序
npm run build:alipay

# 构建其他平台
npm run build:swan    # 百度智能小程序
npm run build:tt      # 字节跳动小程序
npm run build:qq      # QQ小程序
npm run build:jd      # 京东小程序
```

### 主要API模块
项目API按功能模块组织：

- **用户认证**: `src/api/passport/` - 登录、注册、权限验证
- **用户管理**: `src/api/system/user/` - 用户信息管理
- **内容管理**: `src/api/cms/` - 文章、媒体文件管理
- **商城管理**: `src/api/shop/` - 商品、订单管理
- **系统管理**: `src/api/system/` - 系统配置、参数管理

## 🚀 部署指南

### 微信小程序部署
1. 构建小程序代码：
   ```bash
   npm run build:weapp
   ```
2. 使用微信开发者工具打开 `dist` 目录
3. 点击"上传"按钮，上传代码到微信后台
4. 在微信公众平台提交审核

### H5应用部署
1. 构建H5应用：
   ```bash
   npm run build:h5
   ```
2. 将 `dist` 目录下的文件上传到Web服务器
3. 配置Nginx或Apache服务器
4. 确保HTTPS访问（微信要求）

### 其他平台部署
各平台部署流程类似，构建对应平台代码后，使用相应的开发者工具上传即可。

### 生产环境配置
在生产环境中，需要修改相关配置：

1. **环境变量配置**：修改 `config/env.ts` 中的生产环境配置
   ```typescript
   production: {
     API_BASE_URL: 'https://your-production-api.com/api',
     APP_NAME: 'Your App Name',
     DEBUG: 'false',
   }
   ```

2. **构建配置**：修改 `config/prod.ts` 中的构建配置
   - 启用代码压缩和混淆
   - 配置CDN加速
   - 优化资源加载

3. **部署命令**：
   ```bash
   NODE_ENV=production npm run build:weapp
   ```

## 🔧 常见问题

### 开发环境问题
1. **Node.js版本问题**：确保使用Node.js 16+版本
2. **依赖安装失败**：尝试清除缓存后重新安装
   ```bash
   npm cache clean --force
   npm install
   ```
3. **编译错误**：检查TypeScript配置和代码语法

### 小程序开发问题
1. **微信开发者工具无法预览**：检查appid配置和网络连接
2. **API请求失败**：确认后端服务正常运行，检查域名白名单
3. **样式显示异常**：检查rpx单位使用和NutUI组件样式

### 性能优化建议
1. **代码分割**：使用Taro的分包功能减少主包大小
2. **图片优化**：使用WebP格式，启用图片懒加载
3. **请求优化**：合并API请求，使用缓存机制

## 🤝 贡献指南

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开 Pull Request

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情

## 📞 联系我们

- 官网：https://websoft.top
- 邮箱：170083662@qq.com
- QQ群：479713884

---

⭐ 如果这个项目对您有帮助，请给我们一个星标！
