Ir para o conteúdo

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