# courses

**Repository Path**: zgcai/courses

## Basic Information

- **Project Name**: courses
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-05
- **Last Updated**: 2026-03-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Oscanner Report

A full-stack application for automatically posting evaluation reports to student Gitee repositories.

## Overview

This application allows you to:
- Upload evaluation report images
- Automatically create issues named "oscanner评估报告" in student repositories
- Add comments to existing issues if they already exist
- Process multiple students and repositories in batch

## Architecture

- **Backend**: FastAPI (Python) - RESTful API server
- **Frontend**: React + Ant Design - Modern web interface

## Quick Start

### Prerequisites

- Python 3.8+
- Node.js 16+
- Gitee Access Token ([Get it here](https://gitee.com/profile/personal_access_tokens))

### One-Command Start (Recommended)

Run both backend and frontend with a single command:

```bash
./start.sh
```

This will:
- Create a Python virtual environment (if needed)
- Install all backend dependencies
- Install all frontend dependencies
- Start both servers automatically

Then open your browser to `http://localhost:3000`

Press `Ctrl+C` to stop both servers.

### Manual Setup

If you prefer to run the backend and frontend separately:

#### Backend Setup

1. Navigate to the backend directory:
```bash
cd backend
```

2. Install Python dependencies:
```bash
pip install -r requirements.txt
```

3. Start the FastAPI server:
```bash
python main.py
```

The backend will run at `http://localhost:8000`

### Frontend Setup

1. Navigate to the frontend directory:
```bash
cd frontend
```

2. Install Node.js dependencies:
```bash
npm install
```

3. Start the development server:
```bash
npm run dev
```

The frontend will run at `http://localhost:3000`

## Usage

1. Open your browser and go to `http://localhost:3000`
2. Enter your Gitee Access Token
3. Input student data in JSON format (click "填充示例数据" button to see the format):
```json
{
  "students": [
    {
      "username": "kevinboll",
      "url": ["https://gitee.com/kevinboll/zgc-wbx.git"],
      "organization": "",
      "pq_id": "FWSYEM6V"
    },
    {
      "username": "MZ",
      "url": ["https://gitee.com/mz528/mz_VibleCoding"],
      "organization": "datawhale",
      "pq_id": ""
    }
  ]
}
```
4. Upload the evaluation report image (example: `../vibecode-bootcamp/course1_result.png`)
5. Click "Submit" to process all repositories
6. View the results in the table

## Features

### Backend Features
- Gitee API integration
- Issue existence checking
- Automatic issue creation or comment addition
- Base64 image encoding for embedding
- Comprehensive error handling
- Support for multiple repositories per student

### Frontend Features
- Clean and intuitive UI with Ant Design
- JSON editor with syntax highlighting
- Drag-and-drop image upload
- Real-time processing results
- Statistics dashboard
- Responsive design

## Scheduled Report Pipeline

The scheduled report pipeline allows you to automatically run code analysis, tests, and post reports at a specific time.

### Installation

First, install the required dependency:

```bash
cd backend
pip install -r requirements.txt
```

### Usage

**Run at a specific time (24-hour format):**
```bash
cd backend
python scheduled_report.py --time "14:30"
```

This will run at 2:30 PM today. If it's already past 2:30 PM, it will schedule for tomorrow.

**Run at a specific date and time:**
```bash
python scheduled_report.py --time "09:00" --date "2026-02-15"
```

**Run immediately (no scheduling):**
```bash
python scheduled_report.py --now
```

**Using the helper script:**
```bash
cd backend
./run_scheduled_report.sh --time "14:30"
```

### What it does

The pipeline runs three steps in sequence:

1. **Code Analysis** (`/api/courses/analyse_code`): Analyzes code for all students in `backend/result/users.json`
2. **Testing** (`/api/courses/test`): Runs tests for all students
3. **Post Reports** (`/api/post-reports`): Posts evaluation reports to all student repositories

### Requirements

- Backend server must be running on `http://localhost:8003`
- `GITEE_TOKEN` must be set in the `.env` file
- Student data must be available in `backend/result/users.json`

### Example Output

```
================================================================================
⏰ Evaluation Report Pipeline Scheduler
================================================================================
📅 Scheduled run time: 2026-02-09 14:30:00
⏱️  Current time: 2026-02-09 10:15:23
⏳ Time until execution: 4h 14m 37s
================================================================================

✅ Scheduler started. Press Ctrl+C to cancel.
```

## API Endpoints

### POST /api/courses/analyse_code
Analyze code quality for a student repository.

**Request:**
```json
{
  "repo_url": "https://gitee.com/student/repo"
}
```

**Response:**
```json
{
  "success": true,
  "message": "Analysis completed",
  "checkpoint": {...},
  "commits_analyzed": 10
}
```

### POST /api/courses/test
Run tests on a student repository.

**Request:**
```json
{
  "repo_url": "https://gitee.com/student/repo"
}
```

**Response:**
```json
{
  "repo_name": "student/repo",
  "passed": 8,
  "failed": 2,
  "total": 10,
  "score": 80,
  "message": "Test execution completed successfully."
}
```

### POST /api/post-reports
Post evaluation reports to student repositories.

**Request:**
- Form Data:
  - `students_data`: JSON string (includes students array and access_token)
  - `image`: Image file

**Response:**
```json
[
  {
    "username": "kevinboll",
    "repo_url": "https://gitee.com/kevinboll/zgc-wbx.git",
    "status": "issue_created",
    "message": "New issue created",
    "issue_url": "https://gitee.com/kevinboll/zgc-wbx/issues/1"
  }
]
```

## Project Structure

```
.
├── backend/
│   ├── main.py              # FastAPI application
│   ├── requirements.txt     # Python dependencies
│   ├── .gitignore          # Git ignore rules
│   └── README.md           # Backend documentation
├── frontend/
│   ├── src/
│   │   ├── App.jsx         # Main React component
│   │   ├── main.jsx        # Entry point
│   │   └── index.css       # Global styles
│   ├── package.json        # Node.js dependencies
│   ├── vite.config.js      # Vite configuration
│   ├── .gitignore          # Git ignore rules
│   └── README.md          # Frontend documentation
├── start.sh               # Quick start script
└── README.md              # This file
```

## Development

### Backend API Documentation

Once the backend is running, visit:
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc

### Building for Production

**Frontend:**
```bash
cd frontend
npm run build
```

The production files will be in `frontend/dist`

## Troubleshooting

### CORS Issues
Make sure the backend is running and configured to allow requests from the frontend origin.

### Gitee API Errors
- Check your access token is valid
- Ensure you have permissions to create issues in the target repositories
- Verify the repository URLs are correct

### Image Upload Issues
- Only image files (PNG, JPG, JPEG, etc.) are supported
- Check file size limits

## License

MIT