# PlayBallTogether - 约球应用

## 项目简介

这是一个基于Taro + React + TypeScript的约球应用，用户可以发布个人约球活动。

## 主要功能

### 核心功能特性

- ✅ **图片上传** - 支持上传多张活动封面图片
- ✅ **活动信息填写** - 主题、时间、场地、价格等完整信息
- ✅ **多玩法选择** - 单打、双打、娱乐拉球、到了再说
- ✅ **人数控制** - 灵活设置最少到最多参与人数
- ✅ **NTRP水平设置** - 滑动条选择技能水平区间
- ✅ **性别偏好** - 支持性别限制或不限
- ✅ **自动候补** - 开启自动候补逻辑
- ✅ **多场发布** - 支持同时创建多场活动

### 技术架构特性 ⭐

- ✅ **动态表单配置** - 通过JSON配置动态生成表单
- ✅ **组件化架构** - 可复用的字段渲染器
- ✅ **表单验证** - 自动数据验证和错误提示
- ✅ **API集中管理** - 统一services目录，按页面功能命名
- ✅ **Token自动管理** - 自动携带token，处理过期刷新
- ✅ **请求拦截处理** - 统一错误处理和加载状态
- ✅ **多人协作友好** - 按页面隔离，避免代码冲突

## 技术栈

- **框架**: Taro 4.1.5
- **前端**: React 18 + TypeScript
- **UI库**: NutUI React Taro
- **样式**: Sass
- **状态管理**: React Context + useReducer
- **本地存储**: Taro Storage API

## 快速开始

```bash
# 安装依赖
npm install
# 或
yarn install

# 开发环境启动
npm run dev:h5          # H5版本
npm run dev:weapp       # 微信小程序
npm run dev:alipay      # 支付宝小程序

# 构建生产版本
npm run build:h5        # H5版本
npm run build:weapp     # 微信小程序
npm run build:alipay    # 支付宝小程序
```

## 页面路由

- `/pages/index/index` - 首页
- `/pages/publish/publish` - 原发布页面
- `/pages/publishBall/publishBall` - 新的约球发布页面 ⭐
- `/pages/dynamicFormDemo/dynamicFormDemo` - 动态表单演示页面 ⭐

## 项目结构 🏗️

本项目采用**按页面分层、组件共享**的架构设计，便于多人协作开发。

```
src/
├── components/              # 🔥 公共组件（所有页面共享）
│   └── DynamicForm/         # 动态表单组件 ⭐
│       ├── DynamicForm.tsx      # 动态表单容器
│       ├── DynamicForm.scss     # 动态表单样式
│       ├── FieldRenderer.tsx    # 字段渲染器
│       ├── FieldRenderer.scss   # 字段渲染器样式
│       └── index.ts             # 组件导出
├── pages/                   # 📱 页面目录（按功能模块划分）
│   ├── index/               # 首页模块
│   ├── publish/             # 原发布页面
│   ├── publishBall/         # 约球发布模块 ⭐
│   │   ├── publishBall.tsx
│   │   ├── publishBall.scss
│   │   └── publishBall.config.ts
│   └── dynamicFormDemo/     # 动态表单演示模块 ⭐
│       ├── dynamicFormDemo.tsx
│       ├── dynamicFormDemo.scss
│       └── dynamicFormDemo.config.ts
├── services/                # 🌐 API服务（统一管理）
│   ├── httpService.ts           # HTTP基础服务 ⭐
│   ├── authService.ts           # 认证服务 ⭐
│   ├── commonApi.ts             # 通用API服务 ⭐
│   ├── publishBallApi.ts        # 🔥 约球发布API服务
│   └── demoApi.ts               # 🔥 演示页面API服务
├── utils/                   # 🛠️ 工具函数
│   ├── tokenManager.ts          # Token管理 ⭐
│   └── storage.ts               # 本地存储
├── config/                  # ⚙️ 配置文件
│   ├── formConfig.ts            # 表单配置定义 ⭐
│   └── exampleConfigs.ts        # 示例配置 ⭐
├── store/                   # 📦 全局状态管理
│   ├── matchStore.ts           # Zustand状态管理
│   └── storage.ts              # 本地存储工具
├── app.ts                   # 应用入口
├── app.config.ts            # 应用配置
└── app.scss                # 全局样式
```

详细架构说明请查看：[ARCHITECTURE.md](./ARCHITECTURE.md)

## 设计特色

- 🎨 **严格按照设计图实现** - 像素级还原UI设计
- 📱 **移动端优先** - 针对手机屏幕优化
- ⚡ **流畅交互** - 高性能的用户体验
- 💾 **数据持久化** - 自动保存用户输入
- 🔄 **状态同步** - 全局状态实时更新


### 图片上传
- 使用Taro.chooseImage API
- 支持相册和相机选择
- 最多支持9张图片
- 实时预览和删除功能

### 表单验证
- 必填字段验证
- 数字范围验证
- 自定义验证规则
- 友好的错误提示

### 响应式设计
- 适配不同屏幕尺寸
- 灵活的布局系统
- 优雅的动画过渡

## 如何自定义表单配置

## 开发者说明

本项目采用最简单有效、优雅的方式实现，避免代码冗余，遵循以下原则：

1. **组件化设计** - 每个功能模块独立封装
2. **配置驱动** - 通过JSON配置实现灵活的表单生成 ⭐
3. **类型安全** - 完整的TypeScript类型定义
4. **用户体验** - 流畅的交互和反馈
5. **代码质量** - 简洁、可维护的代码结构

## License

MIT