feat: import leftover student fields into notes and show them on the roster

Store leftover CSV columns on hidden student notes, move catalog import to /events/import, and persist Students index columns from Chapter Settings. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-29 23:55:03 -04:00
parent 4c91db37c2
commit 4cfd85b902
39 changed files with 2437 additions and 166 deletions
@@ -0,0 +1,50 @@
+# Import Students and Note Fields
+
+**Created:** 2026-08-29  
+**Last updated:** 2026-08-29  
+
+**Description:** How `/students/import` creates students and merges leftover CSV columns into each student's markdown notes.
+
+## Where notes live
+
+Each student has a system note titled `#Student:{id}`. It is edited on the student edit page and shown on student details. Those notes are hidden from the main Notes list.
+
+Imported leftover values go in a table under `## Imported fields`. Other markdown above or below that heading is left alone.
+
+## CSV format
+
+```
+Student Name,Grade,TSA year,State ID,Regional ID,National ID,Interview Time,Application,Club Permission Slip,Teacher Rec 1,Teacher Rec 2,Teacher Rec 3
+"Last, First",6,1st,,,,3:20-3:35,x,x,Fuqua,Young,
+```
+
+- Roster (required): `Student Name` (`Last, First` or `First Last`), `Grade`, `TSA year`.
+- Roster (optional): `State ID`, `Regional ID`, `National ID`.
+- Every other column becomes a Field/Value row. Later files can add columns without a code change.
+- A cell that is only `x` / `X` is stored as `Yes`. Blank stays blank.
+- Rank columns `1`–`10`, `Officer`, and `TOTAL # OF EVENTS` are ignored (use `/students/event-ranking/import` for rankings).
+
+A notes-only file without `Grade` will not import. Put roster and leftover columns in the same CSV.
+
+## Merge rules
+
+- New students are inserted. Existing first+last name matches are skipped for the roster (add-only).
+- After students are saved, leftover columns are fuzzy-matched by name and merged into notes. Existing students still receive note updates.
+- Incoming values win when a field already exists, including a blank cell that clears a previous value.
+- New fields are appended. Fields not in this CSV stay. Blank cells are stored and re-imported as a no-op.
+- Duplicate rows for the same student collapse into one note match; the last row wins for overlapping field names.
+- Importing the same file twice adds no students and writes no note history.
+
+## Steps
+
+1. Sign in as an Administrator.
+2. Open **Students** and click **Import**, or go to `/students/import`.
+   The arrow next to **Import** downloads a CSV template (roster columns, Students index columns, and any other imported fields already in notes).
+   `/import` still opens this same student page.
+3. Upload the student CSV.
+4. Review new vs existing counts and leftover field names.
+5. **Save to Database**.
+
+## Index columns
+
+Chapter Settings → **Student Index Columns** lists which imported field names appear as extra columns on the Students index. The page also shows field names already present in student notes; click a chip to add or remove it from the list. Open Students again after saving; a restart is not required.