campus-placement-engine / docs /OFFICER_USER_GUIDE.md

feat: institutional campus placement eligibility & interview scheduling engine

788eab4 verified 6 days ago

7.11 kB

# Institutional Placement Engine: Placement Officer & Coordinator Guide (v1.0.0)

## Welcome to the Campus Placement Engine

The Institutional Placement Engine is a purpose-built, 100% offline platform designed to orchestrate complex campus recruitment seasons. It operates directly on institutional laptops or local servers without requiring an internet connection, cloud subscriptions, or Docker.

---

## 1. Quick Launch & Single-Port LAN Deployment

1. **Launch the Engine**:
   - Double-click `start.bat` (Windows) or execute `./start.sh` (Linux/macOS) in the root directory.
   - Alternatively, execute:
     ```bash
     python scripts/lan_launcher.py
     ```
2. **Access the Application**:
   - **Local Officer Console**: `http://localhost:8000`
   - **Candidate & Recruiter LAN Access**: The launcher automatically prints your active local IP (e.g. `http://192.168.1.45:8000`). Distribute this URL to students across the college Wi-Fi.
3. **Default Credentials**:
   - **Placement Officer**: Username: `officer` | Password: `officer123`
   - **Placement Coordinator**: Username: `coordinator` | Password: `coord123`
   - **Sample Student**: Roll No: `PIPE_001` | OTP: `123456`

---

## 2. Ingesting Candidate Rosters (CSV / XLSX)

1. Open the **Students & Importer** tab (`/students`).
2. Drag and drop your college master spreadsheet (`.xlsx` or `.csv`).
3. **Automatic Column Matching**: The engine auto-detects common header variants (`Roll Number`, `RegNo`, `CGPA`, `10th %`, `Backlogs`). Manually map any unmatched columns.
4. **Dry-Run Audit**: Click **Audit & Preview**. The engine checks:
   - Scale conversions (4.0 to 10.0 CGPA).
   - Branch aliases (e.g., "CompSci" -> "Computer Science and Engineering").
   - Invalid dates and formatting issues.
5. Review the row-level audit table. If satisfactory, click **Commit Ingestion** to save records.

---

## 3. Extracting Drive Requirements from Circulars

1. Open the **Extract Drive** tab (`/create_drive`).
2. Provide the announcement document:
   - Paste raw email text directly, OR
   - Upload a PDF circular (digital text and tables are automatically parsed), OR
   - Upload a Word bulletin (`.docx`).
3. Click **Extract Requirements**.
4. **Side-by-Side Verification**:
   - Left side shows the raw document with highlighted source sentences.
   - Right side displays parsed fields (CGPA cut-off, branch list, backlog policy, package/CTC, interview rounds).
   - Confidence badges indicate extraction certainty. Confirm any low-confidence fields and click **Create Drive & Ruleset**.

---

## 4. Configuring Rules & Policy Toggles

1. **Rule Editor (`/rule_editor`)**:
   - Visual forms allow adjusting cut-offs, branch aliases, maximum allowed backlogs, and gap-year ceilings without code.
   - Live candidate counter shows the number of eligible candidates updating in real time.
2. **Offer Policy Settings (`/policies`)**:
   - Select an institutional policy model (Strict One-Offer, Progressive 1.5x Multiplier, or Tiered Quota).
   - Configure institutional interpretation toggles:
     - *Is Dream threshold inclusive?* (e.g. is 10.0 LPA exactly treated as Dream?).
     - *Do off-campus offers count against quota?*
     - *Mandatory cooling window duration (days).*

---

## 5. Running Batch Eligibility & Audit Verification

1. Open the **Eligibility Runs** tab (`/eligibility`).
2. Select the recruitment drive and click **Run Batch Eligibility**.
3. The engine evaluates all candidates in milliseconds:
   - Categorizes students into **Eligible**, **Ineligible**, and **Policy Blocked**.
   - Generates single-line plain-English explanations for candidates.
   - Calculates a cryptographic SHA-256 snapshot hash ensuring audit reproducibility.
4. Export the resulting shortlist or proceed directly to scheduling.

---

## 6. Generating Clash-Free Schedules (OR-Tools CP-SAT)

1. Open the **Schedule Grid** tab (`/schedule`).
2. Select participating drives, available rooms (auditoriums, labs, interview cabins), and date windows.
3. Click **Generate Clash-Free Schedule**.
4. The CP-SAT solver computes an optimal timetable in seconds:
   - **Zero Room Overlaps**: No two companies book the same hall simultaneously.
   - **Zero Panel Clashes**: Interviewers are assigned non-overlapping student slots.
   - **Zero Candidate Clashes**: Students appearing for multiple drives are guaranteed collision-free slots with walking buffers between campus blocks.
5. The UI renders an interactive **Rooms $\times$ Time** grid. Drag and drop slots if manual adjustments are needed; the engine instantly flags any new clashes.

---

## 7. What-If Simulation & Publish Workflow

1. Open the **What-If & Publish** tab (`/what_if`).
2. Before publishing changes, simulate prospective adjustments:
   - E.g., lowering CGPA cut-off from 7.0 to 6.5, adding an interview panel, or marking a room unavailable.
3. The engine computes an instant **Impact Report**:
   - Generates a data-driven headline: *"Lowering cut-off adds 38 students; 6 clash with Northwind test."*
   - Previews schedule movements required to restore zero-clash integrity.
4. Click **Publish Official Schedule** to lock in an immutable version snapshot.
5. In case of unexpected changes, click **Rollback to Previous Version** for instant state recovery.

---

## 8. Result Entry & Automated Enforcement ChangeSets

1. Open the **Result Entry** tab (`/results`).
2. Enter company hiring outcomes (offers accepted, rejected, or revoked).
3. The engine computes a live **Enforcement ChangeSet**:
   - Identifies students who now exceed offer quotas.
   - Automatically cancels downstream test/interview reservations for blocked students.
   - Frees up interview slots for waiting-list candidates.

---

## 9. Resolving Candidate Disputes

1. Open the **Dispute Explainer** tab (`/dispute`).
2. When a student questions why a peer was permitted to interview while they were blocked:
   - Select the recruitment drive.
   - Select Candidate A (allowed) and Candidate B (blocked).
3. The engine generates an objective side-by-side justification citing the exact rule AST nodes and policy clauses, completely eliminating subjective allegations.

---

## 10. Data Protection, Encrypted Backups & Institutional Wipe

1. **Air-Gap Verification**:
   - Visit the **Offline Audit** tab (`/offline_audit`) to verify that 0 external network requests are being made.
2. **Encrypted Backups**:
   - Export an AES-256 encrypted database backup via the CLI:
     ```bash
     python scripts/backup_restore.py backup --passphrase "InstitutionalSecretKey"
     ```
3. **Restore Database**:
   - Restore state on a clean machine:
     ```bash
     python scripts/backup_restore.py restore my_backup.enc --passphrase "InstitutionalSecretKey"
     ```
4. **Institutional Wipe**:
   - At the conclusion of the academic year, wipe all student records and credentials by issuing the cryptographic wipe confirmation: `"CONFIRM_INSTITUTIONAL_WIPE"`.

	# Institutional Placement Engine: Placement Officer & Coordinator Guide (v1.0.0)

	## Welcome to the Campus Placement Engine

	The Institutional Placement Engine is a purpose-built, 100% offline platform designed to orchestrate complex campus recruitment seasons. It operates directly on institutional laptops or local servers without requiring an internet connection, cloud subscriptions, or Docker.

	---

	## 1. Quick Launch & Single-Port LAN Deployment

	1. Launch the Engine:
	- Double-click `start.bat` (Windows) or execute `./start.sh` (Linux/macOS) in the root directory.
	- Alternatively, execute:
	```bash
	python scripts/lan_launcher.py
	```
	2. Access the Application:
	- Local Officer Console: `http://localhost:8000`
	- Candidate & Recruiter LAN Access: The launcher automatically prints your active local IP (e.g. `http://192.168.1.45:8000`). Distribute this URL to students across the college Wi-Fi.
	3. Default Credentials:
	- Placement Officer: Username: `officer` \| Password: `officer123`
	- Placement Coordinator: Username: `coordinator` \| Password: `coord123`
	- Sample Student: Roll No: `PIPE_001` \| OTP: `123456`

	---

	## 2. Ingesting Candidate Rosters (CSV / XLSX)

	1. Open the Students & Importer tab (`/students`).
	2. Drag and drop your college master spreadsheet (`.xlsx` or `.csv`).
	3. Automatic Column Matching: The engine auto-detects common header variants (`Roll Number`, `RegNo`, `CGPA`, `10th %`, `Backlogs`). Manually map any unmatched columns.
	4. Dry-Run Audit: Click Audit & Preview. The engine checks:
	- Scale conversions (4.0 to 10.0 CGPA).
	- Branch aliases (e.g., "CompSci" -> "Computer Science and Engineering").
	- Invalid dates and formatting issues.
	5. Review the row-level audit table. If satisfactory, click Commit Ingestion to save records.

	---

	## 3. Extracting Drive Requirements from Circulars

	1. Open the Extract Drive tab (`/create_drive`).
	2. Provide the announcement document:
	- Paste raw email text directly, OR
	- Upload a PDF circular (digital text and tables are automatically parsed), OR
	- Upload a Word bulletin (`.docx`).
	3. Click Extract Requirements.
	4. Side-by-Side Verification:
	- Left side shows the raw document with highlighted source sentences.
	- Right side displays parsed fields (CGPA cut-off, branch list, backlog policy, package/CTC, interview rounds).
	- Confidence badges indicate extraction certainty. Confirm any low-confidence fields and click Create Drive & Ruleset.

	---

	## 4. Configuring Rules & Policy Toggles

	1. Rule Editor (`/rule_editor`):
	- Visual forms allow adjusting cut-offs, branch aliases, maximum allowed backlogs, and gap-year ceilings without code.
	- Live candidate counter shows the number of eligible candidates updating in real time.
	2. Offer Policy Settings (`/policies`):
	- Select an institutional policy model (Strict One-Offer, Progressive 1.5x Multiplier, or Tiered Quota).
	- Configure institutional interpretation toggles:
	- Is Dream threshold inclusive? (e.g. is 10.0 LPA exactly treated as Dream?).
	- Do off-campus offers count against quota?
	- Mandatory cooling window duration (days).

	---

	## 5. Running Batch Eligibility & Audit Verification

	1. Open the Eligibility Runs tab (`/eligibility`).
	2. Select the recruitment drive and click Run Batch Eligibility.
	3. The engine evaluates all candidates in milliseconds:
	- Categorizes students into Eligible, Ineligible, and Policy Blocked.
	- Generates single-line plain-English explanations for candidates.
	- Calculates a cryptographic SHA-256 snapshot hash ensuring audit reproducibility.
	4. Export the resulting shortlist or proceed directly to scheduling.

	---

	## 6. Generating Clash-Free Schedules (OR-Tools CP-SAT)

	1. Open the Schedule Grid tab (`/schedule`).
	2. Select participating drives, available rooms (auditoriums, labs, interview cabins), and date windows.
	3. Click Generate Clash-Free Schedule.
	4. The CP-SAT solver computes an optimal timetable in seconds:
	- Zero Room Overlaps: No two companies book the same hall simultaneously.
	- Zero Panel Clashes: Interviewers are assigned non-overlapping student slots.
	- Zero Candidate Clashes: Students appearing for multiple drives are guaranteed collision-free slots with walking buffers between campus blocks.
	5. The UI renders an interactive Rooms $\times$ Time grid. Drag and drop slots if manual adjustments are needed; the engine instantly flags any new clashes.

	---

	## 7. What-If Simulation & Publish Workflow

	1. Open the What-If & Publish tab (`/what_if`).
	2. Before publishing changes, simulate prospective adjustments:
	- E.g., lowering CGPA cut-off from 7.0 to 6.5, adding an interview panel, or marking a room unavailable.
	3. The engine computes an instant Impact Report:
	- Generates a data-driven headline: "Lowering cut-off adds 38 students; 6 clash with Northwind test."
	- Previews schedule movements required to restore zero-clash integrity.
	4. Click Publish Official Schedule to lock in an immutable version snapshot.
	5. In case of unexpected changes, click Rollback to Previous Version for instant state recovery.

	---

	## 8. Result Entry & Automated Enforcement ChangeSets

	1. Open the Result Entry tab (`/results`).
	2. Enter company hiring outcomes (offers accepted, rejected, or revoked).
	3. The engine computes a live Enforcement ChangeSet:
	- Identifies students who now exceed offer quotas.
	- Automatically cancels downstream test/interview reservations for blocked students.
	- Frees up interview slots for waiting-list candidates.

	---

	## 9. Resolving Candidate Disputes

	1. Open the Dispute Explainer tab (`/dispute`).
	2. When a student questions why a peer was permitted to interview while they were blocked:
	- Select the recruitment drive.
	- Select Candidate A (allowed) and Candidate B (blocked).
	3. The engine generates an objective side-by-side justification citing the exact rule AST nodes and policy clauses, completely eliminating subjective allegations.

	---

	## 10. Data Protection, Encrypted Backups & Institutional Wipe

	1. Air-Gap Verification:
	- Visit the Offline Audit tab (`/offline_audit`) to verify that 0 external network requests are being made.
	2. Encrypted Backups:
	- Export an AES-256 encrypted database backup via the CLI:
	```bash
	python scripts/backup_restore.py backup --passphrase "InstitutionalSecretKey"
	```
	3. Restore Database:
	- Restore state on a clean machine:
	```bash
	python scripts/backup_restore.py restore my_backup.enc --passphrase "InstitutionalSecretKey"
	```
	4. Institutional Wipe:
	- At the conclusion of the academic year, wipe all student records and credentials by issuing the cryptographic wipe confirmation: `"CONFIRM_INSTITUTIONAL_WIPE"`.