Backend: Editing existing assessment

GitHub Issue: #218

Backend task for editing an assessment (POST /assessments/{assessmentId}) – check the API spec and DB structure, the candidate, board member and argumentacija rules, implement, and verify against the spec.

Docs: Editing existing assessment Spec: POST /assessments/{assessmentId} (updateAssessment), AssessmentNewRequest, AssessmentConflict in api-docs/openapi.yaml DB: Assessments, AssessmentCandidates, AssessmentWrittenTestGrades, AssessmentBoardMembers, AssessmentGrades, AssessmentNotes in api/database/create_schema.sql

1. Double check API spec and DB structure

• Same fields and validation as create. Candidates have an optional id in the request for matching.
• Past assessment → 409 assessment_past. Check the docs (edit only for active/upcoming).
• Blocking candidate removal: the spec blocks it when the candidate has grades, notes or a written test grade (candidate_has_grades). The docs only mention grades and leave notes as an open question. Confirm. The FKs block on all three; if notes shouldn’t block, the edit deletes the removed candidates’ notes before deleting the candidates.
• Turning off argumentation deletes its grades. The docs recommend a confirmation in the frontend. Does the frontend need to be told whether argumentation grades exist?
• After saving, the frontend goes to the detail page. Is 200 + Assessment enough?
• Roles and permissions: Trainer only (assessments.edit), as in the docs permission table.
• DB: removed board members are soft-deleted (DeletedAt, Slot NULL) and their grades stay. Re-adding a member restores the same row. UQ_AssessmentBoardMembers_User (not filtered) keeps it to one row per user per assessment, so a re-added member can’t be inserted twice.
• DB: “candidate has data” is enforced by the FKs from AssessmentGrades, AssessmentNotes and AssessmentWrittenTestGrades: deleting such a candidate fails with 547. The maximums are capped by Slot (see create).
• DB: FK_AssessmentGrades_Argumentation makes HasArgumentation = 0 fail while argumentation rows exist (see Backend: Form – Igranje uloga – argumentacija).
• Komisija lookup: same source as create, for the dropdown and for FullName of newly added members.

2. Implementation

• Roles and permissions: require assessments.edit → 403.
• Lookups: new board members get FullName from the users source; every member must have the Trainer or Assessment evaluator role.

All in one transaction (several writes), in this order, committed only when every statement succeeds. Don’t check for data before deleting: run the write and map the error, so a grade saved at the same moment can’t slip through.

• Status check → 409 assessment_past.
• Candidates left out: one DELETE … WHERE AssessmentId = @id AND Id NOT IN (…). FK error 547 → roll back, 409 candidate_has_grades (nothing deleted).
• Candidates: no id → insert with the lowest free Slot; id that isn’t a candidate of this assessment → 404; others → update name and e-mail.
• Board members: those left out → set DeletedAt, Slot NULL (first, so their slots are free); re-added → clear DeletedAt, take the lowest free Slot; new → insert with the lowest free Slot.
• hasArgumentation true → false: delete all argumentation rows in AssessmentGrades for this assessment, then update HasArgumentation. If the update fails with 547, a board member saved argumentation between the two statements: roll back (nothing is saved, the deleted rows come back) and run the whole edit again, as below.
• Set UpdatedAt. Same validation as create.
• Concurrent changes: a unique violation (2601 / 2627) on a Slot or UserId (another edit ran at the same time) or the 547 above → roll back and run the whole edit again once, in a new transaction. If it fails the same way again → 500.

3. Verify implementation against spec

• Status codes and error values match updateAssessment.
• Scenarios: remove a candidate who has no data (ok), remove one who has grades (409), remove one who has only notes (as decided); remove a board member and re-add them (their grades come back); turn argumentation off and on again (old grades are gone); remove a candidate who only has a written test grade (409); swap a board member for a new one while the komisija is full (10 members).

Done when

All the edit rules in the docs are enforced by the API.