tychat-contracts 1.0.95 → 1.0.97

package/dist/appointments/list-appointments-query.dto.d.ts

@@ -1,5 +1,10 @@
 import { AppointmentDto } from './appointment.dto';
 import { AppointmentStatusDto } from './appointment-status.dto';
+/** Campo principal de ordenação na listagem de agendamentos. */
+export declare const APPOINTMENT_LIST_SORT_BY: readonly ["date", "checkin_completed"];
+export type AppointmentListSortByDto = (typeof APPOINTMENT_LIST_SORT_BY)[number];
+export declare const APPOINTMENT_LIST_SORT_ORDER: readonly ["ASC", "DESC"];
+export type AppointmentListSortOrderDto = (typeof APPOINTMENT_LIST_SORT_ORDER)[number];
 export declare class ListAppointmentsQueryDto {
     page?: number;
     limit?: number;
@@ -9,6 +14,8 @@ export declare class ListAppointmentsQueryDto {
     checkinCompleted?: boolean;
     patientId?: string;
     status?: AppointmentStatusDto;
+    sortBy?: AppointmentListSortByDto;
+    sortOrder?: AppointmentListSortOrderDto;
 }
 export interface AppointmentListResult {
     items: AppointmentDto[];

package/dist/appointments/list-appointments-query.dto.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"list-appointments-query.dto.d.ts","sourceRoot":"","sources":["../../src/appointments/list-appointments-query.dto.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAwB,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAEtF,qBAAa,wBAAwB;IAUnC,IAAI,CAAC,EAAE,MAAM,CAAC;IAad,KAAK,CAAC,EAAE,MAAM,CAAC;IAQf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAQlB,MAAM,CAAC,EAAE,MAAM,CAAC;IAQhB,MAAM,CAAC,EAAE,MAAM,CAAC;IAQhB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAQ3B,SAAS,CAAC,EAAE,MAAM,CAAC;IAUnB,MAAM,CAAC,EAAE,oBAAoB,CAAC;CAC/B;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf"}
+{"version":3,"file":"list-appointments-query.dto.d.ts","sourceRoot":"","sources":["../../src/appointments/list-appointments-query.dto.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAwB,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAEtF,gEAAgE;AAChE,eAAO,MAAM,wBAAwB,wCAAyC,CAAC;AAC/E,MAAM,MAAM,wBAAwB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjF,eAAO,MAAM,2BAA2B,0BAA2B,CAAC;AACpE,MAAM,MAAM,2BAA2B,GAAG,CAAC,OAAO,2BAA2B,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvF,qBAAa,wBAAwB;IAUnC,IAAI,CAAC,EAAE,MAAM,CAAC;IAad,KAAK,CAAC,EAAE,MAAM,CAAC;IAQf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAQlB,MAAM,CAAC,EAAE,MAAM,CAAC;IAQhB,MAAM,CAAC,EAAE,MAAM,CAAC;IAQhB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAQ3B,SAAS,CAAC,EAAE,MAAM,CAAC;IAUnB,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAU9B,MAAM,CAAC,EAAE,wBAAwB,CAAC;IAUlC,SAAS,CAAC,EAAE,2BAA2B,CAAC;CACzC;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf"}

package/dist/appointments/list-appointments-query.dto.js

@@ -9,10 +9,13 @@ var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ListAppointmentsQueryDto = void 0;
+exports.ListAppointmentsQueryDto = exports.APPOINTMENT_LIST_SORT_ORDER = exports.APPOINTMENT_LIST_SORT_BY = void 0;
 const swagger_1 = require("@nestjs/swagger");
 const class_validator_1 = require("class-validator");
 const appointment_status_dto_1 = require("./appointment-status.dto");
+/** Campo principal de ordenação na listagem de agendamentos. */
+exports.APPOINTMENT_LIST_SORT_BY = ['date', 'checkin_completed'];
+exports.APPOINTMENT_LIST_SORT_ORDER = ['ASC', 'DESC'];
 class ListAppointmentsQueryDto {
     page;
     limit;
@@ -22,6 +25,8 @@ class ListAppointmentsQueryDto {
     checkinCompleted;
     patientId;
     status;
+    sortBy;
+    sortOrder;
 }
 exports.ListAppointmentsQueryDto = ListAppointmentsQueryDto;
 __decorate([
@@ -106,3 +111,23 @@ __decorate([
     (0, class_validator_1.IsIn)(appointment_status_dto_1.APPOINTMENT_STATUSES),
     __metadata("design:type", String)
 ], ListAppointmentsQueryDto.prototype, "status", void 0);
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        description: 'Ordenação principal: `date` (data do agendamento) ou `checkin_completed` (check-in feito ou pendente). Omisso = `date`.',
+        enum: exports.APPOINTMENT_LIST_SORT_BY,
+        example: 'checkin_completed',
+    }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsIn)(exports.APPOINTMENT_LIST_SORT_BY),
+    __metadata("design:type", String)
+], ListAppointmentsQueryDto.prototype, "sortBy", void 0);
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        description: 'Direção: `ASC` ou `DESC`. Com `sortBy=checkin_completed`, `ASC` coloca pendentes (false) primeiro; `DESC` coloca concluídos (true) primeiro. Com ordenação por data, aplica-se à coluna `date`.',
+        enum: exports.APPOINTMENT_LIST_SORT_ORDER,
+        example: 'ASC',
+    }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsIn)(exports.APPOINTMENT_LIST_SORT_ORDER),
+    __metadata("design:type", String)
+], ListAppointmentsQueryDto.prototype, "sortOrder", void 0);

package/dist/patients/index.d.ts

@@ -2,6 +2,7 @@ export * from './create-patient.dto';
 export * from './update-patient.dto';
 export * from './patient-history-entry.dto';
 export * from './list-patients-query.dto';
+export * from './list-patients-filters.dto';
 export * from './upsert-patient-by-phone.dto';
 export * from './patient-status.dto';
 //# sourceMappingURL=index.d.ts.map

package/dist/patients/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/patients/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/patients/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,sBAAsB,CAAC"}

package/dist/patients/index.js

@@ -18,5 +18,6 @@ __exportStar(require("./create-patient.dto"), exports);
 __exportStar(require("./update-patient.dto"), exports);
 __exportStar(require("./patient-history-entry.dto"), exports);
 __exportStar(require("./list-patients-query.dto"), exports);
+__exportStar(require("./list-patients-filters.dto"), exports);
 __exportStar(require("./upsert-patient-by-phone.dto"), exports);
 __exportStar(require("./patient-status.dto"), exports);

package/dist/patients/list-patients-filters.dto.d.ts

@@ -0,0 +1,19 @@
+import { ValidationArguments, ValidatorConstraintInterface } from 'class-validator';
+/** Propriedades da entidade paciente permitidas em `filters[].key` (API camelCase). */
+export declare const PATIENT_LIST_FILTER_KEYS: readonly ["id", "status", "name", "cpf", "birthDate", "email", "phone", "gender", "address", "hasDisability", "disabilityDescription", "createdAt", "updatedAt"];
+export type PatientListFilterKeyDto = (typeof PATIENT_LIST_FILTER_KEYS)[number];
+export declare const PATIENT_LIST_FILTER_OPS: readonly ["==", ">", "<", ">=", "<=", "!=", "in"];
+export type PatientListFilterOpDto = (typeof PATIENT_LIST_FILTER_OPS)[number];
+export declare class PatientListFilterValueConstraint implements ValidatorConstraintInterface {
+    validate(value: unknown, args: ValidationArguments): boolean;
+    defaultMessage(): string;
+}
+/**
+ * Um critério de filtro na listagem de pacientes. Apenas `key`, `op` e `value`.
+ */
+export declare class PatientListFilterDto {
+    key: PatientListFilterKeyDto;
+    op: PatientListFilterOpDto;
+    value: unknown;
+}
+//# sourceMappingURL=list-patients-filters.dto.d.ts.map

package/dist/patients/list-patients-filters.dto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-patients-filters.dto.d.ts","sourceRoot":"","sources":["../../src/patients/list-patients-filters.dto.ts"],"names":[],"mappings":"AAEA,OAAO,EAQL,mBAAmB,EAEnB,4BAA4B,EAC7B,MAAM,iBAAiB,CAAC;AAEzB,uFAAuF;AACvF,eAAO,MAAM,wBAAwB,kKAc3B,CAAC;AACX,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhF,eAAO,MAAM,uBAAuB,mDAQ1B,CAAC;AACX,MAAM,MAAM,sBAAsB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9E,qBACa,gCAAiC,YAAW,4BAA4B;IACnF,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,mBAAmB,GAAG,OAAO;IAS5D,cAAc,IAAI,MAAM;CAKzB;AAED;;GAEG;AACH,qBAAa,oBAAoB;IAQ/B,GAAG,EAAE,uBAAuB,CAAC;IAS7B,EAAE,EAAE,sBAAsB,CAAC;IAQ3B,KAAK,EAAE,OAAO,CAAC;CAChB"}

package/dist/patients/list-patients-filters.dto.js

@@ -0,0 +1,93 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PatientListFilterDto = exports.PatientListFilterValueConstraint = exports.PATIENT_LIST_FILTER_OPS = exports.PATIENT_LIST_FILTER_KEYS = void 0;
+const swagger_1 = require("@nestjs/swagger");
+const class_validator_1 = require("class-validator");
+/** Propriedades da entidade paciente permitidas em `filters[].key` (API camelCase). */
+exports.PATIENT_LIST_FILTER_KEYS = [
+    'id',
+    'status',
+    'name',
+    'cpf',
+    'birthDate',
+    'email',
+    'phone',
+    'gender',
+    'address',
+    'hasDisability',
+    'disabilityDescription',
+    'createdAt',
+    'updatedAt',
+];
+exports.PATIENT_LIST_FILTER_OPS = [
+    '==',
+    '>',
+    '<',
+    '>=',
+    '<=',
+    '!=',
+    'in',
+];
+let PatientListFilterValueConstraint = class PatientListFilterValueConstraint {
+    validate(value, args) {
+        const obj = args.object;
+        const op = obj?.op;
+        if (op === 'in') {
+            return Array.isArray(value) && value.length >= 1;
+        }
+        return !Array.isArray(value);
+    }
+    defaultMessage() {
+        return ('Para op "in", value deve ser um array não vazio; para as demais operações, value não pode ser array');
+    }
+};
+exports.PatientListFilterValueConstraint = PatientListFilterValueConstraint;
+exports.PatientListFilterValueConstraint = PatientListFilterValueConstraint = __decorate([
+    (0, class_validator_1.ValidatorConstraint)({ name: 'patientListFilterValueShape', async: false })
+], PatientListFilterValueConstraint);
+/**
+ * Um critério de filtro na listagem de pacientes. Apenas `key`, `op` e `value`.
+ */
+class PatientListFilterDto {
+    key;
+    op;
+    value;
+}
+exports.PatientListFilterDto = PatientListFilterDto;
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Campo do paciente (camelCase, alinhado ao contrato da API)',
+        enum: exports.PATIENT_LIST_FILTER_KEYS,
+        example: 'cpf',
+    }),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsIn)(exports.PATIENT_LIST_FILTER_KEYS),
+    __metadata("design:type", String)
+], PatientListFilterDto.prototype, "key", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Operador de comparação',
+        enum: exports.PATIENT_LIST_FILTER_OPS,
+        example: '==',
+    }),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsIn)(exports.PATIENT_LIST_FILTER_OPS),
+    __metadata("design:type", String)
+], PatientListFilterDto.prototype, "op", void 0);
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        description: 'Valor escalar ou, com op "in", array de valores. null permitido para == / != em colunas opcionais.',
+        example: '12225217416',
+    }),
+    (0, class_validator_1.Validate)(PatientListFilterValueConstraint),
+    __metadata("design:type", Object)
+], PatientListFilterDto.prototype, "value", void 0);

package/dist/patients/list-patients-query.dto.d.ts

@@ -1,5 +1,7 @@
+import { PatientListFilterDto } from './list-patients-filters.dto';
 export declare class ListPatientsQueryDto {
     page?: number;
     limit?: number;
+    filters?: PatientListFilterDto[];
 }
 //# sourceMappingURL=list-patients-query.dto.d.ts.map

package/dist/patients/list-patients-query.dto.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"list-patients-query.dto.d.ts","sourceRoot":"","sources":["../../src/patients/list-patients-query.dto.ts"],"names":[],"mappings":"AAGA,qBAAa,oBAAoB;IAU/B,IAAI,CAAC,EAAE,MAAM,CAAC;IAad,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB"}
+{"version":3,"file":"list-patients-query.dto.d.ts","sourceRoot":"","sources":["../../src/patients/list-patients-query.dto.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAuBnE,qBAAa,oBAAoB;IAU/B,IAAI,CAAC,EAAE,MAAM,CAAC;IAad,KAAK,CAAC,EAAE,MAAM,CAAC;IAcf,OAAO,CAAC,EAAE,oBAAoB,EAAE,CAAC;CAClC"}

package/dist/patients/list-patients-query.dto.js

@@ -11,10 +11,34 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ListPatientsQueryDto = void 0;
 const swagger_1 = require("@nestjs/swagger");
+const class_transformer_1 = require("class-transformer");
 const class_validator_1 = require("class-validator");
+const list_patients_filters_dto_1 = require("./list-patients-filters.dto");
+function parseFiltersFromQuery(value) {
+    if (value === undefined || value === null || value === '') {
+        return undefined;
+    }
+    if (Array.isArray(value)) {
+        return value;
+    }
+    if (typeof value === 'string') {
+        try {
+            const parsed = JSON.parse(value);
+            if (!Array.isArray(parsed)) {
+                return undefined;
+            }
+            return parsed;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}
 class ListPatientsQueryDto {
     page;
     limit;
+    filters;
 }
 exports.ListPatientsQueryDto = ListPatientsQueryDto;
 __decorate([
@@ -43,3 +67,17 @@ __decorate([
     (0, class_validator_1.Max)(100),
     __metadata("design:type", Number)
 ], ListPatientsQueryDto.prototype, "limit", void 0);
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        description: 'Lista de filtros `{ key, op, value }`. Query HTTP: enviar JSON string (ex.: `filters=[{"key":"cpf","op":"==","value":"12225217416"}]`). Operações: ==, !=, >, <, >=, <=, in (value array).',
+        type: [list_patients_filters_dto_1.PatientListFilterDto],
+        isArray: true,
+    }),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_transformer_1.Transform)(({ value }) => parseFiltersFromQuery(value)),
+    (0, class_validator_1.IsArray)(),
+    (0, class_validator_1.ArrayMinSize)(0),
+    (0, class_validator_1.ValidateNested)({ each: true }),
+    (0, class_transformer_1.Type)(() => list_patients_filters_dto_1.PatientListFilterDto),
+    __metadata("design:type", Array)
+], ListPatientsQueryDto.prototype, "filters", void 0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tychat-contracts",
-  "version": "1.0.95",
+  "version": "1.0.97",
   "description": "DTOs compartilhados com class-validator (API e microserviços)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/appointments/list-appointments-query.dto.ts

@@ -3,6 +3,13 @@ import { IsBoolean, IsDateString, IsIn, IsInt, IsOptional, IsString, IsUUID, Max
 import { AppointmentDto } from './appointment.dto';
 import { APPOINTMENT_STATUSES, AppointmentStatusDto } from './appointment-status.dto';
 
+/** Campo principal de ordenação na listagem de agendamentos. */
+export const APPOINTMENT_LIST_SORT_BY = ['date', 'checkin_completed'] as const;
+export type AppointmentListSortByDto = (typeof APPOINTMENT_LIST_SORT_BY)[number];
+
+export const APPOINTMENT_LIST_SORT_ORDER = ['ASC', 'DESC'] as const;
+export type AppointmentListSortOrderDto = (typeof APPOINTMENT_LIST_SORT_ORDER)[number];
+
 export class ListAppointmentsQueryDto {
   @ApiPropertyOptional({
     description: 'Número da página (iniciando em 1)',
@@ -77,6 +84,26 @@ export class ListAppointmentsQueryDto {
   @IsString()
   @IsIn(APPOINTMENT_STATUSES)
   status?: AppointmentStatusDto;
+
+  @ApiPropertyOptional({
+    description:
+      'Ordenação principal: `date` (data do agendamento) ou `checkin_completed` (check-in feito ou pendente). Omisso = `date`.',
+    enum: APPOINTMENT_LIST_SORT_BY,
+    example: 'checkin_completed',
+  })
+  @IsOptional()
+  @IsIn(APPOINTMENT_LIST_SORT_BY)
+  sortBy?: AppointmentListSortByDto;
+
+  @ApiPropertyOptional({
+    description:
+      'Direção: `ASC` ou `DESC`. Com `sortBy=checkin_completed`, `ASC` coloca pendentes (false) primeiro; `DESC` coloca concluídos (true) primeiro. Com ordenação por data, aplica-se à coluna `date`.',
+    enum: APPOINTMENT_LIST_SORT_ORDER,
+    example: 'ASC',
+  })
+  @IsOptional()
+  @IsIn(APPOINTMENT_LIST_SORT_ORDER)
+  sortOrder?: AppointmentListSortOrderDto;
 }
 
 export interface AppointmentListResult {

package/src/patients/index.ts

@@ -2,6 +2,7 @@ export * from './create-patient.dto';
 export * from './update-patient.dto';
 export * from './patient-history-entry.dto';
 export * from './list-patients-query.dto';
+export * from './list-patients-filters.dto';
 export * from './upsert-patient-by-phone.dto';
 export * from './patient-status.dto';
 

package/src/patients/list-patients-filters.dto.ts

@@ -0,0 +1,92 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { Type } from 'class-transformer';
+import {
+  ArrayMinSize,
+  IsArray,
+  IsIn,
+  IsOptional,
+  IsString,
+  Validate,
+  ValidateNested,
+  ValidationArguments,
+  ValidatorConstraint,
+  ValidatorConstraintInterface,
+} from 'class-validator';
+
+/** Propriedades da entidade paciente permitidas em `filters[].key` (API camelCase). */
+export const PATIENT_LIST_FILTER_KEYS = [
+  'id',
+  'status',
+  'name',
+  'cpf',
+  'birthDate',
+  'email',
+  'phone',
+  'gender',
+  'address',
+  'hasDisability',
+  'disabilityDescription',
+  'createdAt',
+  'updatedAt',
+] as const;
+export type PatientListFilterKeyDto = (typeof PATIENT_LIST_FILTER_KEYS)[number];
+
+export const PATIENT_LIST_FILTER_OPS = [
+  '==',
+  '>',
+  '<',
+  '>=',
+  '<=',
+  '!=',
+  'in',
+] as const;
+export type PatientListFilterOpDto = (typeof PATIENT_LIST_FILTER_OPS)[number];
+
+@ValidatorConstraint({ name: 'patientListFilterValueShape', async: false })
+export class PatientListFilterValueConstraint implements ValidatorConstraintInterface {
+  validate(value: unknown, args: ValidationArguments): boolean {
+    const obj = args.object as PatientListFilterDto;
+    const op = obj?.op;
+    if (op === 'in') {
+      return Array.isArray(value) && value.length >= 1;
+    }
+    return !Array.isArray(value);
+  }
+
+  defaultMessage(): string {
+    return (
+      'Para op "in", value deve ser um array não vazio; para as demais operações, value não pode ser array'
+    );
+  }
+}
+
+/**
+ * Um critério de filtro na listagem de pacientes. Apenas `key`, `op` e `value`.
+ */
+export class PatientListFilterDto {
+  @ApiProperty({
+    description: 'Campo do paciente (camelCase, alinhado ao contrato da API)',
+    enum: PATIENT_LIST_FILTER_KEYS,
+    example: 'cpf',
+  })
+  @IsString()
+  @IsIn(PATIENT_LIST_FILTER_KEYS)
+  key: PatientListFilterKeyDto;
+
+  @ApiProperty({
+    description: 'Operador de comparação',
+    enum: PATIENT_LIST_FILTER_OPS,
+    example: '==',
+  })
+  @IsString()
+  @IsIn(PATIENT_LIST_FILTER_OPS)
+  op: PatientListFilterOpDto;
+
+  @ApiPropertyOptional({
+    description:
+      'Valor escalar ou, com op "in", array de valores. null permitido para == / != em colunas opcionais.',
+    example: '12225217416',
+  })
+  @Validate(PatientListFilterValueConstraint)
+  value: unknown;
+}

package/src/patients/list-patients-query.dto.ts

@@ -1,5 +1,36 @@
 import { ApiPropertyOptional } from '@nestjs/swagger';
-import { IsInt, IsOptional, Max, Min } from 'class-validator';
+import { Transform, Type } from 'class-transformer';
+import {
+  ArrayMinSize,
+  IsArray,
+  IsInt,
+  IsOptional,
+  Max,
+  Min,
+  ValidateNested,
+} from 'class-validator';
+import { PatientListFilterDto } from './list-patients-filters.dto';
+
+function parseFiltersFromQuery(value: unknown): PatientListFilterDto[] | undefined {
+  if (value === undefined || value === null || value === '') {
+    return undefined;
+  }
+  if (Array.isArray(value)) {
+    return value as PatientListFilterDto[];
+  }
+  if (typeof value === 'string') {
+    try {
+      const parsed = JSON.parse(value) as unknown;
+      if (!Array.isArray(parsed)) {
+        return undefined;
+      }
+      return parsed as PatientListFilterDto[];
+    } catch {
+      return undefined;
+    }
+  }
+  return undefined;
+}
 
 export class ListPatientsQueryDto {
   @ApiPropertyOptional({
@@ -25,5 +56,19 @@ export class ListPatientsQueryDto {
   @Min(1)
   @Max(100)
   limit?: number;
+
+  @ApiPropertyOptional({
+    description:
+      'Lista de filtros `{ key, op, value }`. Query HTTP: enviar JSON string (ex.: `filters=[{"key":"cpf","op":"==","value":"12225217416"}]`). Operações: ==, !=, >, <, >=, <=, in (value array).',
+    type: [PatientListFilterDto],
+    isArray: true,
+  })
+  @IsOptional()
+  @Transform(({ value }) => parseFiltersFromQuery(value))
+  @IsArray()
+  @ArrayMinSize(0)
+  @ValidateNested({ each: true })
+  @Type(() => PatientListFilterDto)
+  filters?: PatientListFilterDto[];
 }