@floristcloud/api-lib 1.2.107 → 1.2.108

package/build/schemas/money-account/money-account-with-balance.schema.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MoneyAccountWithBalanceSchema = void 0;
+const zod_1 = require("zod");
+const money_account_schema_1 = require("./money-account.schema");
+/**
+ * Денежный счёт в ответах списков. `balance` — текущий остаток счёта (приход минус расход),
+ * приходит только при `?withBalance=true`: поле аддитивное, клиенты без этого параметра
+ * получают ровно прежнюю форму ответа.
+ */
+exports.MoneyAccountWithBalanceSchema = money_account_schema_1.MoneyAccountSchema.extend({
+    balance: zod_1.z.number().optional(),
+});

package/build/schemas/report/inventory-stock-category-item.schema.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InventoryStockCategoryItemSchema = void 0;
+const zod_1 = require("zod");
+/** Строка отчёта об остатках в разрезе категорий (`detailed=false`). */
+exports.InventoryStockCategoryItemSchema = zod_1.z.object({
+    categoryUUID: zod_1.z.string(),
+    categoryName: zod_1.z.string(),
+    balance: zod_1.z.number(),
+});

package/build/schemas/report/inventory-stock-detailed-item.schema.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InventoryStockDetailedItemSchema = void 0;
+const zod_1 = require("zod");
+/** Строка отчёта об остатках с детализацией по name/size/grower (`detailed=true`). */
+exports.InventoryStockDetailedItemSchema = zod_1.z.object({
+    categoryUUID: zod_1.z.string(),
+    categoryName: zod_1.z.string(),
+    name: zod_1.z.string(),
+    color: zod_1.z.string().nullable(),
+    size: zod_1.z.string().nullable(),
+    grower: zod_1.z.string().nullable(),
+    balance: zod_1.z.number(),
+});

package/build/schemas/report/inventory-turnover-category-item.schema.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InventoryTurnoverCategoryItemSchema = void 0;
+const zod_1 = require("zod");
+/** Строка отчёта об оборачиваемости в разрезе категорий (`detailed=false`). */
+exports.InventoryTurnoverCategoryItemSchema = zod_1.z.object({
+    categoryUUID: zod_1.z.string(),
+    categoryName: zod_1.z.string(),
+    initialBalance: zod_1.z.number(), // начальный остаток
+    receipts: zod_1.z.number(), // приходы
+    sales: zod_1.z.number(), // продажи
+    currentBalance: zod_1.z.number(), // текущий остаток
+    daysInStock: zod_1.z.number(), // дни в наличии на складе
+    turnoverRate: zod_1.z.number(), // коэффициент оборачиваемости
+});

package/build/schemas/report/inventory-turnover-detailed-item.schema.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InventoryTurnoverDetailedItemSchema = void 0;
+const zod_1 = require("zod");
+/** Строка отчёта об оборачиваемости с детализацией по name/size/grower (`detailed=true`). */
+exports.InventoryTurnoverDetailedItemSchema = zod_1.z.object({
+    categoryUUID: zod_1.z.string(),
+    categoryName: zod_1.z.string(),
+    name: zod_1.z.string(),
+    color: zod_1.z.string().nullable(),
+    size: zod_1.z.string().nullable(),
+    grower: zod_1.z.string().nullable(), // производитель
+    initialBalance: zod_1.z.number(), // начальный остаток
+    receipts: zod_1.z.number(), // приходы
+    sales: zod_1.z.number(), // продажи
+    currentBalance: zod_1.z.number(), // текущий остаток
+    daysInStock: zod_1.z.number(), // дни в наличии на складе
+    turnoverRate: zod_1.z.number(), // коэффициент оборачиваемости
+});

package/build/schemas/report/sales-by-client-row.schema.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SalesByClientRowSchema = void 0;
+const zod_1 = require("zod");
+const sales_by_client_top_item_schema_1 = require("./sales-by-client-top-item.schema");
+/**
+ * Строка отчёта «продажи по клиентам» — те же данные, что уходят в Excel из `export/sales/clients`.
+ * Опциональные поля отсутствуют в ответе, когда у клиента нет соответствующего значения.
+ */
+exports.SalesByClientRowSchema = zod_1.z.object({
+    uuid: zod_1.z.string(),
+    clientName: zod_1.z.string(),
+    responsibleUserName: zod_1.z.string().optional(),
+    totalOrders: zod_1.z.number(),
+    soldUnits: zod_1.z.number(),
+    soldUnitsByUnit: zod_1.z.object({
+        PIECE: zod_1.z.number(),
+        PACK: zod_1.z.number(),
+        BOX: zod_1.z.number(),
+    }),
+    totalSales: zod_1.z.number(),
+    avgCheck: zod_1.z.number(),
+    totalWriteOff: zod_1.z.number(),
+    grossProfit: zod_1.z.number(),
+    marginality: zod_1.z.number(),
+    // Оплаты (INCOME) и предоплаты (PREPAYMENT) клиента за период
+    totalPayments: zod_1.z.number(),
+    totalPrepayments: zod_1.z.number(),
+    // Сумма услуг (order_service_line) за период — отдельно, вне товарных sales/margin
+    totalServiceAmount: zod_1.z.number(),
+    // Текущий баланс клиента (на момент формирования отчёта)
+    balance: zod_1.z.number(),
+    lastOrderDate: zod_1.z.coerce.date().optional(),
+    // Топ-5 по сумме выручки за период
+    topCategories: zod_1.z.array(sales_by_client_top_item_schema_1.SalesByClientTopItemSchema),
+    topProducts: zod_1.z.array(sales_by_client_top_item_schema_1.SalesByClientTopItemSchema),
+    // Статическая информация о клиенте
+    code: zod_1.z.string().optional(),
+    city: zod_1.z.string().optional(),
+    contactName: zod_1.z.string().optional(),
+    phone: zod_1.z.string().optional(),
+    clientType: zod_1.z.string().optional(),
+    status: zod_1.z.string().optional(),
+    group: zod_1.z.string().optional(),
+});

package/build/schemas/report/sales-by-client-top-item.schema.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SalesByClientTopItemSchema = void 0;
+const zod_1 = require("zod");
+/** Элемент топа (категория или товар) внутри строки отчёта «продажи по клиентам». */
+exports.SalesByClientTopItemSchema = zod_1.z.object({
+    name: zod_1.z.string(),
+    amount: zod_1.z.number(),
+});

package/commands/client/create-client.command.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { ClientSchema } from '../../schemas';
 import { ClientStatusEnum } from '../../enum/client-status.enum';
+import { ClientContractStatusEnum } from '../../enum/client-contract-status.enum';
 import { ClientTypeEnum } from '../../enum/client-type.enum';
 
 const CreateClientRequestSchema = z.object({
@@ -13,6 +14,7 @@ const CreateClientRequestSchema = z.object({
     isCommon: z.coerce.boolean(),
     contractNumber: z.string().nullable().optional(),
     contractDate: z.coerce.date().nullable().optional(),
+    contractStatus: z.nativeEnum(ClientContractStatusEnum).optional(),
     address: z.string().nullable().optional(),
     city: z.string().nullable().optional(),
     code: z.string().nullable().optional(),

package/commands/client/get-client-list.query.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { ClientExtendedListSchema } from '../../schemas';
 import { ClientStatusEnum } from '../../enum/client-status.enum';
+import { ClientContractStatusEnum } from '../../enum/client-contract-status.enum';
 import { ClientTypeEnum } from '../../enum/client-type.enum';
 
 const GetClientListRequestSchema = z.object({
@@ -17,6 +18,13 @@ const GetClientListRequestSchema = z.object({
         .string()
         .optional()
         .transform(val => (val === 'true' ? true : val === 'false' || val === '' ? false : undefined)),
+    contractStatus: z.nativeEnum(ClientContractStatusEnum).optional(),
+    // Feeds the "Contracts" tab: a client counts as having a contract record when a number or a date
+    // is filled in, or the contract status has been moved off NONE.
+    hasContractRecord: z
+        .string()
+        .optional()
+        .transform(val => (val === 'true' ? true : val === 'false' ? false : undefined)),
 });
 
 const GetClientListResponseSchema = z.object({

package/commands/client/index.ts

@@ -4,6 +4,7 @@ export * from './get-client-list.query';
 export * from './get-client-debt-list.query';
 export * from './create-client.command';
 export * from './update-client.command';
+export * from './update-client-contract-data.command';
 export * from './delete-client.command';
 export * from './get-client-calculate.query';
 export * from './set-balance-calculate-client.command';

package/commands/client/update-client-contract-data.command.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+import { ClientSchema } from '../../schemas';
+import { ClientContractStatusEnum } from '../../enum/client-contract-status.enum';
+
+// Narrow, partial counterpart of UpdateClientContract: touches only the contract fields, so a
+// one-click status change cannot overwrite the rest of the client with a stale snapshot.
+const UpdateClientContractDataRequestSchema = z.object({
+    contractNumber: z.string().nullable().optional(),
+    contractDate: z.coerce.date().nullable().optional(),
+    contractStatus: z.nativeEnum(ClientContractStatusEnum).optional(),
+});
+
+const UpdateClientContractDataResponseSchema = z.object({
+    message: z.string().optional(),
+    data: ClientSchema.nullable(),
+});
+
+export namespace UpdateClientContractDataContractCommand {
+    export const RequestSchema = UpdateClientContractDataRequestSchema;
+    export type Request = z.infer<typeof RequestSchema>;
+
+    export const ResponseSchema = UpdateClientContractDataResponseSchema;
+    export type Response = z.infer<typeof ResponseSchema>;
+}

package/commands/client/update-client.command.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { ClientSchema } from '../../schemas';
 import { ClientStatusEnum } from '../../enum/client-status.enum';
+import { ClientContractStatusEnum } from '../../enum/client-contract-status.enum';
 import { ClientTypeEnum } from '../../enum/client-type.enum';
 
 const UpdateClientRequestSchema = z.object({
@@ -13,6 +14,7 @@ const UpdateClientRequestSchema = z.object({
     type: z.nativeEnum(ClientTypeEnum),
     contractNumber: z.string().nullable(),
     contractDate: z.coerce.date().nullable(),
+    contractStatus: z.nativeEnum(ClientContractStatusEnum).optional(),
     address: z.string().nullable().optional(),
     city: z.string().nullable().optional(),
     code: z.string().nullable().optional(),

package/commands/money-account/get-money-account-by-criteria.query.ts

@@ -1,11 +1,18 @@
 import { z } from 'zod';
-import { MoneyAccountSchema } from '../../schemas';
+import { MoneyAccountWithBalanceSchema } from '../../schemas';
+import { queryBooleanSchema } from '../../helpers/query-boolean.helper';
 
-const GetMoneyAccountByCriteriaRequestSchema = z.object({});
+const GetMoneyAccountByCriteriaRequestSchema = z.object({
+    // Опционально: посчитать остаток каждого счёта одним агрегатом вместо отдельного
+    // GET /transaction/sum/:moneyAccountUUID на каждый счёт. Описание видит и MCP-каталог.
+    withBalance: queryBooleanSchema.describe(
+        'Pass "true" to include the current balance of every money account, instead of calling transaction/sum per account.',
+    ),
+});
 
 const GetMoneyAccountByCriteriaResponseSchema = z.object({
     message: z.string().optional(),
-    data: MoneyAccountSchema.array(),
+    data: MoneyAccountWithBalanceSchema.array(),
 });
 
 export namespace GetMoneyAccountByCriteriaContractQuery {

package/commands/money-account/get-money-account-list.query.ts

@@ -1,15 +1,21 @@
 import { z } from 'zod';
-import { MoneyAccountSchema } from '../../schemas';
+import { MoneyAccountWithBalanceSchema } from '../../schemas';
+import { queryBooleanSchema } from '../../helpers/query-boolean.helper';
 
 const GetMoneyAccountListRequestSchema = z.object({
     page: z.string().transform(val => Number(val) || 1),
     count: z.string().transform(val => Number(val) || 10),
+    // Опционально: посчитать остаток каждого счёта одним агрегатом вместо отдельного
+    // GET /transaction/sum/:moneyAccountUUID на каждый счёт. Описание видит и MCP-каталог.
+    withBalance: queryBooleanSchema.describe(
+        'Pass "true" to include the current balance of every money account, instead of calling transaction/sum per account.',
+    ),
 });
 
 const GetMoneyAccountListResponseSchema = z.object({
     message: z.string().optional(),
     data: z.object({
-        list: z.array(MoneyAccountSchema),
+        list: z.array(MoneyAccountWithBalanceSchema),
         total: z.number(),
     }),
 });

package/commands/report/export-inventory-stock.query.ts

@@ -1,30 +1,15 @@
 import { z } from 'zod';
+import { InventoryStockCategoryItemSchema } from '../../schemas/report/inventory-stock-category-item.schema';
+import { InventoryStockDetailedItemSchema } from '../../schemas/report/inventory-stock-detailed-item.schema';
 
 const ExportInventoryStockRequestSchema = z.object({
     categoryUUID: z.uuid().optional(), // Фильтр по категории
     detailed: z.coerce.boolean().optional().default(false), // Флаг для детализации (группировка по name, size, grower)
 });
 
-// Ответ для обычного отчета (по категориям)
-const CategoryStockItemSchema = z.object({
-    categoryUUID: z.string(),
-    categoryName: z.string(),
-    balance: z.number(),
-});
-
-// Ответ для детализированного отчета (с группировкой по name, size, grower)
-const DetailedStockItemSchema = z.object({
-    categoryUUID: z.string(),
-    categoryName: z.string(),
-    name: z.string(),
-    color: z.string().nullable(),
-    size: z.string().nullable(),
-    grower: z.string().nullable(),
-    balance: z.number(),
-});
-
+// Строки живут в schemas/report — их же отдаёт JSON-эндпоинт report/inventory/stock, форма ответа общая.
 const ExportInventoryStockResponseSchema = z.object({
-    data: z.array(z.union([CategoryStockItemSchema, DetailedStockItemSchema])),
+    data: z.array(z.union([InventoryStockCategoryItemSchema, InventoryStockDetailedItemSchema])),
 });
 
 export namespace ExportInventoryStockContractQuery {

package/commands/report/export-inventory-turnover.query.ts

@@ -1,5 +1,7 @@
 import { z } from 'zod';
 import { dateRangeCheck } from '../../helpers/date.helper';
+import { InventoryTurnoverCategoryItemSchema } from '../../schemas/report/inventory-turnover-category-item.schema';
+import { InventoryTurnoverDetailedItemSchema } from '../../schemas/report/inventory-turnover-detailed-item.schema';
 
 const ExportInventoryTurnoverRequestSchema = z
     .object({
@@ -22,36 +24,9 @@ const ExportInventoryTurnoverRequestSchema = z
         },
     );
 
-// Ответ для обычного отчета (по категориям)
-const CategoryTurnoverItemSchema = z.object({
-    categoryUUID: z.string(),
-    categoryName: z.string(),
-    initialBalance: z.number(), // начальный остаток
-    receipts: z.number(), // приходы
-    sales: z.number(), // продажи
-    currentBalance: z.number(), // текущий остаток
-    daysInStock: z.number(), // дни в наличии на складе
-    turnoverRate: z.number(), // коэффициент оборачиваемости
-});
-
-// Ответ для детализированного отчета (с группировкой по name, size, grower)
-const DetailedTurnoverItemSchema = z.object({
-    categoryUUID: z.string(),
-    categoryName: z.string(),
-    name: z.string(),
-    color: z.string().nullable(),
-    size: z.string().nullable(),
-    grower: z.string().nullable(), // производитель
-    initialBalance: z.number(), // начальный остаток
-    receipts: z.number(), // приходы
-    sales: z.number(), // продажи
-    currentBalance: z.number(), // текущий остаток
-    daysInStock: z.number(), // дни в наличии на складе
-    turnoverRate: z.number(), // коэффициент оборачиваемости
-});
-
+// Строки живут в schemas/report — их же отдаёт JSON-эндпоинт report/inventory/turnover, форма ответа общая.
 const ExportInventoryTurnoverResponseSchema = z.object({
-    data: z.array(z.union([CategoryTurnoverItemSchema, DetailedTurnoverItemSchema])),
+    data: z.array(z.union([InventoryTurnoverCategoryItemSchema, InventoryTurnoverDetailedItemSchema])),
 });
 
 export namespace ExportInventoryTurnoverContractQuery {

package/commands/report/get-inventory-stock.query.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+import { isPageAccompaniedByCount } from '../../helpers/pagination.helper';
+import { queryBooleanSchema } from '../../helpers/query-boolean.helper';
+import { InventoryStockCategoryItemSchema } from '../../schemas/report/inventory-stock-category-item.schema';
+import { InventoryStockDetailedItemSchema } from '../../schemas/report/inventory-stock-detailed-item.schema';
+
+const GetInventoryStockRequestSchema = z
+    .object({
+        categoryUUID: z.uuid().optional().describe('Keep only the products of this category.'),
+        detailed: queryBooleanSchema.describe('Pass "true" to group rows by product name / size / grower instead of by category only.'),
+        // Пагинация по строкам отчёта. Без count лимит не накладывается — отдаём весь отчёт,
+        // а page без count отклоняется: иначе листание молча возвращало бы одну и ту же выдачу.
+        page: z.coerce.number().int().positive().optional().describe('1-based page number, requires "count".'),
+        count: z.coerce.number().int().positive().optional().describe('Rows per page. Without it the whole report is returned.'),
+    })
+    .refine(isPageAccompaniedByCount, {
+        message: 'validation.pageRequiresCount',
+        path: ['page'],
+    });
+
+const GetInventoryStockResponseSchema = z.object({
+    message: z.string().optional(),
+    data: z.object({
+        list: z.array(z.union([InventoryStockCategoryItemSchema, InventoryStockDetailedItemSchema])),
+        // Число строк во всём отчёте — не размер страницы.
+        total: z.number(),
+    }),
+});
+
+export namespace GetInventoryStockContractQuery {
+    export const RequestSchema = GetInventoryStockRequestSchema;
+    export type Request = z.infer<typeof RequestSchema>;
+
+    export const ResponseSchema = GetInventoryStockResponseSchema;
+    export type Response = z.infer<typeof ResponseSchema>;
+}

package/commands/report/get-inventory-turnover.query.ts

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+import { dateRangeCheck } from '../../helpers/date.helper';
+import { isPageAccompaniedByCount } from '../../helpers/pagination.helper';
+import { queryBooleanSchema } from '../../helpers/query-boolean.helper';
+import { InventoryTurnoverCategoryItemSchema } from '../../schemas/report/inventory-turnover-category-item.schema';
+import { InventoryTurnoverDetailedItemSchema } from '../../schemas/report/inventory-turnover-detailed-item.schema';
+
+const GetInventoryTurnoverRequestSchema = z
+    .object({
+        // Даты обязательны: без периода оборачиваемость не считается (в отличие от export/*, где
+        // отсутствие дат приводило к ошибке уже внутри сервиса).
+        startDate: z.coerce.date(),
+        endDate: z.coerce.date(),
+        categoryUUID: z.uuid().optional().describe('Keep only the products of this category.'),
+        detailed: queryBooleanSchema.describe('Pass "true" to group rows by product name / size / grower instead of by category only.'),
+        // Пагинация по строкам отчёта. Без count лимит не накладывается — отдаём весь отчёт,
+        // а page без count отклоняется: иначе листание молча возвращало бы одну и ту же выдачу.
+        page: z.coerce.number().int().positive().optional().describe('1-based page number, requires "count".'),
+        count: z.coerce.number().int().positive().optional().describe('Rows per page. Without it the whole report is returned.'),
+    })
+    .refine(value => dateRangeCheck(value.startDate, value.endDate), {
+        message: 'validation.dateRange',
+        path: ['endDate', 'startDate'],
+    })
+    .refine(isPageAccompaniedByCount, {
+        message: 'validation.pageRequiresCount',
+        path: ['page'],
+    });
+
+const GetInventoryTurnoverResponseSchema = z.object({
+    message: z.string().optional(),
+    data: z.object({
+        list: z.array(z.union([InventoryTurnoverCategoryItemSchema, InventoryTurnoverDetailedItemSchema])),
+        // Число строк во всём отчёте — не размер страницы.
+        total: z.number(),
+    }),
+});
+
+export namespace GetInventoryTurnoverContractQuery {
+    export const RequestSchema = GetInventoryTurnoverRequestSchema;
+    export type Request = z.infer<typeof RequestSchema>;
+
+    export const ResponseSchema = GetInventoryTurnoverResponseSchema;
+    export type Response = z.infer<typeof ResponseSchema>;
+}

package/commands/report/get-report-by-client-weeks.query.ts

@@ -1,5 +1,7 @@
 import { z } from 'zod';
 import { dateRangeCheck } from '../../helpers/date.helper';
+import { isPageAccompaniedByCount } from '../../helpers/pagination.helper';
+import { queryBooleanSchema } from '../../helpers/query-boolean.helper';
 import { ClientByWeeksSchema } from '../../schemas';
 
 const GetReportByClientWeeksRequestSchema = z
@@ -7,6 +9,15 @@ const GetReportByClientWeeksRequestSchema = z
         startDate: z.coerce.date(),
         endDate: z.coerce.date(),
         responsibleUserUUID: z.string().optional(),
+        // Отчёт — это матрица «неделя × клиент», поэтому по умолчанию отдаёт строку и на нулевые недели.
+        // Флаг оставляет только недели с заказами: то, что обычно и нужно, и на порядок меньше данных.
+        onlyWithOrders: queryBooleanSchema,
+        // Фильтр по группе клиента (client."group") — дешёвый, применяется до CROSS JOIN недель.
+        clientGroup: z.string().optional(),
+        // Пагинация по строкам матрицы. Без count лимит не накладывается — поведение по умолчанию
+        // прежнее, а page без count отклоняется: иначе листание молча возвращало бы одну и ту же выдачу.
+        page: z.coerce.number().int().positive().optional(),
+        count: z.coerce.number().int().positive().optional(),
     })
     .refine(
         value => {
@@ -20,11 +31,19 @@ const GetReportByClientWeeksRequestSchema = z
             message: 'validation.dateRange',
             path: ['endDate', 'startDate'],
         },
-    );
+    )
+    .refine(isPageAccompaniedByCount, {
+        message: 'validation.pageRequiresCount',
+        path: ['page'],
+    });
 
 const GetReportGroupByClientResponseSchema = z.object({
     message: z.string().optional(),
     data: z.array(ClientByWeeksSchema),
+    // `total` лежит РЯДОМ с data, а не внутри неё: панель читает `data` как плоский массив строк,
+    // и обёртка `{ list, total }` (как в остальных пагинируемых отчётах) сломала бы ей рендер.
+    // Без total последняя страница неотличима от полной выдачи.
+    total: z.number().describe('Rows in the whole report, before "page"/"count" are applied.'),
 });
 
 export namespace GetReportByClientWeeksContractQuery {

package/commands/report/get-report-group-by-client.query.ts

@@ -1,10 +1,25 @@
 import { z } from 'zod';
-import { dateRangeCheck, setEndDay, setStartDay } from '../../helpers/date.helper';
+import { OrderByEnum, ReportSortByEnum } from '../../enum';
+import { dateRangeCheck } from '../../helpers/date.helper';
 
 const GetReportGroupByClientRequestSchema = z
     .object({
-        startDate: z.coerce.date().transform(val => (val ? setStartDay(val) : val)),
-        endDate: z.coerce.date().transform(val => (val ? setEndDay(val) : val)),
+        // Даты приходят «сырым» днём — раскладку в полуинтервал [start, endExclusive) делает сервис
+        // в таймзоне компании, как в cash-flow. Прежний setStartDay/setEndDay в UTC разворачивал день
+        // второй раз, и в таймзоне с плюсовым сдвигом конец периода уезжал на сутки вперёд.
+        startDate: z.coerce.date(),
+        endDate: z.coerce.date(),
+        // Сортировка НЕ имеет значения по умолчанию: без явного sortBy/sortOrder строки отдаются
+        // в том порядке, в каком их вернул отчёт (панель рендерит map в порядке ключей, и тихая
+        // пересортировка меняла бы ей вид таблицы). Исключение — limit: он срезает хвост, что без
+        // сортировки бессмысленно, поэтому при limit применяется порядок «по прибыли, убывание».
+        sortBy: z
+            .nativeEnum(ReportSortByEnum)
+            .optional()
+            .describe('Sort metric. Without it (and without "limit") rows keep the report order.'),
+        sortOrder: z.nativeEnum(OrderByEnum).optional().describe('Sort direction. Defaults to "desc" once sorting applies.'),
+        // Без значения — ограничения нет: панель по-прежнему получает все строки.
+        limit: z.coerce.number().int().positive().optional().describe('Keep only the top N rows; implies sorting by gross profit desc.'),
     })
     .refine(
         value => {
@@ -43,6 +58,10 @@ const GetReportGroupByClientResponseSchema = z.object({
                 marginality: z.number(),
             }),
         ),
+        // Аддитивно к прежней форме: число клиентов во ВСЁМ отчёте до усечения и применённый limit.
+        // Без них усечённый ответ неотличим от полного.
+        total: z.number().describe('Client rows in the whole report, before "limit".'),
+        limit: z.number().optional().describe('Row limit that actually cut rows off. Absent when the response is complete.'),
     }),
 });
 

package/commands/report/get-report-group-by-position.query.ts

@@ -1,13 +1,27 @@
 import { z } from 'zod';
-import { PositionReportTypeEnum } from '../../enum';
-import { dateRangeCheck, setEndDay, setStartDay } from '../../helpers/date.helper';
+import { OrderByEnum, PositionReportTypeEnum, ReportSortByEnum } from '../../enum';
+import { dateRangeCheck } from '../../helpers/date.helper';
 
 const GetReportGroupByPositionRequestSchema = z
     .object({
         type: z.nativeEnum(PositionReportTypeEnum).default(PositionReportTypeEnum.PRODUCT),
         categoryUUID: z.string().optional(),
-        startDate: z.coerce.date().transform(val => (val ? setStartDay(val) : val)),
-        endDate: z.coerce.date().transform(val => (val ? setEndDay(val) : val)),
+        // Даты приходят «сырым» днём — раскладку в полуинтервал [start, endExclusive) делает сервис
+        // в таймзоне компании, как в cash-flow. Прежний setStartDay/setEndDay в UTC разворачивал день
+        // второй раз, и в таймзоне с плюсовым сдвигом конец периода уезжал на сутки вперёд.
+        startDate: z.coerce.date(),
+        endDate: z.coerce.date(),
+        // Сортировка НЕ имеет значения по умолчанию: без явного sortBy/sortOrder строки отдаются
+        // в том порядке, в каком их вернул отчёт (панель рендерит map в порядке ключей, и тихая
+        // пересортировка меняла бы ей вид таблицы). Исключение — limit: он срезает хвост, что без
+        // сортировки бессмысленно, поэтому при limit применяется порядок «по прибыли, убывание».
+        sortBy: z
+            .nativeEnum(ReportSortByEnum)
+            .optional()
+            .describe('Sort metric. Without it (and without "limit") rows keep the report order.'),
+        sortOrder: z.nativeEnum(OrderByEnum).optional().describe('Sort direction. Defaults to "desc" once sorting applies.'),
+        // Без значения — ограничения нет: панель по-прежнему получает все строки.
+        limit: z.coerce.number().int().positive().optional().describe('Keep only the top N rows; implies sorting by gross profit desc.'),
     })
     .refine(
         value => {
@@ -67,6 +81,11 @@ const GetReportGroupByPositionResponseSchema = z.object({
                 }),
             )
             .optional(),
+        // Аддитивно к прежней форме: отчёт отдаёт ЛИБО категории, ЛИБО товары (при categoryUUID),
+        // поэтому total относится к той группировке, что вернулась. Вместе с limit это единственный
+        // способ отличить усечённый ответ от полного.
+        total: z.number().describe('Rows in the whole report (of the returned grouping), before "limit".'),
+        limit: z.number().optional().describe('Row limit that actually cut rows off. Absent when the response is complete.'),
     }),
 });
 

package/commands/report/get-sales-by-client.query.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+import { OrderByEnum, ReportSortByEnum } from '../../enum';
+import { dateRangeCheck, isStatementPeriodWithinLimit } from '../../helpers/date.helper';
+import { isPageAccompaniedByCount } from '../../helpers/pagination.helper';
+import { SalesByClientRowSchema } from '../../schemas/report/sales-by-client-row.schema';
+
+const GetSalesByClientRequestSchema = z
+    .object({
+        startDate: z.coerce.date(),
+        endDate: z.coerce.date(),
+        // По умолчанию самые прибыльные клиенты сверху, чтобы count срезал хвост, а не топ.
+        sortBy: z.nativeEnum(ReportSortByEnum).optional().default(ReportSortByEnum.GROSS_PROFIT),
+        sortOrder: z.nativeEnum(OrderByEnum).optional().default(OrderByEnum.DESC),
+        // Пагинация по строкам отчёта. Без count лимит не накладывается — отдаём всех клиентов,
+        // а page без count отклоняется: иначе листание молча возвращало бы одну и ту же выдачу.
+        page: z.coerce.number().int().positive().optional().describe('1-based page number, requires "count".'),
+        count: z.coerce.number().int().positive().optional().describe('Rows per page. Without it every client row is returned.'),
+    })
+    .refine(value => dateRangeCheck(value.startDate, value.endDate), {
+        message: 'validation.dateRange',
+        path: ['endDate', 'startDate'],
+    })
+    .refine(value => isStatementPeriodWithinLimit(value.startDate, value.endDate), {
+        message: 'validation.reportPeriodMax',
+        path: ['endDate', 'startDate'],
+    })
+    .refine(isPageAccompaniedByCount, {
+        message: 'validation.pageRequiresCount',
+        path: ['page'],
+    });
+
+const GetSalesByClientResponseSchema = z.object({
+    message: z.string().optional(),
+    data: z.object({
+        list: z.array(SalesByClientRowSchema),
+        // Число клиентов во всём отчёте — не размер страницы.
+        total: z.number(),
+    }),
+});
+
+export namespace GetSalesByClientContractQuery {
+    export const RequestSchema = GetSalesByClientRequestSchema;
+    export type Request = z.infer<typeof RequestSchema>;
+
+    export const ResponseSchema = GetSalesByClientResponseSchema;
+    export type Response = z.infer<typeof ResponseSchema>;
+}

package/commands/report/index.ts

@@ -12,3 +12,6 @@ export * from './export-client-statement.query';
 export * from './get-report-by-client-weeks.query';
 export * from './get-daily-orders-summary.query';
 export * from './get-cash-flow.query';
+export * from './get-inventory-stock.query';
+export * from './get-inventory-turnover.query';
+export * from './get-sales-by-client.query';