From 8cce715c8e58baa480098cb7cca223aa132ee20e Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 28 Dec 2025 06:48:59 +0000 Subject: [PATCH 1/2] Initial plan From d12ba542b8378d5a713b30b1e9fb556c92453bd1 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 28 Dec 2025 06:51:57 +0000 Subject: [PATCH 2/2] feat: add Copilot instructions for repository Co-authored-by: happylittle7 <7501374+happylittle7@users.noreply.github.com> --- .github/copilot-instructions.md | 267 ++++++++++++++++++++++++++++++++ 1 file changed, 267 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..f87194e --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,267 @@ +# GitHub Copilot Instructions for Spaghetti-OJ Backend + +This document provides instructions for GitHub Copilot when working on the Spaghetti-OJ (NOJ) backend codebase. + +## Project Overview + +This is the backend system for an Online Judge (OJ) platform built with **Django 5.2.7** and **Django REST Framework 3.16.1**. The system handles code submission, evaluation, course management, and user authentication for programming contests and assignments. + +## Technology Stack + +- **Framework**: Django 5.2.7 with Django REST Framework 3.16.1 +- **Database**: PostgreSQL (production), SQLite (development) +- **Cache & Message Queue**: Redis 7.1.0 +- **Task Queue**: Celery 5.4.0 +- **Authentication**: JWT (djangorestframework_simplejwt 5.5.1) +- **API Documentation**: drf-spectacular 0.29.0 (OpenAPI/Swagger) +- **Testing**: pytest with hypothesis for property-based testing +- **Python Version**: Managed via `.python-version` file + +## Project Structure + +### Main Django Apps + +- **`auths/`** - Authentication and security (JWT tokens, permissions) +- **`user/`** - User management and profiles +- **`profiles/`** - Extended user profile information +- **`courses/`** - Course and member management +- **`problems/`** - Problem management and storage +- **`assignments/`** - Assignment system for courses +- **`submissions/`** - Code submission and evaluation +- **`copycat/`** - Plagiarism detection using MOSS +- **`editor/`** - Code editor related functionality +- **`announcements/`** - Announcement system +- **`search/`** - Search functionality +- **`api_tokens/`** - API token management + +### Configuration + +- **`back_end/settings.py`** - Main Django settings +- **`back_end/celery.py`** - Celery configuration +- **`manage.py`** - Django management script with dotenv support +- **`.env`** - Environment variables (not in Git, use `.env.example` as template) + +## Development Setup + +### Environment Setup + +1. **Python Virtual Environment**: + ```bash + python -m venv .venv + source .venv/bin/activate # macOS/Linux + .venv\Scripts\activate # Windows + ``` + +2. **Install Dependencies**: + ```bash + pip install -r requirements.txt + ``` + +3. **Database Migrations**: + ```bash + python manage.py makemigrations + python manage.py migrate + ``` + +4. **Environment Variables**: Copy `.env.example` to `.env` and configure + +### Required Services + +The project requires **4 concurrent services** during development: + +1. **Redis** (Message queue for Celery): + ```bash + docker-compose -f docker-compose.redis.yml up -d + # Verify: redis-cli ping (should return PONG) + ``` + +2. **Celery Worker** (Async task processing): + ```bash + celery -A back_end worker -l info + # Note: Must restart after code changes in tasks.py + ``` + +3. **Django Development Server**: + ```bash + python manage.py runserver + # Available at http://localhost:8000 + ``` + +4. **Test/Command Terminal**: For running pytest, migrations, etc. + +### API Documentation + +- Swagger UI: `http://localhost:8000/api/schema/swagger-ui/` +- ReDoc: `http://localhost:8000/api/schema/redoc/` + +## Coding Standards + +### File Structure + +- Each Django app follows standard structure: `models.py`, `views.py`, `serializers.py`, `urls.py`, `tests/` +- Tests are organized in `tests/` directories within each app or as `test_*.py` files +- Use pytest fixtures defined in `conftest.py` at the root level + +### Testing + +- **Framework**: pytest (configured in `pytest.ini`) +- **Property-based testing**: Hypothesis (profiles: dev, ci, debug) +- **Test markers**: `@pytest.mark.slow`, `@pytest.mark.unit`, `@pytest.mark.integration`, `@pytest.mark.hypothesis` +- **Fixtures**: + - `api_client()` - DRF APIClient for testing API endpoints + - Tests automatically use in-memory cache to avoid Redis dependency +- **Run tests**: `pytest` or `pytest -m "not slow"` to skip slow tests + +### Code Style + +- Follow Django and DRF conventions +- Use Django's model validation and DRF serializers for data validation +- Handle authentication with JWT tokens via djangorestframework_simplejwt +- Use Celery tasks for long-running operations (e.g., code evaluation) + +### Environment Variables + +Always use environment variables for: +- `DJANGO_DEBUG` - Debug mode flag +- `DJANGO_SECRET_KEY` - Django secret key +- `DB_ENGINE` - Database engine (sqlite/postgresql) +- `CELERY_BROKER_URL` - Redis URL for Celery +- `SANDBOX_API_URL` - External sandbox API for code evaluation +- `CORS_ALLOWED_ORIGINS` - Frontend CORS settings +- `CSRF_TRUSTED_ORIGINS` - CSRF trusted origins + +### Dependencies + +- Add new dependencies to `requirements.txt` with version pinning +- Update via `pip freeze > requirements.txt` after installing new packages +- Coordinate dependency updates with team + +## Git Workflow + +### Branching Strategy + +- **`main`** - Production branch (only team lead/PM can merge) +- **`dev`** - Main development branch (all features merge here) +- **Feature branches** - Created from `dev`, named as: + - `feat/feature-name` - New features + - `fix/bug-description` - Bug fixes + - `docs/documentation-topic` - Documentation + - `refactor/component-name` - Code refactoring + - `chore/task-description` - Configuration/tooling + +### Commit Convention + +Format: `type: subject` + +**Types**: +- `feat` - New feature or functionality +- `fix` - Bug fix +- `docs` - Documentation or comments +- `refactor` - Code refactoring (no functionality change) +- `chore` - Environment/configuration changes + +**Examples**: +``` +feat: add login backend support +fix: correct submission serializer bug +docs: update API usage in README +refactor: simplify course query logic +chore: update Django version to 5.2.7 +``` + +**Best Practice**: Make small, focused commits - commit after completing each logical unit of work. + +### Pull Request Workflow + +1. Create feature branch from `dev` +2. Develop and commit changes +3. Submit PR to `dev` +4. Code review by team +5. Merge to `dev` after approval +6. Team lead/PM merges `dev` to `main` when stable + +## Important Notes + +### Celery Tasks + +- Celery workers do **not** auto-reload on code changes +- After modifying `tasks.py` or related code, **restart the Celery worker** with Ctrl+C and restart +- Tasks are typically in `/tasks.py` (e.g., `submissions/tasks.py`) + +### Database + +- Development uses **SQLite** (file: `db.sqlite3`) +- Production uses **PostgreSQL** +- Database file `db.sqlite3` is in `.gitignore` + +### Sandbox Integration + +- External sandbox API is used for code evaluation +- Configuration in `.env`: `SANDBOX_API_URL`, `SANDBOX_API_KEY`, `SANDBOX_TIMEOUT` +- Async submission handled via Celery tasks + +### Security + +- Never commit `.env` file (already in `.gitignore`) +- Keep `DJANGO_SECRET_KEY` secret and unique per environment +- Use JWT for API authentication +- Validate all user inputs via serializers + +### Files to Ignore + +Already configured in `.gitignore`: +- Virtual environments (`.venv/`, `venv/`, `env/`) +- Database (`db.sqlite3`) +- Python cache (`__pycache__/`, `*.pyc`) +- Environment config (`.env`) +- IDE settings (`.vscode/`, `.idea/`) +- Test artifacts (`.pytest_cache/`, `.hypothesis/`) + +## Common Commands + +```bash +# Database operations +python manage.py makemigrations +python manage.py migrate +python manage.py createsuperuser + +# Testing +pytest # Run all tests +pytest -m "not slow" # Skip slow tests +pytest path/to/test_file.py # Run specific test file + +# Django shell +python manage.py shell + +# Redis verification +redis-cli ping # Should return PONG + +# Celery worker +celery -A back_end worker -l info + +# API documentation +# Visit http://localhost:8000/api/schema/swagger-ui/ +``` + +## Additional Resources + +- Main developer documentation: `docs/developers.MD` (contains detailed Chinese documentation) +- App-specific documentation in `docs/` directory (e.g., `docs/submissions.MD`, `docs/auths.MD`) +- Cache usage documentation: `cache_usage.md` + +## When Making Changes + +1. **Check if services are running**: Redis, Celery, Django server +2. **Run existing tests** before making changes to understand baseline +3. **Make minimal, focused changes** aligned with the task +4. **Write/update tests** for new functionality (if test infrastructure exists) +5. **Update documentation** if changing user-facing behavior or APIs +6. **Follow commit conventions** when committing changes +7. **Restart Celery** if modifying async tasks +8. **Test manually** via API documentation (Swagger UI) when appropriate + +## Language Note + +- Code, comments, and commit messages are primarily in **English** +- Documentation in `docs/` is primarily in **Chinese (Traditional/Simplified)** +- Both languages are acceptable in documentation, but be consistent within a file