# 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-09-14

## 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 18+
- Docker + Docker Compose, if you prefer the containerized setup
- 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:3003`

Press `Ctrl+C` to stop both servers.

### Docker Setup

If you prefer to run both services in containers:

```bash
docker compose up --build
```

This starts:
- Backend API at `http://localhost:8003`
- Frontend dev server at `http://localhost:3003`

The compose file bind-mounts `backend/` and `frontend/`, so code changes are picked up by FastAPI reload and Vite. If you have secrets or API keys, put them in `backend/.env`; the backend container reads that file through the bind mount.

Useful Docker commands:

```bash
# Start in the background
docker compose up --build -d

# View logs
docker compose logs -f

# Stop services
docker compose down
```

### 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:8003`

### 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:3003`

## Usage

1. Open your browser and go to `http://localhost:3003`
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/students.json`
2. **Testing** (`/api/courses/test`): Runs tests for all students
3. **Post Reports** (`/api/post-reports`): Posts evaluation reports to all student repositories

### Course Testing Reports

`/api/courses/test` delegates repository execution to Oscanner's repos_runner
`/api/runner/run-all` endpoint and stores the returned checkpoint in the course
test data. For tagged submissions, repos_runner writes `TEST_REPORT_{tag}.md`
inside the cloned repository and returns the report content to the course API.

The report starts with an overview and the features to test:

- **老师要求（可以为空，为空则表示"学生任意发挥"）**: the standard tag description from
  `backend/result/courses.json`.
- **学生自述功能**: the tag description from the student repository.

The score has two parts:

1. **代码测试**: unit/integration/test commands executed from the repository.
2. **功能验收**: tag-derived required feature coverage from static checks,
   service/API runtime evidence, and UI evidence.

When tag requirements are present, weights are dynamic:

```text
final_score = code_pass_rate × code_relevance_ratio × code_weight
            + functionality_coverage_ratio × functionality_weight
```

`code_weight` ranges from 30 to 40 based on how much the repository's tests
cover the required features. `functionality_weight` is the remainder, from 70 to
60. If no relevant code tests are found, code tests score 0 and functional
acceptance can still earn up to 70.

If no tag requirements are available, the score falls back to the code test pass
rate out of 100.

Runtime evidence reads README-like documentation and recognizes safe local
startup patterns such as `python scripts/start.py start`, `python scripts/dev-*.py`,
`uvicorn <module>:<app> --port <port>`, `python -m uvicorn ...`, and `npm run dev`.
It follows simple `cd <relative-dir>` lines in shell blocks, but it does not run
arbitrary README commands. Under the Docker executor, Chromium and CJK fonts are
preinstalled in the runner image so UI evidence can include screenshots and
rendered DOM checks without installing Playwright inside each student repo.

Windows-specific virtualenv activation lines such as `.venv\Scripts\activate`
are normalized to Linux/Docker startup (`. .venv/bin/activate`) when the runner
constructs a safe service command. If the Oscanner runner enables
`REPOS_RUNNER_RUNTIME_COMPAT_LLM=true`, DeepSeek/OpenRouter can suggest missing
Linux/Docker-compatible startup commands, but every suggestion is validated
against the same safe command allowlist before execution.

Directory checks use the cloned Git tree. Git does not preserve empty directories,
so required empty directories such as `.harness/datasets/`, `.harness/eval/`, and
`.harness/logs/` must contain a committed placeholder file like `.gitkeep`.

### 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/students.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",
  "username": null
}
```

`username` behavior:
- Omit or empty string: backend auto-detects latest commit author.
- Non-empty string: use that author for analysis.
- `null`: analyze without single-author filtering (all repo authors are included).

**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
├── docker-compose.yml    # Docker startup for backend + frontend
├── start.sh               # Local quick start script
└── README.md              # This file
```

## Development

### Backend API Documentation

Once the backend is running, visit:
- Swagger UI: http://localhost:8003/docs
- ReDoc: http://localhost:8003/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