haxala1r/Se302
1
0
Fork 0
mirror of https://github.com/sabazadam/Se302.git synced 2025-12-31 20:31:22 +00:00
Code Issues Packages Projects Releases Wiki Activity

Preparation and Planing Documents added to the github

Browse Source
This commit is contained in:
sabazadam
2025-11-30 17:56:12 +03:00
parent 720188328b
commit a8dd7154dd
19 changed files with 10240 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files

563
README.md
View File

@@ -1,96 +1,537 @@
# SE302 - Exam Management System
# Exam Scheduling System
## Project Overview
[![Java CI](https://github.com/sabazadam/se302/workflows/Java%20CI%20with%20Maven/badge.svg)](https://github.com/sabazadam/se302/actions)
[![License: Academic](https://img.shields.io/badge/License-Academic-yellow.svg)](https://opensource.org/licenses/MIT)
This is a desktop application developed as part of the SE302 Software Engineering course. The system is designed to streamline and automate the management of examination schedules, ensuring efficient allocation of resources while preventing conflicts.
A desktop application for automated exam scheduling using Constraint Satisfaction Problem (CSP) solving techniques. Built with Java and JavaFX for educational institutions to efficiently generate conflict-free exam schedules.
## Purpose
---
The Exam Management System aims to solve common challenges faced by educational institutions during examination periods by:
- Managing multiple classes and examination schedules
- Optimizing time slot allocation for exams
- Preventing student scheduling conflicts (collision detection)
- Ensuring fair exam distribution across different time periods
- Reducing administrative workload in exam planning
## Table of Contents
## Key Features
- [Features](#features)
- [Quick Start](#quick-start)
- [Installation](#installation)
- [Usage](#usage)
- [Project Structure](#project-structure)
- [Development](#development)
- [Testing](#testing)
- [Documentation](#documentation)
- [Team](#team)
- [License](#license)
### Planned Features
- **Class Management**: Register and manage multiple classes and courses
- **Exam Scheduling**: Create and organize exam schedules with date and time allocation
- **Conflict Detection**: Automatic detection of scheduling conflicts for students enrolled in multiple courses
- **Collision Avoidance**: Intelligent algorithm to prevent students from having overlapping exams
- **Time Optimization**: Efficient distribution of exams across available time slots
- **Student Management**: Track student enrollments and exam assignments
- **Reporting**: Generate reports on exam schedules and potential conflicts
---
## Technology Stack
## Features
*To be updated as development progresses*
### Core Functionality
- **Platform**: Desktop Application
- **Programming Language**: [TBD]
- **Database**: [TBD]
- **UI Framework**: [TBD]
- **CSV Data Import**: Import students, courses, classrooms, and enrollment data from CSV files
- **Intelligent Scheduling**: Automated exam scheduling using backtracking CSP solver
- **Constraint Validation**: Enforces hard constraints:
- No consecutive exams for any student
- Maximum 2 exams per student per day
- Classroom capacity limits respected
- **Multiple Optimization Strategies**:
- Minimize days used
- Balance distribution across exam period
- Minimize classrooms needed
- Balance classroom usage per day
- **Multi-View Display**:
- Classroom view (which exams in which rooms)
- Student view (personal exam schedule)
- Course view (exam details per course)
- Day view (grid layout by day and time slot)
- **Export Capabilities**: Export schedules to CSV or Excel (.xlsx) format
- **Manual Adjustments**: Edit schedules with real-time constraint validation
- **Schedule History**: Save, load, and compare previous schedules
- **Conflict Detection**: Detailed reporting when no valid schedule exists
## Project Structure
### Technical Highlights
```
se302/
├── src/ # Source code files
├── docs/ # Documentation
├── tests/ # Test files
└── README.md # Project documentation
```
- **Performance**: Generates schedules for 20 courses, 250 students in < 5 seconds
- **Scalability**: Handles datasets up to 50 courses, 500+ students
- **Reliability**: 100% constraint satisfaction guarantee
- **User-Friendly**: Clear error messages, progress indicators, intuitive UI
## Installation
---
*Installation instructions will be added as the project develops*
## Quick Start
```bash
# Clone the repository
git clone https://github.com/sabazadam/se302.git
cd se302
# Further installation steps to be added
# Build the project
mvn clean install
# Run the application
mvn javafx:run
```
---
## Installation
### Prerequisites
- **Java Development Kit (JDK) 17 or higher**
- Download: [Oracle JDK](https://www.oracle.com/java/technologies/downloads/) or [OpenJDK](https://adoptium.net/)
- **Maven 3.8+** (for building from source)
- Download: [Apache Maven](https://maven.apache.org/download.cgi)
- **Operating System**: Windows 10/11, macOS, or Linux
- **Minimum Hardware**:
- 2 GHz dual-core processor
- 4 GB RAM
- 100 MB disk space
### Installation Steps
#### Option 1: Run from JAR (Recommended for Users)
1. Download the latest release JAR from [Releases](https://github.com/sabazadam/se302/releases)
2. Double-click the JAR file or run from command line:
```bash
java -jar exam-scheduler-1.0.0-jar-with-dependencies.jar
```
#### Option 2: Build from Source (For Developers)
1. **Clone the repository:**
```bash
git clone https://github.com/sabazadam/se302.git
cd se302
```
2. **Build the project:**
```bash
mvn clean package
```
3. **Run the application:**
```bash
mvn javafx:run
```
Or run the generated JAR:
```bash
java -jar target/exam-scheduler-1.0.0-jar-with-dependencies.jar
```
---
## Usage
*Usage instructions will be provided once the application is developed*
### 1. Import Data
## Development Roadmap
1. Click **Import Data** in the navigation panel
2. Select your CSV files:
- **Students**: List of student IDs (one per line)
- **Courses**: List of course codes (one per line)
- **Classrooms**: Format `ClassroomID;Capacity` (e.g., `Room_01;40`)
- **Enrollments**: Student-course enrollment mappings
3. Click **Import All** and verify success
- [ ] Requirements analysis and specification
- [ ] System design and architecture
- [ ] Database schema design
- [ ] Core functionality implementation
- [ ] User interface development
- [ ] Conflict detection algorithm implementation
- [ ] Testing and quality assurance
- [ ] Documentation and deployment
**CSV Format Examples:**
## Contributing
`students.csv`:
```
Std_ID_001
Std_ID_002
Std_ID_003
```
This is an academic project for SE302 course. Contributions are limited to project team members.
`classrooms.csv`:
```
Classroom_01;40
Classroom_02;35
Classroom_03;50
```
### Team Members
- [Add team member names here]
### 2. Configure Exam Period
1. Click **Configure** in the navigation panel
2. Set **Number of Days** (e.g., 5 days)
3. Set **Time Slots Per Day** (e.g., 4 slots)
4. Total available slots = Days × Slots (e.g., 5 × 4 = 20 slots)
5. Choose **Optimization Strategy**:
- **Minimize Days**: Pack exams into fewest days
- **Balance Distribution**: Spread exams evenly
- **Minimize Classrooms**: Use fewest rooms
- **Balance Classrooms**: Even room usage per day
6. Click **Save Configuration**
### 3. Generate Schedule
1. Click **Generate** in the navigation panel
2. Review configuration summary
3. Click **Generate Schedule**
4. Watch progress bar (cancellation available)
5. View success/failure result
**If generation fails**, view conflict report for:
- Students with too many courses
- Courses exceeding classroom capacity
- Recommendations to resolve conflicts
### 4. View Schedule
After successful generation, view schedule in 4 different formats:
- **Classroom View**: See which exams are in each classroom
- **Student View**: Search for a student's personal exam schedule
- **Course View**: See when each course exam is scheduled
- **Day View**: Visual grid of all exams by day and time slot
### 5. Export Schedule
1. Click **Export** in the navigation panel
2. Choose format: CSV or Excel
3. Select which views to export (can export all 4 views)
4. Choose destination folder
5. Click **Export**
Excel exports create a multi-sheet workbook with formatted tables ready for printing.
---
## Project Structure
```
se302/
├── src/
│ ├── main/
│ │ ├── java/com/se302/examscheduler/
│ │ │ ├── model/ # Domain models (Student, Course, etc.)
│ │ │ ├── dao/ # Data Access Objects
│ │ │ ├── service/ # Business logic layer
│ │ │ ├── algorithm/ # CSP solver implementation
│ │ │ ├── controller/ # JavaFX controllers
│ │ │ ├── util/ # Utility classes
│ │ │ └── Main.java # Application entry point
│ │ └── resources/
│ │ ├── fxml/ # JavaFX FXML layouts
│ │ ├── css/ # Stylesheets
│ │ ├── images/ # Icons and images
│ │ └── database/ # SQL schema
│ └── test/
│ └── java/com/se302/examscheduler/
│ ├── dao/ # DAO tests
│ ├── service/ # Service tests
│ ├── algorithm/ # Algorithm tests
│ └── integration/ # Integration tests
├── docs/ # Documentation
│ ├── MEMORY_BANK.md # Comprehensive project documentation
│ ├── ROADMAP.md # Development roadmap
│ ├── TEAM_ASSIGNMENTS.md # Team roles and responsibilities
│ ├── GIT_WORKFLOW.md # Git workflow guide
│ └── screenshots/ # Application screenshots
├── .github/
│ └── workflows/
│ └── ci.yml # GitHub Actions CI/CD
├── pom.xml # Maven configuration
├── .gitignore # Git ignore rules
└── README.md # This file
```
---
## Development
### Prerequisites for Development
- Java JDK 17+
- Maven 3.8+
- IDE: IntelliJ IDEA (recommended) or Eclipse
- Scene Builder (for FXML editing): [Download](https://gluonhq.com/products/scene-builder/)
- Git
### Setup Development Environment
1. **Clone the repository:**
```bash
git clone https://github.com/sabazadam/se302.git
cd se302
```
2. **Import into IDE:**
- IntelliJ IDEA: File → Open → Select `pom.xml`
- Eclipse: File → Import → Existing Maven Projects
3. **Configure JDK 17:**
- IntelliJ: File → Project Structure → Project SDK → Select JDK 17
- Eclipse: Right-click project → Properties → Java Build Path → JRE System Library
4. **Build the project:**
```bash
mvn clean install
```
5. **Run from IDE:**
- Main class: `com.se302.examscheduler.Main`
- VM options: `--module-path /path/to/javafx-sdk/lib --add-modules javafx.controls,javafx.fxml`
### Git Workflow
We follow a **feature branch workflow** with `main` and `develop` branches:
1. Create feature branch from `develop`:
```bash
git checkout develop
git pull origin develop
git checkout -b feature/your-feature-name
```
2. Make changes and commit:
```bash
git add .
git commit -m "feat(scope): brief description"
```
3. Push and create Pull Request:
```bash
git push origin feature/your-feature-name
```
4. After PR approval, merge to `develop`
5. Delete feature branch after merge
**See [GIT_WORKFLOW.md](GIT_WORKFLOW.md) for detailed guidelines.**
### Coding Standards
- **Java Naming Conventions**: camelCase for variables/methods, PascalCase for classes
- **JavaDoc**: Required for all public methods
- **Comments**: Explain "why" not "what"
- **Max line length**: 120 characters
- **Indentation**: 4 spaces (no tabs)
- **Formatting**: Follow Java standard code style
---
## Testing
### Running Tests
```bash
# Run all tests
mvn test
# Run specific test class
mvn test -Dtest=StudentDAOTest
# Run with coverage report
mvn clean test jacoco:report
# View coverage report
open target/site/jacoco/index.html
```
### Test Coverage Goals
- **Overall**: > 70% line coverage
- **DAO Layer**: > 90%
- **Algorithm Layer**: > 95%
- **Service Layer**: > 80%
- **Controller Layer**: > 70%
### Continuous Integration
GitHub Actions automatically runs tests on every push and pull request:
- Compiles code
- Runs all tests
- Generates coverage report
- Uploads to Codecov
See [.github/workflows/ci.yml](.github/workflows/ci.yml) for CI configuration.
---
## Documentation
### User Documentation
- **User Manual** (PDF): Comprehensive guide with screenshots (coming in Week 10)
- **Installation Guide**: See [Installation](#installation) section above
- **Troubleshooting Guide**: (coming soon)
### Developer Documentation
- **Memory Bank**: [MEMORY_BANK.md](MEMORY_BANK.md) - Comprehensive project documentation including:
- Requirements summary
- Database schema
- Architecture and design patterns
- Algorithm design
- API contracts
- Testing strategy
- **Roadmap**: [ROADMAP.md](ROADMAP.md) - Week-by-week development plan
- **Team Assignments**: [TEAM_ASSIGNMENTS.md](TEAM_ASSIGNMENTS.md) - Roles and responsibilities
- **Git Workflow**: [GIT_WORKFLOW.md](GIT_WORKFLOW.md) - Branching strategy and PR process
- **JavaDoc**: Generate with `mvn javadoc:javadoc`, view at `target/site/apidocs/index.html`
### API Documentation
Generate JavaDoc:
```bash
mvn javadoc:javadoc
open target/site/apidocs/index.html
```
---
## Team
**SE302 - Software Engineering | Team 3, Section 1**
| Name | Student ID | Role |
|------|-----------|------|
| Kerem Bozdag | 20200602012 | Database & Data Layer Lead |
| Milena Larissa Ünal | 20230602107 | Algorithm Specialist |
| Rabia Tülay Gokdag | 20210602029 | UI/FXML Specialist |
| Mehmet Sefa Keskin | 20230602047 | Controller Layer Lead |
| Feyza Gereme | 20230602028 | Testing & QA Lead |
| Emin Arslan | 20230602007 | Documentation & Integration Lead |
---
## Technology Stack
- **Language**: Java 17
- **UI Framework**: JavaFX 21
- **Database**: SQLite 3.44
- **Build Tool**: Maven 3.8+
- **Testing**: JUnit 5, Mockito, TestFX
- **Libraries**:
- Apache POI (Excel export)
- Apache Commons CSV (CSV parsing)
- SQLite JDBC
- **CI/CD**: GitHub Actions
- **Code Coverage**: JaCoCo
---
## Architecture
The application follows the **Model-View-Controller (MVC)** architectural pattern:
- **Model**: Domain objects (Student, Course, Classroom, etc.) and business logic
- **View**: JavaFX FXML layouts and UI components
- **Controller**: JavaFX controllers handling user interactions
**Key Design Patterns**:
- **DAO Pattern**: Data access abstraction
- **Strategy Pattern**: Pluggable optimization strategies
- **Singleton Pattern**: Database connection management
- **Observer Pattern**: Progress tracking for long-running operations
- **Factory Pattern**: DAO instantiation
---
## Algorithm
The scheduling algorithm uses **Backtracking with Constraint Propagation**:
1. **Variables**: Each course is a variable needing assignment
2. **Domain**: Each course can be assigned to {Classroom, Day, TimeSlot} triple
3. **Constraints**:
- No consecutive exams for any student
- Max 2 exams per student per day
- Classroom capacity limits
4. **Heuristics**:
- **Variable ordering**: Minimum Remaining Values (MRV)
- **Value ordering**: Least Constraining Value
5. **Optimization**: Strategy-based heuristics affect value ordering
See [MEMORY_BANK.md](MEMORY_BANK.md#algorithm-design) for detailed algorithm documentation.
---
## Course Information
- **Course**: SE302 - Software Engineering
- **Institution**: [Your University Name]
- **Academic Year**: [Year/Semester]
## License
This project is developed for educational purposes as part of SE302 coursework.
## Contact
For questions or issues related to this project, please contact the project team members or the course instructor.
- **Section**: 1
- **Team**: 3
- **Academic Year**: 2025-2026 Fall Semester
- **Project Start**: November 26, 2025
- **Final Delivery**: February 4, 2026
---
*Last Updated: October 2025*
## License
This project is developed as part of SE302 Software Engineering course.
**Academic Use Only** - Not licensed for commercial use.
Copyright © 2025 Team 3, Section 1. All rights reserved.
---
## Frequently Asked Questions
### Q: What happens if no valid schedule exists?
**A:** The system will detect conflicts and provide a detailed report identifying:
- Students with too many courses for the available slots
- Courses with enrollment exceeding maximum classroom capacity
- Specific recommendations to resolve the issue (extend period, add classrooms, reduce enrollments)
### Q: Can I run multiple schedules with different configurations?
**A:** Yes! The system saves schedule history with metadata (date, optimization strategy, configuration). You can generate multiple schedules and compare them.
### Q: Can I edit a generated schedule manually?
**A:** Yes, but all edits are validated against constraints in real-time. If an edit would violate a constraint (e.g., create consecutive exams for a student), the system will reject it with a detailed explanation.
### Q: How fast is the scheduling algorithm?
**A:** For the sample dataset (20 courses, 250 students, 10 classrooms), generation typically completes in < 5 seconds. Larger datasets (50 courses, 500 students) complete in < 10 seconds.
### Q: Can I use this on macOS or Linux?
**A:** Yes! The application is built with Java and JavaFX, which are cross-platform. It works on Windows, macOS, and Linux.
---
## Development Progress
### Completed
- [x] Requirements analysis and specification
- [x] System design and architecture
- [x] Database schema design
- [x] Project structure and Maven setup
- [x] Git workflow and CI/CD pipeline
- [x] Comprehensive documentation (Memory Bank, Roadmap, Team Assignments)
### In Progress (Week 1)
- [ ] Database layer implementation
- [ ] CSV import functionality
- [ ] Domain model classes
- [ ] UI wireframes and layouts
### Planned
- [ ] CSP solver implementation
- [ ] Optimization strategies
- [ ] JavaFX UI views
- [ ] Export functionality
- [ ] Testing and quality assurance
- [ ] User manual and final documentation
See [ROADMAP.md](ROADMAP.md) for detailed week-by-week plan.
---
## Contact
For questions or issues related to this project:
- Create an issue on GitHub
- Contact team members (see [Team](#team) section)
- Contact course instructor
---
*Last Updated: November 26, 2025*
For comprehensive project documentation, see [MEMORY_BANK.md](MEMORY_BANK.md).