# ResiCloud_server

**Repository Path**: southwind957/resi-cloud_server

## Basic Information

- **Project Name**: ResiCloud_server
- **Description**: ResiCloud_API 是 ResiCloud 系统的后端服务，负责数据存储、业务逻辑处理与接口提供。  
它为小程序端和管理后台提供统一的数据支持与认证服务。  
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-17
- **Last Updated**: 2026-03-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ResiCloud Server

## 项目简介

ResiCloud Server是一个基于Flask构建的智慧小区管理系统后端API，提供全面的小区物业管理功能，包括用户管理、维修申请、缴费管理、公告发布、投诉处理等核心功能模块。

## 功能特性

### 核心模块

- **用户管理**：业主注册、登录、个人信息管理
- **维修服务**：维修申请提交、状态查询、进度追踪
- **缴费管理**：物业费、停车费等各类费用查询与缴纳
- **公告系统**：管理员发布小区公告，用户查看最新通知
- **投诉处理**：用户提交投诉建议，管理员处理反馈
- **联系管理**：联系方式管理
- **事件管理**：小区活动、事件记录
- **活动报名**：小区活动报名信息记录与管理
- **员工管理**：物业工作人员信息管理
- **管理员功能**：系统后台管理权限
- **车位管理**：停车位信息管理
- **房屋管理**：房屋信息管理

### 技术亮点

- **模块化设计**：采用MVC架构，代码结构清晰
- **JWT认证**：安全的用户认证机制
- **多数据库支持**：支持SQLite、MySQL、PostgreSQL
- **环境变量配置**：灵活的配置管理
- **RESTful API**：标准化的API接口设计
- **数据验证**：输入数据安全验证
- **密码加密**：用户密码安全存储

## 技术栈

- **后端框架**：Flask 2.3+
- **数据库ORM**：Flask-SQLAlchemy 3.0+
- **认证授权**：Flask-JWT-Extended 4.5+
- **数据库迁移**：Flask-Migrate 4.0+
- **数据序列化**：marshmallow 3.20+
- **环境变量管理**：python-dotenv 1.0.0+
- **数据库支持**：
  - SQLite（默认开发环境）
  - MySQL（可选，需安装pymysql）
  - PostgreSQL（可选）
- **包管理器**：uv

## 项目结构

```
resicloud_server/
├── app/
│   ├── __init__.py         # 应用工厂和初始化
│   ├── config.py           # 配置管理
│   ├── extensions.py       # 扩展组件初始化
│   ├── controllers/        # 业务逻辑层
│   │   ├── __init__.py
│   │   ├── admin.py
│   │   ├── announcement.py
│   │   ├── complaint.py
│   │   ├── contact.py
│   │   ├── event.py
│   │   ├── house.py
│   │   ├── parking_space.py
│   │   ├── payment.py
│   │   ├── repair.py
│   │   ├── signup_record.py
│   │   ├── staff.py
│   │   └── user.py
│   ├── models/             # 数据模型层
│   │   ├── __init__.py
│   │   ├── admin.py
│   │   ├── announcement.py
│   │   ├── complaint.py
│   │   ├── contact.py
│   │   ├── event.py
│   │   ├── house.py
│   │   ├── parking_space.py
│   │   ├── payment.py
│   │   ├── repair.py
│   │   ├── signup_record.py
│   │   ├── staff.py
│   │   └── user.py
│   ├── routes/             # 路由和视图层
│   │   ├── __init__.py
│   │   ├── admin.py
│   │   ├── announcement.py
│   │   ├── complaint.py
│   │   ├── contact.py
│   │   ├── event.py
│   │   ├── house.py
│   │   ├── parking_space.py
│   │   ├── payment.py
│   │   ├── repair.py
│   │   ├── signup_record.py
│   │   ├── staff.py
│   │   └── user.py
│   └── utils/              # 工具函数
│       ├── __init__.py
│       ├── response.py
│       └── security.py
├── .env.example            # 环境变量示例
├── .gitignore              # Git忽略配置
├── README.MD               # 项目说明文档
├── pyproject.toml          # 项目配置和依赖
├── resicloud_2025-10-09_174116.sql  # 数据库备份文件
├── run.py                  # 应用启动入口
├── tests/                  # 测试文件
│   ├── test_admin_api.py
│   ├── test_announcement_api.py
│   ├── test_complaint_api.py
│   ├── test_contact_api.py
│   ├── test_event_api.py
│   ├── test_payment_api.py
│   ├── test_repair_api.py
│   ├── test_staff_api.py
│   └── test_user_api.py
└── uv.lock                 # uv依赖锁文件
```

## 安装与部署

### 前置要求

- Python 3.8 或更高版本
- uv 包管理器

### 安装步骤

1. **克隆项目**

   ```bash
   git clone [项目仓库地址]
   cd resicloud_server
   ```
2. **安装依赖**

   ```bash
   uv install
   ```
3. **配置环境变量**

   - 复制环境变量示例文件
     ```bash
     cp .env.example .env
     ```
   - 编辑 `.env` 文件，设置必要的环境变量
     ```
     # 数据库配置
     DB_TYPE=sqlite      # 可选: sqlite, mysql, postgresql
     SECRET_KEY=your_secret_key
     JWT_SECRET_KEY=your_jwt_secret_key

     # MySQL/PostgreSQL配置（仅在使用时需要）
     # DB_HOST=localhost
     # DB_PORT=3306
     # DB_NAME=resicloud
     # DB_USER=username
     # DB_PASSWORD=password
     ```
4. **运行应用**

   ```bash
   uv run run.py
   ```
5. **访问API**
   应用启动后，API将在 http://localhost:5000 上可用

## API文档

### 认证相关

- **用户注册**: `POST /api/register`
- **用户登录**: `POST /api/login`

### 用户管理

- **获取用户信息**: `GET /api/users/<id>`
- **更新用户信息**: `PUT /api/users/<id>`
- **获取所有用户**: `GET /api/users` (管理员权限)

### 维修服务

- **提交维修申请**: `POST /api/repairs`
- **获取维修记录**: `GET /api/repairs`
- **获取单个维修详情**: `GET /api/repairs/<id>`
- **更新维修状态**: `PUT /api/repairs/<id>`

### 缴费管理

- **获取费用账单**: `GET /api/payments`
- **缴费**: `POST /api/payments/<id>/pay`
- **获取缴费历史**: `GET /api/payments/history`

### 事件管理

- **创建活动**: `POST /events/add`
- **获取活动列表**: `GET /events/list`
- **获取活动详情**: `GET /events/event`
- **更新活动信息**: `POST /events/edit`
- **删除活动**: `POST /events/delete`

### 活动报名管理

- **创建报名记录**: `POST /signup_records/add`
- **获取报名记录列表**: `GET /signup_records/list`
- **获取报名记录详情**: `GET /signup_records/record`
- **更新报名记录**: `POST /signup_records/edit`
- **删除报名记录**: `POST /signup_records/delete`

### 投诉管理

- **提交投诉**: `POST /complaints/add`
- **获取投诉列表**: `GET /complaints/list`
- **获取投诉详情**: `GET /complaints/complaint`
- **更新投诉状态**: `POST /complaints/edit`
- **删除投诉**: `POST /complaints/delete`

### 公告管理

- **发布公告**: `POST /announcements/add`
- **获取公告列表**: `GET /announcements/list`
- **获取公告详情**: `GET /announcements/announcement`
- **更新公告**: `POST /announcements/edit`
- **删除公告**: `POST /announcements/delete`

### 联系管理

- **添加联系方式**: `POST /contacts/add`
- **获取联系方式列表**: `GET /contacts/list`
- **获取联系方式详情**: `GET /contacts/contact`
- **更新联系方式**: `POST /contacts/edit`
- **删除联系方式**: `POST /contacts/delete`

### 维修服务

- **提交维修申请**: `POST /repairs/add`
- **获取维修记录列表**: `GET /repairs/list`
- **获取维修详情**: `GET /repairs/repair`
- **更新维修状态**: `POST /repairs/edit`
- **删除维修记录**: `POST /repairs/delete`

### 缴费管理

- **获取费用账单**: `GET /payments/list`
- **缴费**: `POST /payments/pay`
- **获取缴费详情**: `GET /payments/payment`
- **更新缴费信息**: `POST /payments/edit`
- **删除缴费记录**: `POST /payments/delete`

### 员工管理

- **添加员工**: `POST /staff/add`
- **获取员工列表**: `GET /staff/list`
- **获取员工详情**: `GET /staff/staff`
- **更新员工信息**: `POST /staff/edit`
- **删除员工**: `POST /staff/delete`

### 管理员功能

- **管理员登录**: `POST /admin/login`
- **获取管理员信息**: `GET /admin/info`
- **更新管理员信息**: `POST /admin/update`

### 车位管理

- **添加车位**: `POST /parking/add`
- **获取车位列表**: `GET /parking/list`
- **获取车位详情**: `GET /parking/parking`
- **更新车位信息**: `POST /parking/edit`
- **删除车位**: `POST /parking/delete`

### 房屋管理

- **添加房屋信息**: `POST /house/add`
- **获取房屋列表**: `GET /house/list`
- **获取房屋详情**: `GET /house/house`
- **更新房屋信息**: `POST /house/edit`
- **删除房屋信息**: `POST /house/delete`

## 测试

项目包含单元测试，使用以下命令运行测试：

```bash
# 在项目根目录运行
uv run pytest
```

## 开发指南

### 添加新功能模块

1. **创建模型**：在 `app/models/` 下创建新的模型文件
2. **创建控制器**：在 `app/controllers/` 下实现业务逻辑
3. **创建路由**：在 `app/routes/` 下定义API端点
4. **注册蓝图**：在 `app/routes/__init__.py` 中注册新的蓝图

### 数据库迁移

当修改数据库模型时，执行以下步骤进行迁移：

```bash
# 生成迁移文件
flask db migrate -m "描述迁移内容"

# 应用迁移
flask db upgrade
```

## 安全注意事项

1. **生产环境配置**

   - 务必修改 `SECRET_KEY` 和 `JWT_SECRET_KEY` 为强随机值
   - 禁用调试模式
   - 使用HTTPS加密传输
2. **密码安全**

   - 系统使用安全的密码哈希算法存储密码
   - 建议定期更新密码策略
3. **访问控制**

   - 确保敏感操作（如管理员功能）有适当的权限验证

## 许可证

[在此添加许可证信息]

## 联系信息

- **项目维护者**: jiajiazhang
- **邮箱**: you@example.com
- **问题反馈**: 请在项目仓库提交Issue

## 更新日志

### v0.1.0 (初始版本)

- 实现用户管理核心功能
- 实现维修申请模块
- 实现缴费管理模块
- 实现公告系统
- 实现投诉处理模块
- 基础架构搭建和API设计

### v0.1.1

- 添加活动管理模块
- 添加活动报名管理功能
- 添加车位管理模块
- 添加房屋管理模块
- 添加联系管理模块
- 添加员工管理模块
- 完善测试用例