# 志愿者服务平台 React 版本

## 项目简介

本项目是将原有的志愿者服务平台从原生JavaScript重构为React框架的版本，保持了原有的页面样式和功能效果，同时采用了现代化的React开发模式。

## 技术栈

- **前端框架**: React 18.2.0
- **路由管理**: React Router 6.8.0
- **状态管理**: React Context + useReducer
- **样式预处理**: CSS
- **UI组件库**: dingtalk-design-mobile
- **HTTP客户端**: Axios
- **开发语言**: TypeScript

## 环境配置

### 环境变量配置

项目支持通过环境变量配置基础URL，创建`.env`文件并设置以下变量：

```bash
# 管理端基础URL（积分核销跳转目标）
REACT_APP_ADMIN_BASE_URL=http://10.200.1.89:3000

# API基础URL
REACT_APP_API_BASE_URL=http://10.200.1.89:8080

# 应用名称
REACT_APP_APP_NAME=志愿者服务平台

# 版本号
REACT_APP_VERSION=1.0.0
```

### 积分核销功能

积分核销页面支持扫码后跳转到外部管理端页面，跳转URL格式：
```
{REACT_APP_ADMIN_BASE_URL}/admin-points-redemption?communityCode={社区编码}&volunteerId={用户ID}&volunteerName={用户姓名}&points={可用积分}
```

## 项目结构

```
volunteer-app/
├── public/
│   └── index.html          # HTML入口文件
├── src/
│   ├── components/         # 可复用组件
│   │   ├── Carousel.tsx   # 轮播图组件
│   │   └── PageHeader.tsx # 页面头部组件
│   ├── context/           # 全局状态管理
│   │   └── AppContext.tsx # 应用上下文
│   ├── views/             # 页面级组件
│   │   ├── HomePage.tsx           # 首页
│   │   ├── PointsDeclarationPage.tsx  # 积分申报页面
│   │   ├── DeclarationDetailPage.tsx  # 申报详情页面
│   │   ├── PointsQueryPage.tsx       # 积分查询页面
│   │   ├── ScanCheckinPage.tsx       # 签到页面
│   │   ├── PointsRedemptionPage.tsx  # 积分核销页面
│   │   ├── ActivityDetailPage.tsx    # 活动详情页面
│   │   ├── ActivityCheckinPage.tsx   # 活动签到页面
│   │   └── CheckinSuccessPage.tsx    # 签到成功页面
│   ├── App.tsx            # 主应用组件
│   ├── index.tsx          # React入口文件
│   └── index.css          # 全局样式文件
├── package.json           # 项目依赖配置
└── README.md             # 项目说明文档
```

## 主要功能

### 1. 首页功能
- 轮播图展示公益活动
- 消息通知条
- 功能按钮导航（积分申报、活动列表、签到签退、积分核销）
- 最新活动列表展示

### 2. 积分申报功能
- 申报记录列表查看
- Tab切换筛选（全部、审核中、已审核）
- 搜索功能
- 自主申报表单
- 悬浮申报按钮

### 3. 活动管理功能
- 活动列表展示
- 活动状态筛选（全部、进行中、即将开始、已完成）
- 活动详情查看
- 活动签到功能

### 4. 签到功能
- 活动签到
- 签到地点记录
- 备注信息
- 签到成功页面

### 5. 积分核销功能
- 核销码输入
- 积分数量设置
- 二维码扫描区域
- 积分信息展示

## 设计特色

- **主色调**: 以淡红色为主色调，温暖、积极，突出公益氛围
- **移动端优先**: 所有布局、字号、间距都适配手机屏幕
- **图标丰富**: 使用Font Awesome图标库，提升辨识度
- **渐变设计**: 页面头部采用渐变背景，视觉效果更佳
- **卡片式布局**: 信息展示采用卡片式设计，层次分明

## 开发规范

### 代码规范
- 组件文件使用大驼峰命名（PascalCase）
- 组件内部函数使用小驼峰命名（camelCase）
- 组件props类型必须使用TypeScript接口定义
- 组件必须包含清晰的JSDoc注释

### 样式规范
- 使用标准CSS
- 全局样式变量统一管理
- 移动端适配使用rem或vw单位
- 组件样式使用CSS Modules避免样式污染

## 安装和运行

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

### 启动开发服务器

#### 方法1: 使用npm命令
```bash
npm start
```

#### 方法2: 使用启动脚本
- Windows: 双击 `start.bat` 文件
- Linux/Mac: 在终端中执行 `./start.sh`

项目启动后会自动打开浏览器，访问地址: http://localhost:3000

### 构建生产版本
```bash
npm run build
```

## 浏览器支持

- Chrome (推荐)
- Firefox
- Safari
- Edge

## 作者信息

- **开发者**: 韩天尊
- **开发时间**: 2024-01-15
- **版本**: 1.0.0

## 故障排除

### 常见问题

#### 1. 依赖安装失败
如果遇到依赖冲突，请尝试：
```bash
npm install --legacy-peer-deps
```

#### 2. 项目启动失败
- 确保已安装Node.js 16+版本
- 删除node_modules文件夹，重新执行npm install
- 检查端口3000是否被占用

#### 3. 样式文件问题
项目使用标准CSS，如果遇到样式问题，请确保：
- 样式文件路径正确
- 浏览器支持CSS变量

## 更新日志

### v1.0.0 (2024-01-15)
- 完成从原生JavaScript到React框架的重构
- 实现所有原有功能页面
- 保持原有页面样式和效果
- 采用现代化的React开发模式
- 完善的状态管理和路由配置