# Students API

The Students module manages student profiles, enrollment, and related data.

## Model

```json
{
  "id": "uuid",
  "code": "STD001",
  "moet_id": "M12345678",
  "status": "active",
  "enrollment_date": "2024-09-01",
  "enrollment_year": 2024,

  "first_name": "John",
  "last_name": "Doe",
  "nickname": "Johnny",
  "name": "Doe John",
  "birthdate": "2010-05-15",
  "gender": "Male",
  "email": "john.doe@school.edu",
  "phone_mobile": "+84123456789",

  "avatar": "https://...",
  "personal_id_number": "123456789",
  "nationality": "Vietnam",
  "ethnicity": "Kinh",
  "religion": "None",

  "address": "123 Main Street",
  "district": "District 1",
  "province": "Ho Chi Minh City",
  "country": "Vietnam",

  "cur_address": "456 Current Street",
  "cur_district": "District 2",
  "cur_province": "Ho Chi Minh City",

  "current_class_id": "class-uuid",
  "current_class": { "id": "...", "name": "Class 10A" },

  "program_id": "program-uuid",
  "program": { "id": "...", "name": "Academic Program" },

  "lms_active": true,
  "lms_id": "canvas-123",
  "lms_user": "johndoe",

  "app_active": true,
  "app_user": "johndoe",

  "team_id": "team-uuid",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}
```

## Status Values

| Status | Description |
|--------|-------------|
| `applicant` | Application submitted, not yet enrolled (default) |
| `active` | Currently enrolled student |
| `alumni` | Graduated student |
| `withdrawal` | Withdrawn from school |

## Model Fields

The Student model embeds several interfaces for shared fields:

### Base Fields (from BaseModel)
- `id` - UUID primary key (auto-generated)
- `name` - Display name (auto-generated from first/last name)
- `description` - Optional description
- `team_id` - Multi-tenant team/campus ID
- `created_at`, `updated_at`, `deleted_at` - Timestamps
- `created_by_id`, `updated_by_id`, `deleted_by_id` - Audit user IDs
- `assigned_to_id` - Assigned staff member

### Student-Specific Fields
- `code` - Student code (auto-generated or manual)
- `moet_id` - Ministry of Education ID (Vietnam)
- `status` - Enrollment status (see above)
- `enrollment_date` - Date of enrollment
- `enrollment_year` - Year of enrollment
- `sace_regis_number` - SACE registration number
- `source` - Lead source (`direct`, `other`)
- `current_class_id` - Current homeroom class
- `program_id` - Academic program
- `user_id` - Linked user account
- `need_canvas_sync` - Flag for Canvas LMS sync

### Person Fields (from Person interface)
- `avatar` - Profile image URL
- `first_name`, `last_name` - Name components
- `nickname` - Optional nickname
- `full_name_first_last`, `full_name_last_first` - Computed full names
- `birthdate` - Date of birth
- `gender` - `None`, `Male`, `Female`
- `email` - Email address
- `phone_mobile` - Mobile phone number
- `personal_id_number` - National ID number
- `nationality`, `ethnicity`, `religion` - Demographics

### Address Fields (4 address types)

**Permanent Address:**
- `country`, `province`, `district`, `ward`
- `address`, `address_ext`

**Current Address:**
- `cur_country`, `cur_province`, `cur_district`, `cur_ward`
- `cur_address`, `cur_address_ext`

**Birth Place Address:**
- `birth_place_country`, `birth_place_province`, `birth_place_district`, `birth_place_ward`
- `birth_place_address`, `birth_place_address_ext`

**Birth Registration Address:**
- `birth_regis_country`, `birth_regis_province`, `birth_regis_district`, `birth_regis_ward`
- `birth_regis_address`, `birth_regis_address_ext`

### Mobile App Integration
- `app_active` - Mobile app account active
- `app_user` - Mobile app username
- `app_pass` - Mobile app password (write-only)
- `app_last_login` - Last mobile app login

### LMS Integration
- `lms_active` - LMS account active
- `lms_id` - Canvas LMS user ID
- `lms_user` - LMS username
- `lms_pass` - LMS password (write-only)

## Endpoints

### List Students

**Endpoint:** `POST /api/students/list`

**Request:**
```json
{
  "page": 1,
  "limit": 20,
  "search": "john",
  "sort_field": "name",
  "sort_direction": "asc",
  "filter": {
    "group": "AND",
    "conditions": [
      {"field": "status", "operator": "=", "value": "active"},
      {"field": "current_class_id", "operator": "=", "value": "class-uuid"}
    ]
  },
  "preloads": ["CurrentClass", "Program"]
}
```

**Response:**
```json
{
  "success": true,
  "message": "Records retrieved successfully",
  "data": {
    "list": [
      {
        "id": "student-uuid",
        "code": "STD001",
        "name": "Doe John",
        "status": "active",
        "current_class": { "id": "...", "name": "Class 10A" }
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150
    }
  }
}
```

### Get Student by ID

**Endpoint:** `GET /api/students/:id`

**Response:**
```json
{
  "success": true,
  "message": "Record retrieved",
  "data": {
    "id": "student-uuid",
    "code": "STD001",
    "first_name": "John",
    "last_name": "Doe",
    "name": "Doe John",
    "email": "john.doe@school.edu",
    "status": "active",
    "current_class": { ... },
    "student_enroll_classes": [ ... ],
    "student_enroll_courses": [ ... ]
  }
}
```

### Create Student

**Endpoint:** `POST /api/students`

**Request:**
```json
{
  "first_name": "Jane",
  "last_name": "Smith",
  "email": "jane.smith@school.edu",
  "birthdate": "2010-05-15",
  "gender": "Female",
  "status": "applicant",
  "enrollment_date": "2024-09-01",
  "phone_mobile": "+84123456789",
  "address": "123 Main Street",
  "province": "Ho Chi Minh City",
  "current_class_id": "class-uuid",
  "program_id": "program-uuid"
}
```

**Response:**
```json
{
  "success": true,
  "message": "Record created successfully",
  "data": {
    "id": "new-student-uuid",
    "code": "STD002",
    "first_name": "Jane",
    "last_name": "Smith",
    "status": "applicant"
  }
}
```

!!! note "Auto-generated Code"
    The `code` field is auto-generated if not provided. The format is defined in AutoCode settings.

### Update Student

**Endpoint:** `PUT /api/students/:id`

**Request:**
```json
{
  "status": "active",
  "current_class_id": "new-class-uuid",
  "phone_mobile": "+84987654321"
}
```

### Delete Student

**Endpoint:** `DELETE /api/students/:id`

Soft-deletes the student record.

### Bulk Create Students

**Endpoint:** `POST /api/students/bulk`

**Request:**
```json
{
  "items": [
    { "first_name": "Student", "last_name": "One", ... },
    { "first_name": "Student", "last_name": "Two", ... }
  ]
}
```

### Bulk Delete Students

**Endpoint:** `DELETE /api/students/bulk`

**Request:**
```json
{
  "ids": ["student-uuid-1", "student-uuid-2"]
}
```

### Export to Excel

**Endpoint:** `POST /api/students/export`

**Request:**
```json
{
  "filter": {
    "group": "AND",
    "conditions": [
      {"field": "status", "operator": "=", "value": "active"}
    ]
  }
}
```

**Response:** Excel file download

### Import from Excel

**Endpoint:** `POST /api/students/import`

**Request:** Multipart form data with Excel file

See [Import System Guide](../../guides/import-system.md) for detailed import workflow.

## Enrollment Endpoints

### Get Student's Class Enrollments

**Endpoint:** `POST /api/students/list_relate/:student_id/student_enroll_classes/StudentEnrollClass`

Lists all class enrollments for a student.

### Enroll Student in Class

**Endpoint:** `PUT /api/students/list_relate/:student_id/student_enroll_classes/StudentEnrollClass`

**Request:**
```json
{
  "ids": ["enrollment-uuid"]
}
```

Or create enrollment directly via the StudentEnrollClass endpoint.

### Get Student's Course Enrollments

**Endpoint:** `POST /api/students/list_relate/:student_id/student_enroll_courses/StudentEnrollCourse`

## Special Endpoints

### Force Canvas Sync

Trigger immediate sync of student data to Canvas LMS.

**Endpoint:** `POST /api/students/:id/force-sync-canvas`

**Response:**
```json
{
  "success": true,
  "message": "Canvas sync triggered"
}
```

## Searchable Fields

The search parameter queries these fields:

- `code` - Student code
- `moet_id` - Ministry of Education ID
- `full_name_first_last` - Full name (First Last)
- `full_name_last_first` - Full name (Last First)
- `nickname` - Student nickname
- `email` - Email address

## Filterable Fields

| Field | Type | Description |
|-------|------|-------------|
| `code` | text | Student code |
| `status` | enum | Student status |
| `gender` | enum | Gender |
| `enrollment_year` | int | Year of enrollment |
| `current_class_id` | relate | Current homeroom class |
| `program_id` | relate | Academic program |
| `team_id` | relate | Campus/school |
| `birthdate` | date | Date of birth |
| `lms_active` | bool | LMS account active |

## Related Modules

| Module | Relationship | Description |
|--------|--------------|-------------|
| Class | many-to-many (via StudentEnrollClass) | Class enrollments |
| Course | many-to-many (via StudentEnrollCourse) | Course enrollments |
| Program | belongs to | Academic program |
| Attendance | has many | Attendance records |
| Behavior | has many | Behavior records |
| Gradebook | has many | Grade records |
| Guardian | many-to-many (via PersonRelationship) | Parents/guardians |
| MedicalRecord | has many | Health records |

## Canvas LMS Integration

When Canvas sync is enabled:

1. Student creation triggers Canvas user creation
2. Student updates sync to Canvas profile
3. Course enrollments sync to Canvas enrollments
4. Assessment results sync from Canvas gradebook

Set `need_canvas_sync: true` to trigger sync on next job run.

## Code Examples

### JavaScript - List Active Students

```javascript
const response = await fetch('/api/students/list', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'X-Team-ID': teamId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    page: 1,
    limit: 50,
    filter: {
      group: 'AND',
      conditions: [
        { field: 'status', operator: '=', value: 'active' }
      ]
    },
    preloads: ['CurrentClass', 'Program']
  })
});

const data = await response.json();
console.log(data.data.list);
```

### JavaScript - Create Student

```javascript
const response = await fetch('/api/students', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'X-Team-ID': teamId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    first_name: 'New',
    last_name: 'Student',
    email: 'new.student@school.edu',
    birthdate: '2010-01-15',
    gender: 'Male',
    status: 'applicant'
  })
});

const data = await response.json();
console.log('Created student:', data.data.code);
```

### cURL - Search Students

```bash
curl -X POST http://localhost:8080/api/students/list \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Team-ID: $TEAM_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "search": "john",
    "page": 1,
    "limit": 20
  }'
```