Backend: Adding new BTC certificiranje

Backend task for creating a BTC certificiranje (POST /btc-certifications) – check the API spec and DB structure, set up the BTC evaluator role, btc-certifications permissions, tables and the Komisija / Partner lookups, implement, and verify against the spec.

Docs: Adding new BTC certificiranje Spec: POST /btc-certifications (createBtcCertification), BtcCertificationNewRequest, BtcCertification, BtcStatus in api-docs/openapi.yaml DB: BtcCertifications, BtcCertificationCandidates, BtcCertificationBoardMembers in api/database/create_schema.sql

This is the first BTC certificiranje endpoint, so it also includes the shared setup for the certificiranje sub-area: the BTC evaluator role, permissions, tables, the status helper and the Komisija / Partner lookups.

1. Double check API spec and DB structure

• Every docs field is in BtcCertificationNewRequest, with the right required/optional setting: Marka (one brand → brandCode), Naziv certificiranja (name), Datum početka / završetka (startDate / endDate, both required), candidates (Ime i prezime required, E-mail optional, Partner required), Komisija (boardMemberUserIds).
• Limits: 1–20 candidates, 1–10 komisija members, no duplicate members. Check the docs and the spec (minItems / maxItems) agree.
• Dates: end ≥ start (docs recommendation) is in the spec and in CK_BtcCertifications_Dates. Confirm.
• Komisija lookup: each row is one user dropdown whose options show the user’s name and e-mail (there is no separate e-mail field). The docs recommend listing only Trainer and BTC evaluator users. The spec has no users endpoint and api/ has no users integration. Use the same source as Backend: Adding new assessment (it must return user id, full name, e-mail and role) and filter by role. The e-mail is only shown in the dropdown; it is not stored (only UserId and FullName).
• Partner lookup: Partner is a dropdown. Reuse the shared partner source.
• Default structure: Rezultati certificiranja and Modul 5 – Usmeni ispit per candidate are fixed in code. No rows are created besides the certificiranje, candidates and komisija.
• Each DB column has a request field or a value set by the server (CreatedBy, CreatedAt, member FullName).
• Is 201 + BtcCertification enough to return to the list with a toast?
• Roles and permissions (decided, see Roles): a BTC evaluator sees everything and can enter Pismeni ispit, but can’t create, edit or delete certificiranja. Mapping: Trainer → btc-certifications.access, btc-certifications.edit, btc-certifications.written-exam-edit; BTC evaluator → btc-certifications.access, btc-certifications.written-exam-edit. Admin → to confirm. This endpoint uses btc-certifications.edit.
• Brand restriction: decide whether limitedBrandCodes applies (the docs say Trainers and BTC evaluators see everything; recommended: no).
• DB: BrandCode CHAR(1) with the brand CHECK; PartnerId NVARCHAR(50) NOT NULL; UserId NVARCHAR(100). The maximums are capped by Slot: UQ_BtcCertificationCandidates_Slot (1–20) and UX_BtcCertificationBoardMembers_Slot (1–10, active members only); UQ_BtcCertificationBoardMembers_User keeps one row per user. The minimums are checked in code only. Slot is not the display order (that’s CreatedAt).

2. Implementation

• Roles and permissions: add BtcEvaluator to RoleCode (pick a single-letter code, add ToName and the GetRoles catalog). The Trainer role comes from the assessments task; add it here if it doesn’t exist yet. Add btc-certifications.access, btc-certifications.edit and btc-certifications.written-exam-edit to Permissions.cs and map them to roles as decided in step 1. Update docs/content/general/user-roles.md if the role list is maintained there.
• DB: apply the -- BTC CERTIFICIRANJE -- section of create_schema.sql (plus a migration script, if used). Add the status helper from BtcStatus: upcoming when StartDate > today, past when EndDate < today, otherwise active (today in Europe/Zagreb). Make it usable as a SQL expression for the list.
• Lookups: Komisija users (Trainer and BTC evaluator, with name and e-mail for the dropdown) and partners, from the shared sources. A service that resolves a user id to full name and role.
• Function + repository. Insert the certificiranje, candidates and komisija members in one transaction (several writes). Candidates get Slot 1…n and members 1…m, in request order.
• Validation → 400 (validation_error): required fields; brand code; end ≥ start; 1–20 candidates; 1–10 unique members; every member exists and has the Trainer or BTC evaluator role; lengths.
• Requires btc-certifications.edit → 403. Response 201 with BtcCertification (calculated status, candidatesCount).

3. Verify implementation against spec

• Route, method, request and response shapes match createBtcCertification.
• 400 / 401 / 403 / 500 cases can be produced; no undocumented status codes.
• BTC evaluator token → 403. End before start → 400. Duplicate member → 400. A user with the Assessment evaluator role as member → 400.
• GET /me/permissions returns the expected set for a Trainer and for a BTC evaluator. Permission names in Permissions.cs match the PermissionName enum.
• Any new lookup endpoints are in openapi.yaml.

Done when

A trainer can create a BTC certificiranje, which then shows on the list and on the detail page with its candidates and komisija.