# 社区服务系统

**Repository Path**: cctvbtx/community-service-system

## Basic Information

- **Project Name**: 社区服务系统
- **Description**: 基于PyQt6+python设计的简单社区服务系统，见证本人的成长过程
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 4
- **Created**: 2025-12-26
- **Last Updated**: 2025-12-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🌟 志愿者管理系统 (Volunteer Management System)

[![Python](https://img.shields.io/badge/Python-3.13-blue.svg)](https://www.python.org/)
[![PySide6](https://img.shields.io/badge/PySide6-6.6.0-green.svg)](https://pypi.org/project/PySide6/)
[![MySQL](https://img.shields.io/badge/MySQL-8.0+-orange.svg)](https://www.mysql.com/)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

一个基于 **PySide6** 和 **MySQL** 开发的现代化志愿者管理系统，提供完整的志愿者信息管理、服务项目发布、报名审核、服务记录跟踪和积分奖励等功能。

## 📋 目录

- [✨ 项目特色](#-项目特色)
- [🎯 核心功能](#-核心功能)
- [🏗️ 系统架构](#️-系统架构)
- [💻 技术栈](#-技术栈)
- [📁 项目结构](#-项目结构)
- [🚀 快速开始](#-快速开始)
- [⚙️ 配置说明](#️-配置说明)
- [📖 使用指南](#-使用指南)
- [🗄️ 数据库设计](#️-数据库设计)
- [🔧 开发指南](#-开发指南)
- [❓ 常见问题](#-常见问题)
- [🤝 贡献指南](#-贡献指南)
- [📄 许可证](#-许可证)

## ✨ 项目特色

- 🎨 **现代化界面**: 基于 PySide6 的美观桌面应用
- 🔐 **双角色系统**: 管理员端和志愿者端分离设计
- 📊 **数据可视化**: 集成 Matplotlib 图表展示
- 🏛️ **MVC架构**: 清晰的分层架构设计
- 🔄 **实时刷新**: 数据变更实时同步
- 💾 **数据持久化**: MySQL 数据库存储
- 🛡️ **安全可靠**: 完善的数据验证和错误处理

## 🎯 核心功能

### 👥 志愿者信息管理
- ✅ 志愿者注册与登录
- ✅ 个人信息维护（姓名、年龄、性别、联系方式）
- ✅ 技能信息管理
- ✅ 积分查询与统计

### 📋 服务项目发布
- ✅ 项目创建与编辑
- ✅ 项目信息管理（名称、地点、时间、需求人数）
- ✅ 项目状态跟踪
- ✅ 项目删除与归档

### 📝 志愿者报名与审核
- ✅ 在线报名申请
- ✅ 管理员审核流程
- ✅ 审核状态实时更新
- ✅ 审核历史记录

### 📈 服务过程管理
- ✅ 服务记录创建
- ✅ 服务时长统计
- ✅ 服务状态跟踪
- ✅ 服务完成确认

### 🏆 积分与奖励管理
- ✅ 积分规则设定
- ✅ 自动积分计算
- ✅ 积分历史查询
- ✅ 奖励发放记录

### 📢 社区公告栏
- ✅ 公告发布与管理
- ✅ 重要通知推送
- ✅ 公告分类管理
- ✅ 历史公告查询

## 🏗️ 系统架构

```
志愿者管理系统
├── 表现层 (Presentation Layer)
│   ├── 管理员界面 (Admin UI)
│   └── 志愿者界面 (Volunteer UI)
├── 业务逻辑层 (Business Logic Layer)
│   ├── 控制器 (Controllers)
│   ├── 服务层 (Services)
│   └── 工具类 (Utils)
├── 数据访问层 (Data Access Layer)
│   ├── 数据映射 (Mappers)
│   └── 实现类 (Implementations)
└── 数据层 (Data Layer)
    └── MySQL 数据库
```

## 💻 技术栈

### 🖥️ 前端技术
- **PySide6 6.6.0** - Qt6 Python 绑定，提供现代化桌面UI
- **Qt Designer** - 可视化界面设计工具

### 🔧 后端技术
- **Python 3.13** - 主要开发语言
- **PyMySQL 1.1.0** - MySQL 数据库连接驱动
- **dataclasses** - 数据类装饰器

### 🗄️ 数据库
- **MySQL 8.0+** - 关系型数据库管理系统

### 🛠️ 开发工具
- **Git** - 版本控制
- **PyCharm/VS Code** - 集成开发环境

## 📁 项目结构

```
pyhomework/
├── 📄 README.md                    # 项目说明文档
├── 📄 list.sql                     # 数据库建表脚本
├── 📄 .gitignore                   # Git忽略文件配置
├── 🖼️ ER.png                       # 数据库ER图
├── 🖼️ 系统功能结构图.png             # 系统功能架构图
├── 🖼️ 系统技术架构图.png             # 技术架构图
├── 📁 qt_ui/                       # Qt界面文件目录
│   ├── 📄 main_window.ui           # 主窗口界面
│   ├── 📄 login.ui                 # 登录界面
│   ├── 📄 register.ui              # 注册界面
│   ├── 📄 client_main_window.ui    # 客户端主界面
│   ├── 📄 add_server_project.ui    # 添加项目界面
│   ├── 📄 edit_vol_info.ui         # 编辑志愿者信息界面
│   ├── 📄 edit_review.ui           # 编辑审核界面
│   ├── 📄 edit_score.ui            # 编辑积分界面
│   └── 📄 edit_feedback.ui         # 编辑反馈界面
└── 📁 src/                         # 源代码目录
    └── 📁 main/
        ├── 📁 server/              # 服务端代码
        │   ├── 📁 controller/      # 控制器层
        │   │   ├── 📄 login_controller.py
        │   │   ├── 📄 vol_info_controller.py
        │   │   ├── 📄 server_info_controller.py
        │   │   ├── 📄 server_review_controller.py
        │   │   ├── 📄 server_feedback_controller.py
        │   │   └── 📄 score_controller.py
        │   ├── 📁 mapper/          # 数据访问层
        │   │   ├── 📄 CreateMysqlCon.py
        │   │   └── 📁 impl/        # 数据访问实现
        │   │       ├── 📄 login_impl.py
        │   │       ├── 📄 vol_info_impl.py
        │   │       ├── 📄 server_info_impl.py
        │   │       ├── 📄 server_review_impl.py
        │   │       ├── 📄 server_feedback_impl.py
        │   │       └── 📄 score_impl.py
        │   ├── 📁 pojo/            # 数据对象
        │   │   ├── 📄 Result.py
        │   │   ├── 📄 Volunteer.py
        │   │   └── 📄 ServerProject.py
        │   └── 📁 utils/           # 工具类
        │       ├── 📄 gender_judge.py
        │       ├── 📄 feedback_judge.py
        │       ├── 📄 review_judge.py
        │       └── 📄 format_datetime.py
        └── 📁 vision/              # 视图层
            ├── 📄 show.py          # 应用程序入口
            └── 📁 windows/         # 窗口类
                ├── 📄 main_window.py
                ├── 📄 login_window.py
                ├── 📄 register_window.py
                ├── 📄 client_main_window.py
                ├── 📄 client_login_window.py
                ├── 📄 client_register_window.py
                ├── 📄 add_server_project_window.py
                ├── 📄 edit_vol_info_window.py
                ├── 📄 edit_review_window.py
                ├── 📄 edit_score_window.py
                └── 📄 edit_feedback_window.py
```

## 🚀 快速开始

### 📋 环境要求

- **Python**: 3.13 或更高版本
- **MySQL**: 8.0 或更高版本
- **操作系统**: Windows 10/11, macOS 10.15+, Ubuntu 18.04+

### 🔧 安装步骤

#### 1. 克隆项目
```bash
git clone <repository-url>
cd pyhomework
```

#### 2. 创建虚拟环境（推荐）
```bash
# Windows
python -m venv venv
venv\Scripts\activate

# macOS/Linux
python3 -m venv venv
source venv/bin/activate
```

#### 3. 安装依赖
```bash
pip install PySide6==6.6.0
pip install PyMySQL==1.1.0
pip install matplotlib>=3.5.0
```

或者创建 `requirements.txt` 文件：
```txt
PySide6==6.6.0
PyMySQL==1.1.0
matplotlib>=3.5.0
```

然后安装：
```bash
pip install -r requirements.txt
```

#### 4. 数据库配置

##### 4.1 创建数据库
```sql
CREATE DATABASE volunteer_server CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

##### 4.2 导入数据表
```bash
mysql -u root -p volunteer_server < list.sql
```

##### 4.3 配置数据库连接
编辑 `src/main/server/mapper/CreateMysqlCon.py` 文件：
```python
class CreateMysqlCon:
    def __init__(self):
        self.con = pymysql.connect(
            host="localhost",        # 数据库主机
            port=3306,              # 数据库端口
            user="root",            # 数据库用户名
            password="your_password", # 修改为你的数据库密码
            database="volunteer_server",
            autocommit=True
        )
```

#### 5. 启动应用
```bash
cd src/main/vision
python show.py
```

## ⚙️ 配置说明

### 🗄️ 数据库配置

系统默认连接本地 MySQL 数据库，配置信息位于：
`src/main/server/mapper/CreateMysqlCon.py`

**重要配置项：**
- `host`: 数据库服务器地址（默认：localhost）
- `port`: 数据库端口（默认：3306）
- `user`: 数据库用户名（默认：root）
- `password`: 数据库密码（需要修改）
- `database`: 数据库名称（volunteer_server）

### 🎨 界面配置

界面文件位于 `qt_ui/` 目录，使用 Qt Designer 进行设计：
- 可以使用 Qt Designer 打开 `.ui` 文件进行界面修改
- 修改后需要重启应用程序生效

## 📖 使用指南

### 🔐 系统登录

#### 管理员登录
1. 启动应用程序
2. 在登录界面输入管理员账号密码
3. 点击"登录"进入管理员主界面

#### 志愿者登录
1. 在登录界面点击"志愿者登录"
2. 输入志愿者账号密码
3. 首次使用需要先注册账号

### 👥 志愿者管理

#### 添加志愿者
1. 进入"志愿者信息管理"标签页
2. 点击"添加志愿者"按钮
3. 填写志愿者基本信息
4. 保存信息

#### 编辑志愿者信息
1. 在志愿者列表中选择要编辑的志愿者
2. 点击"编辑"按钮
3. 修改相关信息
4. 保存更改

### 📋 项目管理

#### 发布新项目
1. 进入"服务项目发布"标签页
2. 点击"新增项目"按钮
3. 填写项目详细信息：
   - 项目名称
   - 服务地点
   - 开始/结束时间
   - 需求人数
   - 项目描述
4. 保存项目

#### 管理现有项目
1. 在项目列表中查看所有项目
2. 可以编辑、删除或查看项目详情
3. 查看项目报名情况

### 📝 审核管理

#### 处理报名申请
1. 进入"志愿者报名与审核"标签页
2. 查看待审核的报名申请
3. 选择申请记录，点击"审核"
4. 选择"通过"或"拒绝"
5. 填写审核意见（可选）
6. 提交审核结果

### 📊 数据统计

#### 查看积分统计
1. 进入"积分与奖励管理"标签页
2. 查看志愿者积分排行
3. 管理积分奖励规则
4. 发放奖励

#### 服务记录统计
1. 查看志愿者服务时长
2. 统计项目完成情况
3. 生成服务报告

## 🗄️ 数据库设计

### 📊 数据表结构

#### 1. 志愿者信息表 (volunteers_info)
| 字段名 | 类型 | 说明 |
|--------|------|------|
| ID | int | 主键，自增 |
| username | varchar(50) | 用户名 |
| password | varchar(50) | 密码 |
| age | int | 年龄 |
| gender | int | 性别（-1:未知, 0:女, 1:男） |
| pho_num | varchar(11) | 手机号码 |
| email | varchar(50) | 邮箱地址 |
| score | int | 积分 |

#### 2. 服务项目表 (server_project)
| 字段名 | 类型 | 说明 |
|--------|------|------|
| ID | int | 主键，自增 |
| server_name | varchar(50) | 项目名称 |
| place | varchar(50) | 地点 |
| server_info | varchar(255) | 项目信息 |
| server_start | datetime | 开始时间 |
| server_end | datetime | 结束时间 |
| request_person | int | 需求人数 |

#### 3. 项目审核表 (server_review)
| 字段名 | 类型 | 说明 |
|--------|------|------|
| ID | int | 主键，自增 |
| ser_name_id | int | 项目ID |
| vol_id | int | 志愿者ID |
| apply_time | datetime | 申请时间 |
| review_time | datetime | 审核时间 |
| status | int | 审核状态（0:待审核, 1:通过, 2:拒绝） |

#### 4. 服务记录表 (server_records)
| 字段名 | 类型 | 说明 |
|--------|------|------|
| ID | int | 主键，自增 |
| server_name_id | int | 项目ID |
| vol_id | int | 志愿者ID |
| server_rec_start | datetime | 开始时间 |
| server_rec_end | datetime | 结束时间 |

#### 5. 服务反馈表 (server_feedback)
| 字段名 | 类型 | 说明 |
|--------|------|------|
| ID | int | 主键，自增 |
| server_name_id | int | 项目ID |
| vol_id | int | 志愿者ID |
| status | int | 表现评分 |
| feedback | text | 反馈内容 |

#### 6. 积分表 (score)
| 字段名 | 类型 | 说明 |
|--------|------|------|
| ID | int | 主键，自增 |
| vol_id | int | 志愿者ID |
| ser_name_id | int | 项目ID |
| get_score | int | 获得积分 |

#### 7. 志愿者技能表 (skills)
| 字段名 | 类型 | 说明 |
|--------|------|------|
| ID | int | 主键，自增 |
| ski_name | varchar(50) | 技能名称 |
| ski_info | varchar(255) | 技能描述 |
| vol_id | int | 志愿者ID |

### 🔗 表关系说明

- `volunteers_info` ↔ `server_review`: 一对多（一个志愿者可以申请多个项目）
- `server_project` ↔ `server_review`: 一对多（一个项目可以有多个申请）
- `volunteers_info` ↔ `server_records`: 一对多（一个志愿者可以有多条服务记录）
- `volunteers_info` ↔ `skills`: 一对多（一个志愿者可以有多项技能）
- `volunteers_info` ↔ `score`: 一对多（一个志愿者可以有多条积分记录）

## 🔧 开发指南

### 🏗️ 架构说明

项目采用经典的 **MVC（Model-View-Controller）** 架构模式：

#### 📱 View 层 (视图层)
- **位置**: `src/main/vision/`
- **职责**: 用户界面展示和用户交互
- **技术**: PySide6 + Qt Designer

#### 🎮 Controller 层 (控制器层)
- **位置**: `src/main/server/controller/`
- **职责**: 业务逻辑处理和数据流控制
- **特点**: 连接视图层和数据层

#### 🗄️ Model 层 (模型层)
- **位置**: `src/main/server/mapper/` 和 `src/main/server/pojo/`
- **职责**: 数据访问和数据对象定义
- **技术**: PyMySQL + 数据类

### 🔄 开发流程

#### 1. 添加新功能

**步骤 1: 设计数据库表**
```sql
-- 在 list.sql 中添加新表
CREATE TABLE new_table (
    ID int auto_increment primary key,
    -- 其他字段
);
```

**步骤 2: 创建数据对象**
```python
# src/main/server/pojo/NewModel.py
from dataclasses import dataclass

@dataclass
class NewModel:
    field1: str
    field2: int
```

**步骤 3: 实现数据访问层**
```python
# src/main/server/mapper/impl/new_impl.py
from src.main.server.mapper.CreateMysqlCon import CreateMysqlCon

class NewImpl:
    def __init__(self):
        self.con = CreateMysqlCon().get_con()
        self.cursor = self.con.cursor()
    
    def get_all(self):
        sql = "SELECT * FROM new_table"
        self.cursor.execute(sql)
        return self.cursor.fetchall()
```

**步骤 4: 创建控制器**
```python
# src/main/server/controller/new_controller.py
from src.main.server.mapper.impl.new_impl import NewImpl

class NewController:
    def __init__(self):
        self.impl = NewImpl()
    
    def get_all_data(self):
        return self.impl.get_all()
```

**步骤 5: 设计界面**
- 使用 Qt Designer 创建 `.ui` 文件
- 保存到 `qt_ui/` 目录

**步骤 6: 创建窗口类**
```python
# src/main/vision/windows/new_window.py
from PySide6.QtUiTools import QUiLoader
from PySide6.QtCore import QFile

class NewWindow:
    def __init__(self):
        self.ui_file_path = "../../../qt_ui/new_window.ui"
        self._load_ui()
    
    def _load_ui(self):
        file = QFile(self.ui_file_path)
        try:
            self.window = QUiLoader().load(file)
            # 绑定事件
        finally:
            file.close()
```

#### 2. 调试技巧

**数据库调试**
```python
# 在控制器中添加调试信息
print(f"SQL执行结果: {result}")
print(f"数据库连接状态: {self.con.open}")
```

**界面调试**
```python
# 在窗口类中添加调试信息
print(f"按钮点击事件触发")
print(f"当前窗口状态: {self.window.isVisible()}")
```

### 📝 代码规范

#### 命名规范
- **类名**: 使用 PascalCase（如：`VolInfoController`）
- **方法名**: 使用 snake_case（如：`get_all_data`）
- **变量名**: 使用 snake_case（如：`user_name`）
- **常量名**: 使用 UPPER_CASE（如：`MAX_SCORE`）

#### 文件组织
- 每个功能模块独立文件
- 相关功能放在同一目录
- 使用有意义的文件名

#### 注释规范
```python
class ExampleController:
    """
    示例控制器类
    负责处理示例相关的业务逻辑
    """
    
    def get_data(self, user_id: int) -> list:
        """
        获取用户数据
        
        Args:
            user_id: 用户ID
            
        Returns:
            list: 用户数据列表
        """
        pass
```

## ❓ 常见问题

### 🔧 安装问题

**Q: 安装 PySide6 时出现错误？**

A: 尝试以下解决方案：
```bash
# 升级 pip
pip install --upgrade pip

# 使用国内镜像源
pip install PySide6==6.6.0 -i https://pypi.tuna.tsinghua.edu.cn/simple/

# 如果仍有问题，尝试安装特定版本
pip install PySide6==6.5.0
```

**Q: MySQL 连接失败？**

A: 检查以下配置：
1. 确认 MySQL 服务已启动
2. 检查用户名和密码是否正确
3. 确认数据库 `volunteer_server` 已创建
4. 检查防火墙设置

### 🖥️ 运行问题

**Q: 启动应用时出现 "No module named 'src'" 错误？**

A: 确保在正确的目录下运行：
```bash
cd src/main/vision
python show.py
```

**Q: 界面显示异常或无法加载？**

A: 检查以下几点：
1. 确认 `.ui` 文件路径正确
2. 检查 Qt Designer 版本兼容性
3. 重新生成 `.ui` 文件

**Q: 数据库操作失败？**

A: 常见解决方案：
1. 检查 SQL 语句语法
2. 确认表结构是否正确
3. 查看数据库连接是否正常
4. 检查数据类型匹配

### 📊 数据问题

**Q: 数据显示不完整或格式错误？**

A: 检查数据处理逻辑：
1. 确认数据查询 SQL 正确
2. 检查数据格式化函数
3. 验证数据类型转换

**Q: 积分计算不正确？**

A: 检查积分计算逻辑：
1. 确认积分规则设置
2. 检查计算公式
3. 验证数据库更新操作

## 🤝 贡献指南

我们欢迎所有形式的贡献！无论是 bug 报告、功能建议还是代码贡献。

### 🐛 报告 Bug

1. 在 [Issues](../../issues) 页面创建新的 issue
2. 使用清晰的标题描述问题
3. 提供详细的问题描述，包括：
   - 操作系统和版本
   - Python 版本
   - 错误信息和堆栈跟踪
   - 重现步骤

### 💡 功能建议

1. 在 [Issues](../../issues) 页面创建功能请求
2. 详细描述建议的功能
3. 说明功能的使用场景和价值

### 🔧 代码贡献

1. **Fork** 项目到你的 GitHub 账户
2. 创建功能分支：`git checkout -b feature/amazing-feature`
3. 提交更改：`git commit -m 'Add some amazing feature'`
4. 推送到分支：`git push origin feature/amazing-feature`
5. 创建 **Pull Request**

### 📋 贡献规范

- 遵循现有的代码风格
- 添加适当的注释和文档
- 确保新功能有相应的测试
- 更新相关文档

## 📞 联系我们

如果你有任何问题或建议，欢迎通过以下方式联系我们：

- 📧 **邮箱**: [your-email@example.com](mailto:your-email@example.com)
- 🐛 **Bug 报告**: [GitHub Issues](../../issues)
- 💬 **讨论**: [GitHub Discussions](../../discussions)

## 📄 许可证

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

---

<div align="center">

**⭐ 如果这个项目对你有帮助，请给我们一个 Star！⭐**

**🙏 感谢所有贡献者的支持！🙏**

---

*最后更新时间: 2025年6月*

</div>