Schemas Zod

O pacote @neemias/schemas contém todos os schemas Zod compartilhados entre frontend e backend. Estes schemas são a fonte única da verdade para validação de dados, tipos TypeScript e geração da especificação OpenAPI.

Primitivas

PhoneEntry

Entrada de telefone com número e qualificador (ex.: "Celular", "WhatsApp").

Campo	Tipo	Restrições
number	string	min 1, max 20
qualifier	string	min 1, max 50

Address

Endereço residencial do aluno (dado LGPD — PII).

Campo	Tipo	Restrições
street	string	max 255, default ""
number	string	max 20, default ""
complement	string	max 255, default ""
neighborhood	string	max 255, default ""
city	string	max 255, default ""
state	string	max 2, default ""
zip	string	max 10, default ""

Constante auxiliar: EMPTY_ADDRESS — objeto Address com todos os campos vazios.

EncryptedPayload

Payload criptografado com AES-GCM para dados sensíveis em repouso.

Campo	Tipo
ciphertext	string
iv	string
keyVersion	number (inteiro)

Entidades principais

Student

Aluno — entidade central do sistema. Contém campos PII (LGPD) e não-PII.

Campos PII (LGPD): displayName, photoRef, guardianName, guardianNameAlt, birthDate, phones, address, allergies, specialNeeds

Campo	Tipo	Restrições
studentId	string	UUID
displayName	string	min 1, max 140 — PII
photoRef	string	default "" — PII (dado biométrico)
status	StudentStatus	enum
guardianName	string	min 1, max 200 — PII
guardianNameAlt	string (opcional)	max 200 — PII
birthDate	string (opcional)	— PII
phones	PhoneEntry[]	default [] — PII
address	Address	default EMPTY_ADDRESS — PII
classId	string (opcional)	UUID
nucleusParticipates	boolean	default false
nucleusRegion	NucleusRegion (opcional)	enum
nucleusName	string (opcional)	max 200
allergies	string (opcional)	max 1000 — PII
specialNeeds	string (opcional)	max 1000 — PII
familyMembershipStatus	FamilyMembershipStatus	default "DESCONHECIDO"
createdAt	string	ISO 8601 datetime
updatedAt	string	ISO 8601 datetime
createdBy	string	UUID
deletedAt	string (opcional)	—
deletedBy	string (opcional)	UUID

Class (Turma)

Campo	Tipo	Restrições
classId	string	UUID
name	string	min 1, max 100
ageMin	number (opcional)	inteiro, 0–99
ageMax	number (opcional)	inteiro, 0–99
status	enum	"ACTIVE" | "DELETED"
createdAt	string	ISO 8601 datetime
updatedAt	string	ISO 8601 datetime

Nucleus (Núcleo)

Campo	Tipo	Restrições
nucleusId	string	UUID
region	NucleusRegion	enum
name	string	min 1, max 200
status	enum	"ACTIVE" | "DELETED"
createdAt	string	ISO 8601 datetime
updatedAt	string	ISO 8601 datetime

ClassSlot

Campo	Tipo	Restrições
slotId	string	UUID
dayOfWeek	number	inteiro, 0–6
startTime	string	regex HH:MM
label	string	min 1, max 100
sessionDate	string (opcional)	—
status	SlotStatus	enum
createdAt	string	ISO 8601 datetime
updatedAt	string	ISO 8601 datetime

ClassSession

Campo	Tipo	Restrições
sessionId	string	UUID
slotId	string	UUID
sessionDate	string	regex YYYY-MM-DD
createdAt	string	ISO 8601 datetime

SessionOption (auxiliar de exibição)

Campo	Tipo
sessionId	string (UUID)
slotId	string (UUID)
label	string
sessionDate	string
dayOfWeek	number (0–6)
startTime	string

Eventos e auditoria

AttendanceEvent

Registro de chamada (presença/falta).

Campo	Tipo	Restrições
eventId	string	UUID
studentId	string	UUID
classSessionId	string	UUID
actionType	AttendanceActionType	enum
actorId	string	UUID
actorRole	string	—
timestamp	string	ISO 8601 datetime
syncState	SyncState	default "SYNCED"
isConflictLoser	boolean	default false
conflictSupersededBy	string (opcional)	UUID

StudentEvent

Evento de auditoria de alterações em alunos. Inclui criptografia opcional para dados sensíveis.

Campo	Tipo	Restrições
eventId	string	UUID
studentId	string	UUID
eventType	StudentEventType	enum
actorId	string	UUID
actorRole	string	—
timestamp	string	ISO 8601 datetime
changePayload	Record<string, unknown>	default {}
justification	string (opcional)	max 500
encryptedChangePayload	EncryptedPayload (opcional)	—
encryptedJustification	EncryptedPayload (opcional)	—
syncState	SyncState	default "SYNCED"
isConflictLoser	boolean	default false

UserEvent

Evento de auditoria de alterações em usuários.

Campo	Tipo	Restrições
eventId	string	UUID
userId	string	UUID
eventType	UserEventType	enum
actorId	string	UUID
actorRole	string	—
timestamp	string	ISO 8601 datetime
changePayload	Record<string, unknown>	default {}
encryptedChangePayload	EncryptedPayload (opcional)	—
syncState	SyncState	default "SYNCED"
isConflictLoser	boolean	default false

Sincronização offline

SyncQueueEntry

Entrada na fila de sincronização offline → online.

Campo	Tipo	Restrições
queueId	string	UUID
eventId	string	UUID
entityType	enum	"ATTENDANCE_EVENT" | "STUDENT_EVENT" | "USER_EVENT"
actionType	string	min 1
actorId	string	UUID
actorRole	string	—
enqueuedAt	string	ISO 8601 datetime
syncState	SyncState	default "PENDING"
retryCount	number	inteiro ≥ 0, default 0
failureCode	string (opcional)	—
failureReason	string (opcional)	—
lastAttemptAt	string (opcional)	ISO 8601 datetime

Autenticação e sessão

Session

Sessão autenticada do usuário.

Campo	Tipo	Restrições
sessionId	string	UUID
userId	string	UUID
role	string	—
issuedAt	string	ISO 8601 datetime
expiresAt	string	ISO 8601 datetime
state	enum	"ACTIVE" | "EXPIRED" | "REVOKED"
lastValidatedAt	string (opcional)	ISO 8601 datetime
backendRefreshToken	string (opcional)	—
csrfToken	string (opcional)	—
encryptedSessionSecrets	EncryptedPayload (opcional)	—
backendAuthMode	enum (opcional)	"bearer" | "cookie"

LocalUser

Usuário armazenado localmente (IndexedDB) para operação offline.

Campo	Tipo	Restrições
userId	string	UUID
username	string	min 1, max 100
email	string (opcional)	email
displayName	string	min 1, max 140
passwordHash	string (opcional)	—
encryptedCredentials	EncryptedPayload (opcional)	—
cryptoKeyVersion	number (opcional)	inteiro
keyRotatedAt	string (opcional)	ISO 8601 datetime
role	string	—
status	UserStatus	enum
createdAt	string	ISO 8601 datetime
createdBy	string | null	UUID ou null
updatedAt	string	ISO 8601 datetime
deactivatedAt	string (opcional)	ISO 8601 datetime
deactivatedBy	string (opcional)	UUID

Outros schemas

Role (papel dinâmico — v0.26.0+)

Campo	Tipo	Restrições
name	string	min 1, max 50
displayName	string	min 1, max 100
permissions	string[]	—
isSystem	boolean	default false
createdAt	string	ISO 8601 datetime
updatedAt	string	ISO 8601 datetime

LocaleResource

Recurso de internacionalização (i18n).

Campo	Tipo	Restrições
localeCode	string	min 2, max 10
key	string	min 1
translatedText	string	—

---

Fonte: packages/schemas/src/entities.ts