Campus Lost & Found Platform

An intelligent campus lost and found platform built with modern web technologies, providing efficient item matching, user interaction, and community features.

📌 Project Overview

This project is a campus-oriented lost and found platform designed to improve the efficiency and user experience of lost and found services through technology. The platform uses a front-end and back-end separated architecture, with the back-end based on Python FastAPI framework and the front-end built with Vue 3. The database uses MySQL for both development and production environments.

✨ Core Features

Core Functionality

User Authentication: Email/password registration and login with JWT tokens
User Management: Profile management, notifications, and credit scoring system
Community Forum: Create posts, comment on posts, and engage with the community
Real-time Notifications: Get notified about comments and other activities
Responsive Design: Modern, mobile-friendly UI built with Tailwind CSS

Lost & Found Features ✨

Item Categories: Organize lost and found items by category (electronics, documents, keys, etc.)
Smart Matching: Intelligent recommendation system to match lost and found items
Image Upload: Support multiple image uploads for item posts
Advanced Search: Filter by category, location, time, and claimed status
Claim System: Complete claim workflow with approval/rejection
Rating System: Mutual rating between item owners and claimers
Credit Score: Automatic credit score updates based on ratings
Detailed Information: Track item location, time, and contact information

🚀 Tech Stack

Backend Technologies

FastAPI: High-performance Python web framework with automatic API documentation
SQLModel: Type-safe ORM combining SQLAlchemy and Pydantic
MySQL: Reliable relational database for both development and production
JWT: Secure authentication with JSON Web Tokens
Alembic: Database migration tool
Uvicorn: ASGI server supporting asynchronous request processing
Scikit-learn: Used for intelligent matching algorithms
Python-Levenshtein: String similarity calculation

Frontend Technologies

Vue 3: Progressive JavaScript framework using Composition API
Pinia: Modern state management library for Vue
Vue Router: Official routing manager for Vue.js
Axios: Promise-based HTTP client
Element Plus: Vue 3-based desktop component library
Tailwind CSS: Utility-first CSS framework
Vite: Next-generation frontend build tool
Day.js: Lightweight date processing library

📁 Project Structure

lost-and-found-platform/
├── backend/                 # Backend code
│   ├── app/                # Application main directory
│   │   ├── api/            # API routes
│   │   │   ├── v1/         # API version 1
│   │   │   └── deps.py     # Dependency injection
│   │   ├── core/           # Core functionality
│   │   │   ├── config.py   # Configuration management
│   │   │   └── security.py # Security related
│   │   ├── models/         # Data models
│   │   ├── schemas/        # Pydantic models
│   │   └── services/       # Business logic
│   ├── tests/              # Test code
│   ├── alembic/            # Database migrations
│   ├── scripts/            # Utility scripts
│   ├── requirements.txt     # Python dependencies
│   └── start.py            # Startup script
│
└── frontend/               # Frontend code
    └── frontend/           # Vue project
        ├── public/         # Static resources
        └── src/
            ├── api/        # API requests
            ├── assets/     # Resource files
            ├── components/ # Public components
            ├── router/     # Routing configuration
            ├── stores/     # Pinia state management
            ├── utils/      # Utility functions
            └── views/      # Page components

🔄 Recent Updates

Frontend Optimization (2024-01-15)

Unified use of content-wrapper to wrap main views for consistent page layout
Created message utility function for unified message prompt management
Optimized notification center using router-link for page navigation
Fixed multiple message prompts and layout issues in various views

Database Optimization (2024-01-10)

Optimized database query performance
Added database backup and recovery scripts
Fixed data consistency issues

🚧 Development Progress

Completed Features

In Progress

Smart recommendation algorithm optimization
Admin management system
Data statistics and analysis
Multi-language support

🛠️ Development Guide

Environment Requirements

Python 3.9+
Node.js 18+
MySQL 8.0+

Quick Start

Clone the repository

git clone https://github.com/yourusername/lost-and-found-platform.git
cd lost-and-found-platform

Backend setup

cd backend
python -m venv venv
source venv/bin/activate  # Linux/Mac
# or venv\Scripts\activate  # Windows
pip install -r requirements.txt

Frontend setup
```
cd ../frontend/frontend
npm install
```

Start development servers

# Start backend
cd ../../backend
uvicorn app.main:app --reload

# Start frontend (new terminal)
cd ../frontend/frontend
npm run dev

Visit http://localhost:5173

🤝 Contributing

We welcome Issue and Pull Request submissions. Please ensure:

Follow the project's code style
Add appropriate tests
Update relevant documentation

📄 License

This project is licensed under the MIT License

📞 Contact

For any questions or suggestions, please contact us through:

Email: your.email@example.com
GitHub Issues: Submit an issue

Core Features

User Authentication: Email/password registration and login with JWT tokens
User Management: Profile management, notifications, and credit scoring system
Community Forum: Create posts, comment on posts, and engage with the community
Real-time Notifications: WebSocket-based real-time notifications for comments and claim updates
Email Notifications: Automated email notifications for claim status changes
Responsive Design: Modern, mobile-friendly UI built with Tailwind CSS

Lost & Found Features ✨

Item Categories: Organize lost and found items by category (electronics, documents, keys, etc.)
Smart Matching: Intelligent recommendation system to match lost and found items
Image Upload: Support multiple image uploads for item posts
Advanced Search: Filter by category, location, time, and claimed status
Claim System: Complete claim workflow with approval/rejection
Rating System: Mutual rating between item owners and claimers
Credit Score: Automatic credit score updates based on ratings
Detailed Information: Track item location, time, and contact information

Tech Stack

Backend

FastAPI: Modern, fast web framework for building APIs
SQLModel: Type-safe ORM that combines SQLAlchemy and Pydantic
PostgreSQL: Robust, open-source relational database
JWT: Secure authentication with JSON Web Tokens
Alembic: Database migration tool

Frontend

Vue 3: Progressive JavaScript framework with Composition API
Pinia: State management for Vue applications
Vue Router: Official router for Vue.js
Axios: HTTP client for API communication
Tailwind CSS: Utility-first CSS framework

Project Structure

lost-and-found-platform/
├── backend/
│   ├── app/
│   │   ├── api/           # API routes
│   │   ├── core/          # Core functionality (security, config)
│   │   ├── models/        # SQLModel database models
│   │   ├── schemas/       # Pydantic schemas
│   │   ├── database.py    # Database configuration
│   │   └── main.py        # FastAPI application
│   ├── requirements.txt   # Python dependencies
│   └── start.py          # Startup script
├── frontend/
│   └── frontend/
│       ├── src/
│       │   ├── api/       # API client configuration
│       │   ├── components/ # Vue components
│       │   ├── stores/    # Pinia stores
│       │   ├── views/     # Vue pages
│       │   └── router/    # Vue Router configuration
│       └── package.json   # Node.js dependencies
└── README.md

Getting Started

Prerequisites

Python 3.8+
Node.js 16+
PostgreSQL 12+

Backend Setup

Navigate to the backend directory:
```
cd backend
```

Create a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install dependencies:
```
pip install -r requirements.txt
```

Set up environment variables:

cp .env.example .env
# Edit .env with your database credentials

Start the backend server:
```
python start.py
```

The API will be available at http://localhost:8000

Frontend Setup

Navigate to the frontend directory:
```
cd frontend/frontend
```
Install dependencies:
```
npm install
```
Start the development server:
```
npm run dev
```

The frontend will be available at http://localhost:5173

Create an Admin User

To create an administrator account for the platform:

cd backend
python create_admin.py

The script will interactively prompt you for:

Username
Full Name
Email
Password (with confirmation)

The created user will have admin privileges and can access the admin panel at /admin.

Seed the Database with Test Data

To quickly populate the database with realistic test data (users, posts, claims, comments, ratings):

BACKUP YOUR DATABASE FIRST (optional but recommended):
```
cd backend
./backup_database.sh
```
Ensure backend dependencies are installed:
```
pip install -r requirements.txt
```

Run the seeding script:

python seed_database.py
# Type 'yes' when prompted to confirm

⚠️ WARNING: This script is DESTRUCTIVE and will:

Delete ALL existing data (users, posts, claims, comments, etc.)
Create fresh test data with Faker
Create a default admin account (admin@example.com / admin123)

Notes:

The script requires typing 'yes' to proceed as a safety measure
Uses the DATABASE_URL from environment or falls back to SQLite
Creates ~20 users, ~50 posts, ~30 claims, and related data

API Endpoints

Authentication

POST /api/auth/register - User registration
POST /api/auth/login - User login
GET /api/auth/me - Get current user info

Users

GET /api/users/profile - Get user profile
PUT /api/users/profile - Update user profile
GET /api/users/notifications - Get user notifications
PUT /api/users/notifications/{id}/read - Mark notification as read

Posts (Lost & Found)

GET /api/posts - List posts (with filtering)
POST /api/posts - Create post
GET /api/posts/{id} - Get post detail
PUT /api/posts/{id} - Update post
DELETE /api/posts/{id} - Delete post
GET /api/posts/{id}/matches - Get smart matches for a post
GET /api/posts/search/advanced - Advanced search
POST /api/posts/{id}/comments - Add comment
GET /api/posts/{id}/comments - List comments
DELETE /api/posts/comments/{id} - Delete comment

Claims ✨

POST /api/claims/ - Create claim request
GET /api/claims/my-claims - Get my claim requests
GET /api/claims/post/{id} - Get claims for a post
POST /api/claims/{id}/approve - Approve a claim
POST /api/claims/{id}/reject - Reject a claim
DELETE /api/claims/{id} - Cancel a claim

Ratings ✨

POST /api/ratings/ - Create rating
GET /api/ratings/claim/{id} - Get ratings for a claim
GET /api/ratings/user/{id}/received - Get ratings received by user

Users ✨

GET /api/users/{id} - Get user public information
GET /api/users/{id}/posts - Get user's posts
GET /api/users/{id}/ratings - Get user's ratings

Upload

POST /api/upload/upload - Upload single image
POST /api/upload/upload-multiple - Upload multiple images
DELETE /api/upload/{filename} - Delete image

Database Schema

The application uses the following main entities:

Users: User accounts with authentication, profile information, and credit scores
Categories: Item categories (electronics, documents, keys, books, etc.)
Posts: Forum posts with lost/found item information
Comments: Comments on posts
Notifications: System notifications for users
Claims ✨: Claim requests for lost and found items
Ratings ✨: User ratings after successful claims

Admin Setup

To create an administrator account, run the admin creation script:

cd backend
source .venv/bin/activate  # Activate virtual environment
python3 create_admin.py

The script will prompt you to enter:

Username
Full Name
Email
Password (minimum 6 characters)

Once created, you can login with these credentials and access admin features including:

User management (/admin/users)
Post moderation (/admin/posts)
System-wide content management

Development

Running Tests

# Backend tests
cd backend
pytest

# Frontend tests
cd frontend/frontend
npm run test

Database Migrations

cd backend
alembic upgrade head

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

Documentation

Claim System Complete Guide - Complete implementation report of the claim system
User Profile Feature - User profile and rating display feature
Testing Checklist - Comprehensive testing guide
Development Summary - Development completion summary

Current Status

Completed Features (≈ 90%)

✅ User authentication and authorization
✅ User profile management
✅ Forum system with posts and comments
✅ Notification system
✅ Item categories
✅ Image upload (single and multiple)
✅ Advanced search and filtering
✅ Smart matching algorithm
✅ Claim system (NEW)
✅ Rating system (NEW)
✅ Credit score system (NEW)
✅ User profile page (NEW) ✨

Optional Enhancements

⚠️ Admin dashboard
✅ Real-time messaging (WebSocket)
✅ Email notifications
⚠️ Data analytics and reports

License

This project is licensed under the MIT License.

Name		Name	Last commit message	Last commit date
Latest commit History 16 Commits
backend		backend
docs		docs
frontend		frontend
reports		reports
scripts		scripts
tools		tools
.editorconfig		.editorconfig
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
DEMO_GUIDE.md		DEMO_GUIDE.md
DEPLOYMENT.md		DEPLOYMENT.md
EMAIL_SETUP.md		EMAIL_SETUP.md
IMPLEMENTATION_PLAN.md		IMPLEMENTATION_PLAN.md
LICENSE		LICENSE
PROJECT_USAGE.md		PROJECT_USAGE.md
QUICK_DEMO.md		QUICK_DEMO.md
README.md		README.md
README_zh.md		README_zh.md
SYSTEM_TEST.md		SYSTEM_TEST.md
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json
start-project.sh		start-project.sh

Folders and files

Latest commit

History

Repository files navigation

Campus Lost & Found Platform

📌 Project Overview

✨ Core Features

Core Functionality

Lost & Found Features ✨

🚀 Tech Stack

Backend Technologies

Frontend Technologies

📁 Project Structure

🔄 Recent Updates

Frontend Optimization (2024-01-15)

Database Optimization (2024-01-10)

🚧 Development Progress

Completed Features

In Progress

🛠️ Development Guide

Environment Requirements

Quick Start

🤝 Contributing

📄 License

📞 Contact

Core Features

Lost & Found Features ✨

Tech Stack

Backend

Frontend

Project Structure

Getting Started

Prerequisites

Backend Setup

Frontend Setup

Create an Admin User

Seed the Database with Test Data

API Endpoints

Authentication

Users

Categories

Posts (Lost & Found)

Claims ✨

Ratings ✨

Users ✨

Upload

Database Schema

Admin Setup

Development

Running Tests

Database Migrations

Contributing

Documentation

Current Status

Completed Features (≈ 90%)

Optional Enhancements

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages