Psychological Tests — System Documentation¶
Module for recording and querying psychological tests administered to workers. Generation date: 2026-06-22
Overview¶
The psychological tests module allows professionals in the Psychologist group to record the results of psychological assessments for workers linked to the companies they have access to. Each record is available for consultation by other authorized health professionals.
Data Models¶
Teste_Psicologico (Psychological_Test)¶
Table: home_teste_psicologico
| Field | Type | Description |
|---|---|---|
id |
AutoField (PK) | Unique identifier |
titulo |
TextField | Test title ID (logical FK to Titulo_Teste_Psicologico) |
empresa |
TextField | Worker's company ID |
paciente |
TextField | CPF (Brazilian taxpayer ID) of the assessed worker |
nome_paciente |
TextField | Worker's name |
score |
TextField | Test result/classification |
observacao |
TextField | Free-text notes from the psychologist (max. 10,000 characters) |
encaminhamento |
TextField | List of suggested referrals (serialized) |
data_teste |
TextField | Date the test was administered |
psicologo_responsavel |
TextField | Name of the responsible psychologist |
Titulo_Teste_Psicologico (Psychological_Test_Title)¶
Table: home_titulo_teste_psicologico
| Field | Type | Description |
|---|---|---|
id |
AutoField (PK) | Unique identifier |
titulo |
TextField | Name of the psychological test |
Registered Test Titles¶
Titles are created dynamically by the system and can be added by the psychologist at registration time.
| Title | Note |
|---|---|
| TRI | Reasoning Test (Teste de Raciocínio) |
| Palográfico | Graphomotor test — uses the "Descriptive" score |
New titles can be added directly on the test registration screen via a modal.
Classification Fields¶
Score (Test Result)¶
| Value | When to use |
|---|---|
| Below Average (Inferior) | All tests except Palográfico |
| Below-Average to Average (Médio-inferior) | All tests except Palográfico |
| Average (Médio) | All tests except Palográfico |
| Average to Above-Average (Médio-superior) | All tests except Palográfico |
| Above Average (Superior) | All tests except Palográfico |
| Well Above Average (Muito Superior) | All tests except Palográfico |
| Descriptive (Descritivo) | Exclusive to the Palográfico test |
The system automatically hides the "Descriptive" score for tests other than Palográfico, and hides the other scores when Palográfico is selected.
Possible Referrals¶
Multiple-selection field — the psychologist can select one or more referrals:
| Referral |
|---|
| Psychologist |
| Neuropsychologist |
| Nutritionist |
| General Practitioner |
| Cardiologist |
| Endocrinologist |
| Gastroenterologist |
| Gynecologist |
| Occupational Physician |
| Ophthalmologist |
| Orthopedist |
| Urologist |
| Psychiatrist |
Routes (URLs)¶
| Method | URL | Name | Description |
|---|---|---|---|
| GET / POST | /psicologico |
psicologico |
Form for registering a new test |
| POST | /psicologico/register_titulo |
register_titulo |
Registration of a new test title (via modal) |
| GET | /psicologico_view/<id> |
psicologico_view |
View a specific test |
| POST | /delete_psicologico/<id> |
delete_psicologico |
Delete a test |
| GET / POST | /lista-trabalhadores-psicologico/ |
lista-trabalhadores-psicologico |
Paginated listing of tests with search by CPF |
Registration Flow¶
1. Psychologist selects the test title
└─ If the title does not exist → opens modal → creates new title
2. Selects the company
3. Selects the worker
└─ The worker list is dynamically filtered by company
└─ Search by name or CPF
4. Enters the score
└─ Options automatically filtered by the selected title
└─ Palográfico → only "Descriptive"
└─ Others → quantitative scales
5. Fills in notes (free text field, up to 10,000 characters)
6. Selects suggested referral(s) (multiple choice)
7. Enters the date the test was administered
8. Saves → record created and shown in the listing
Data Scope¶
The system applies access filtering by Organizational Unit: each user sees only tests for workers linked to companies within their unit. This is implemented via get_empresas_ids_unidade_usuario() in the controller.
Templates¶
| File | Route | Description |
|---|---|---|
apps/templates/home/psicologico.html |
/psicologico |
Registration form |
apps/templates/home/psicologico_view.html |
/psicologico_view/<id> |
View a record |
apps/templates/home/lista-trabalhadores-psicologico.html |
/lista-trabalhadores-psicologico/ |
Listing with search and pagination |
Controller¶
File: apps/home/controller/controller_psicologico.py
| Function | Description |
|---|---|
register_psicologico(request) |
GET: renders the form; POST: validates and saves the test |
register_titulo(request) |
POST: creates a new test title |
psicologico_view(request, trabalhador_id) |
Shows the details of a test by ID |
lista_trabalhadores_psicologico(request) |
Lists tests with scope filtering and search by CPF, 10 per page pagination |
delete_psicologico(request, psicologico_id) |
Deletes a record and redirects to the listing |
Form (Teste_PsicologicoForm)¶
Defined in apps/home/forms.py — fields shown on registration:
| Field in Form | Field in Model | Widget Type |
|---|---|---|
titulo |
titulo |
Hidden input (filled via custom select) |
empresa |
empresa |
Hidden input (filled via custom select) |
paciente |
paciente |
Hidden input (filled via datalist with CPF) |
nome_paciente |
nome_paciente |
Hidden input (filled via JS) |
psicologo_responsavel |
psicologo_responsavel |
Hidden input (name of the logged-in user) |
score |
score |
Select with options filtered by title |
observacao |
observacao |
Textarea (max. 10,000 characters) |
encaminhamento |
encaminhamento |
CheckboxSelectMultiple |
data_teste |
data_teste |
Date input |
Special Frontend Behavior¶
- Company selected first: the worker field is only enabled after a company is selected, and workers are filtered via JS on the frontend (without a new request to the server).
- Dynamic score: when the title changes, JS filters the score options, showing only "Descriptive" for Palográfico or only the quantitative scales for the others.
- Character counter: the notes field shows in real time how many characters remain up to the 10,000 limit.
- New title modal: the
+button next to the title select opens a modal to register a new test type without leaving the page.
SQL — Initial Titles¶
-- Initial insertion of the default titles (run on a new installation)
INSERT INTO home_titulo_teste_psicologico (titulo) VALUES ('TRI');
INSERT INTO home_titulo_teste_psicologico (titulo) VALUES ('Palográfico');
File: scripts/teste_psiciologico/novos_teste.sql