初始化工程

2025-08-10 21:09:19 +08:00
commit 42c71f5d13
30 changed files with 12882 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,212 @@
+# 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设计
+- 📱 **移动端优先** - 针对手机屏幕优化
+- ⚡ **流畅交互** - 高性能的用户体验
+- 💾 **数据持久化** - 自动保存用户输入
+- 🔄 **状态同步** - 全局状态实时更新
+
+## 核心功能实现
+
+### 动态表单配置 ⭐
+- **JSON驱动** - 通过配置文件定义表单结构
+- **字段类型丰富** - 支持10+种字段类型（图片上传、文本输入、多选、计数器、滑动条等）
+- **灵活配置** - 支持验证规则、默认值、选项配置
+- **自动渲染** - 根据配置自动生成对应的UI组件
+- **类型安全** - 完整的TypeScript类型定义
+
+### 支持的字段类型
+- `image-upload` - 图片上传
+- `text-input` - 文本输入
+- `number-input` - 数字输入
+- `time-display` - 时间显示
+- `venue-input` - 场地输入（带箭头）
+- `multi-select` - 多选按钮
+- `counter` - 计数器（min/max）
+- `slider` - 滑动条
+- `radio-group` - 单选按钮组
+- `checkbox` - 复选框
+
+### 图片上传
+- 使用Taro.chooseImage API
+- 支持相册和相机选择
+- 最多支持9张图片
+- 实时预览和删除功能
+
+### 表单验证
+- 必填字段验证
+- 数字范围验证
+- 自定义验证规则
+- 友好的错误提示
+
+### 响应式设计
+- 适配不同屏幕尺寸
+- 灵活的布局系统
+- 优雅的动画过渡
+
+## 如何自定义表单配置
+
+### 修改表单字段
+
+编辑 `src/config/formConfig.ts` 文件：
+
+```typescript
+// 添加新字段
+{
+  key: 'newField',           // 字段唯一标识
+  type: 'text-input',        // 字段类型
+  title: '新字段',           // 显示标题
+  required: true,            // 是否必填
+  placeholder: '请输入内容',  // 占位符
+  defaultValue: '',          // 默认值
+  validation: {              // 验证规则
+    min: 1,
+    max: 100,
+    message: '请输入1-100字符'
+  }
+}
+
+// 修改现有字段
+{
+  key: 'playStyle',
+  type: 'multi-select',
+  title: '活动玩法',
+  options: [
+    { label: '新玩法', value: 'new-style' }, // 添加新选项
+    { label: '单打', value: '单打' },
+    // ... 其他选项
+  ]
+}
+```
+
+### 支持的配置选项
+
+- **基础配置**: `key`, `type`, `title`, `required`, `placeholder`, `hint`
+- **默认值**: `defaultValue`
+- **验证规则**: `validation.min`, `validation.max`, `validation.message`
+- **选项配置**: `options` (用于选择类型字段)
+- **特殊配置**: `config.maxImages`, `config.minValue`, `config.showArrow` 等
+
+## 开发者说明
+
+本项目采用最简单有效、优雅的方式实现，避免代码冗余，遵循以下原则：
+
+1. **组件化设计** - 每个功能模块独立封装
+2. **配置驱动** - 通过JSON配置实现灵活的表单生成 ⭐
+3. **类型安全** - 完整的TypeScript类型定义
+4. **用户体验** - 流畅的交互和反馈
+5. **代码质量** - 简洁、可维护的代码结构
+
+## License
+
+MIT