97 lines
4.7 KiB
Markdown
97 lines
4.7 KiB
Markdown
# Staff Backend
|
|
|
|
## Purpose
|
|
|
|
`staff` is the per-organization employee profile roster, linking an optional `user` account and
|
|
`campus` to each staff member. It is a generic-CRUD slice assembled from the shared factories;
|
|
the backend is the source of truth for staff records.
|
|
|
|
## Slice Files (by layer)
|
|
|
|
- Route: `src/routes/staff.ts` — `createCrudRouter(controller, { permission: 'staff' })`.
|
|
- Controller: `src/api/controllers/staff.controller.ts` — `createCrudController(service, { csvFields })`.
|
|
- Service (BLL): `src/services/staff.ts` — `createCrudService(DbApi, { notFoundCode: 'staffNotFound' })`.
|
|
- Repository (DAL): `src/db/api/staff.ts` (`StaffDBApi`) — entity-specific
|
|
`create`/`bulkImport`/`update`/`findBy`/`findAll`; `remove`/`deleteByIds`/`findAllAutocomplete`
|
|
delegate to `db/api/shared/repository.ts`.
|
|
- Model: `src/db/models/staff.ts`.
|
|
- Shared used: CRUD factories (`services/shared/crud-service.ts`,
|
|
`api/controllers/shared/crud-controller.ts`, `api/http/crud-router.ts`), repository helpers
|
|
(`db/api/shared/repository.ts`), `shared/constants/pagination.ts` (`resolvePagination`),
|
|
`shared/constants/database.ts` (`BULK_IMPORT_TIMESTAMP_STEP_MS`), `db/utils.ts` (`Utils`),
|
|
`db/api/file.ts` (`FileDBApi.replaceRelationFiles` for the `photo` relation).
|
|
|
|
## API
|
|
|
|
The standard generic-CRUD surface (all under `/api/staff`, JWT + `${METHOD}_STAFF` permission,
|
|
all `200`) — see `backend-architecture.md` for the shared contract:
|
|
|
|
- `POST /` — body `{ data }`, returns `true`.
|
|
- `POST /bulk-import` — multipart CSV file, returns `true`.
|
|
- `PUT /:id` — body `{ data, id }` (the service reads the id from the **body**, not the path
|
|
param), returns `true`.
|
|
- `DELETE /:id` — returns `true`.
|
|
- `POST /deleteByIds` — body `{ data: string[] }`, returns `true`.
|
|
- `GET /` — query filters, returns `{ rows, count }`; `?filetype=csv` streams a CSV of `csvFields`.
|
|
- `GET /count` — returns `{ rows: [], count }`.
|
|
- `GET /autocomplete` — `?query&limit&offset`, returns `[{ id, label }]` where `label` is
|
|
`employee_number`.
|
|
- `GET /:id` — returns the record with eager associations (see Data Contract).
|
|
|
|
`csvFields`: `id`, `employee_number`, `job_title`, `hire_date`.
|
|
|
|
## Access Rules
|
|
|
|
- JWT required; the whole router is guarded by `checkCrudPermissions('staff')`, deriving
|
|
`READ_STAFF` / `CREATE_STAFF` / `UPDATE_STAFF` / `DELETE_STAFF` per HTTP method.
|
|
- Access is granted by role permission or per-user `custom_permissions` (see `permissions.md`).
|
|
|
|
## Tenant Scope
|
|
|
|
- `findAll` scopes `where.organizationId` to `currentUser.organizationId`; a `globalAccess`
|
|
role clears the org filter (sees all tenants).
|
|
- `create` assigns the organization from `currentUser.organizationId`; `update` only reassigns
|
|
organization for `globalAccess` users (otherwise it stays the caller's org), and only when
|
|
`data.organization` is provided.
|
|
|
|
## Data Contract
|
|
|
|
Model columns (`paranoid`, soft-delete via `deletedAt`):
|
|
|
|
- `id` (UUID PK), `employee_number`, `job_title` (TEXT, nullable).
|
|
- `staff_type` — ENUM `teacher` | `admin` | `support`.
|
|
- `status` — ENUM `active` | `on_leave` | `inactive`.
|
|
- `hire_date` — DATE.
|
|
- `importHash` (unique), `campusId`, `organizationId`, `userId`, `createdById`, `updatedById`,
|
|
timestamps.
|
|
|
|
Associations: `belongsTo` organization, campus, user (a `users` record), createdBy/updatedBy
|
|
(users); `hasMany` `classes_homeroom_teacher` (classes via `homeroom_teacherId`),
|
|
`class_subjects_teacher` (class_subjects via `teacherId`), `attendance_sessions_taken_by`
|
|
(attendance_sessions via `taken_byId`), `payments_received_by` (payments via `received_byId`);
|
|
`hasMany` file as `photo` (scoped relation). `findBy`/`GET /:id` eager-load all of these in a
|
|
single `Promise.all`.
|
|
|
|
List filters (`StaffFilter`): `id`, `employee_number`, `job_title`, `hire_dateRange`,
|
|
`staff_type`, `status`, `campus` (id or name, `|`-separated), `user` (id or `firstName`,
|
|
`|`-separated), `organization` (id list, `|`-separated), `createdAtRange`, plus `field`/`sort`
|
|
ordering and `limit`/`page` pagination.
|
|
|
|
## Behavior / Notes
|
|
|
|
- `create`/`bulkImport`/`update` manage the `photo` file relation via
|
|
`FileDBApi.replaceRelationFiles`.
|
|
- `bulkImport` offsets `createdAt` per row by `BULK_IMPORT_TIMESTAMP_STEP_MS` to preserve order.
|
|
- List pagination uses the shared `resolvePagination` defaults (page size 10, capped at 100).
|
|
- Note: `StaffFilter` accepts an `active` flag and `findAll` filters on an `active` column, but
|
|
the model has no `active` column; this filter is currently inert (kept for source accuracy).
|
|
|
|
## Tests
|
|
|
|
None yet.
|
|
|
|
## Related
|
|
|
|
- Generic-CRUD contract: `backend-architecture.md`; related slices: `organizations`, `campuses`,
|
|
`classes`, `class_subjects`, `attendance_sessions`, `payments`, `file.md`, `permissions.md`.
|