@floristcloud/api-lib 1.2.107 → 1.2.109

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,11 +1,30 @@
 import { z } from 'zod';
-import { dateRangeCheck, setEndDay, setStartDay } from '../../helpers/date.helper';
+import { OrderByEnum, ReportSortByEnum } from '../../enum';
+import { dateRangeCheck } from '../../helpers/date.helper';
+import { ReportOrderFilterSchema } from '../../schemas/report/report-order-filter.schema';
 
 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.'),
     })
+    // dateBasis / excludeClientUUID общие с sales/summary: обе цифры живут на одном экране и должны
+    // сужаться одинаково.
+    .merge(ReportOrderFilterSchema)
     .refine(
         value => {
             const { startDate, endDate } = value;
@@ -43,6 +62,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,50 @@
+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';
+import { ReportOrderFilterSchema } from '../../schemas/report/report-order-filter.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.'),
+    })
+    // dateBasis / excludeClientUUID — те же, что у JSON-эндпоинтов отчётов по заказам.
+    .merge(ReportOrderFilterSchema)
+    .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/get-sales-summary.query.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { dateRangeCheck } from '../../helpers/date.helper';
 import { ReportPeriodTypeEnum } from '../../enum/report-period-type.enum';
+import { ReportOrderFilterSchema } from '../../schemas/report/report-order-filter.schema';
 
 const GetSalesSummaryRequestSchema = z
     .object({
@@ -8,6 +9,9 @@ const GetSalesSummaryRequestSchema = z
         endDate: z.coerce.date().optional(),
         periodType: z.nativeEnum(ReportPeriodTypeEnum).default(ReportPeriodTypeEnum.DAY),
     })
+    // dateBasis / excludeClientUUID общие с group-client: обе цифры живут на одном экране и должны
+    // сужаться одинаково.
+    .merge(ReportOrderFilterSchema)
     .refine(
         value => {
             const { startDate, endDate } = value;

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';

package/commands/settings/get-company-profile.query.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+
+/**
+ * Company-level facts every panel role may read: who the company is, how it is named, which time
+ * zone its calendar days are counted in and which currency its figures are in. `companyUUID` is
+ * echoed so a caller can prove the profile belongs to its own tenant — the ADMIN-only
+ * `settings/for-admin` answer carries no such marker and cannot be cross-checked.
+ */
+const CompanyProfileSchema = z.object({
+    companyUUID: z.string(),
+    companyName: z.string().nullable(),
+    timeZone: z.string().nullable(),
+    currency: z.string().nullable(),
+});
+
+const GetCompanyProfileResponseSchema = z.object({
+    message: z.string().optional(),
+    data: CompanyProfileSchema,
+});
+
+export namespace GetCompanyProfileContractQuery {
+    export const ResponseSchema = GetCompanyProfileResponseSchema;
+    export type Response = z.infer<typeof ResponseSchema>;
+}

package/commands/settings/index.ts

@@ -1,3 +1,4 @@
 export * from './get-settings.query';
 export * from './update-settings.command';
 export * from './get-settings-for-admin.query';
+export * from './get-company-profile.query';

package/constant/index.ts

@@ -4,3 +4,4 @@ export * from './error-i18n-key';
 export * from './import.constant';
 export * from './validation-i18n-key';
 export * from './validation-i18n-message';
+export * from './report.constant';

package/constant/report.constant.ts

@@ -0,0 +1,6 @@
+/**
+ * Потолок списка исключаемых из отчёта клиентов. Список едет в query-строке и дальше в SQL
+ * как `= ANY($n::text[])`, поэтому ограничение защищает и от переполнения URL, и от запроса
+ * с массивом в тысячи элементов.
+ */
+export const REPORT_EXCLUDE_CLIENT_LIMIT = 500;

package/enum/client-contract-status.enum.ts

@@ -0,0 +1,9 @@
+export enum ClientContractStatusEnum {
+    NONE = 'NONE',
+    REQUIRED = 'REQUIRED',
+    PREPARED = 'PREPARED',
+    SENT = 'SENT',
+    SIGNED = 'SIGNED',
+    EXPIRED = 'EXPIRED',
+    TERMINATED = 'TERMINATED',
+}

package/enum/index.ts

@@ -36,6 +36,7 @@ export * from './order-distribute-status-list';
 export * from './order-active-status-list';
 export * from './order-price-correction-skipped-status-list';
 export * from './client-status.enum';
+export * from './client-contract-status.enum';
 export * from './client-type.enum';
 export * from './consignment-distribution-validation-status.enum';
 export * from './consignment-distribution-validation-type.enum';
@@ -95,3 +96,6 @@ export * from './legal-identifier-field.enum';
 export * from './permission-key.enum';
 export * from './cash-flow-item-status.enum';
 export * from './payment-invoice-status.enum';
+export * from './order-by.enum';
+export * from './report-sort-by.enum';
+export * from './report-order-date-basis.enum';

package/enum/report-order-date-basis.enum.ts

@@ -0,0 +1,14 @@
+/**
+ * Ось периода для отчётов по заказам — ровно одна дата на отчёт.
+ *
+ * CREATED_AT — по дате создания заказа (историческое поведение всех отчётов).
+ * COMPLETED_AT — по дате отгрузки (завершения); заказ, созданный в июне и отгруженный в июле,
+ * попадёт в июль.
+ *
+ * Дизъюнкции («любая из дат») здесь намеренно нет: заказ, созданный в июне и отгруженный в июле,
+ * попал бы в оба месяца, сумма отчётов по месяцам перестала бы сходиться с отчётом за квартал.
+ */
+export enum ReportOrderDateBasisEnum {
+    CREATED_AT = 'CREATED_AT',
+    COMPLETED_AT = 'COMPLETED_AT',
+}

package/enum/report-sort-by.enum.ts

@@ -0,0 +1,9 @@
+/**
+ * Метрика сортировки для отчётов-группировок (по позициям и по клиентам).
+ * Значения совпадают с именами полей ответа, чтобы клиент мог сортировать «по тому, что видит».
+ */
+export enum ReportSortByEnum {
+    GROSS_PROFIT = 'grossProfit',
+    TOTAL_SALES = 'totalSales',
+    SOLD_UNITS = 'soldUnits',
+}

package/helpers/index.ts

@@ -1 +1,3 @@
 export * from './date.helper';
+export * from './pagination.helper';
+export * from './query-boolean.helper';

package/helpers/pagination.helper.ts

@@ -0,0 +1,9 @@
+/**
+ * `page` имеет смысл только вместе с `count`.
+ *
+ * Раньше `page` без `count` молча игнорировался и отчёт отдавался целиком: агент, листающий
+ * страницы, бесконечно получал одну и ту же выдачу и не мог отличить это от «страниц больше нет».
+ * Поэтому неполная пара отклоняется валидацией — единообразно во всех постраничных отчётах.
+ */
+export const isPageAccompaniedByCount = (value: { page?: number; count?: number }): boolean =>
+    value.page === undefined || value.count !== undefined;

package/helpers/query-boolean.helper.ts

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+
+/**
+ * Boolean-флаг, приходящий в query-строке.
+ *
+ * Не `z.coerce.boolean()`: в query всегда приходит текст, а `Boolean('false') === true` —
+ * такой флаг невозможно выключить явным значением. Принимаем `true` / `1` как включение,
+ * всё остальное — выключение. По умолчанию флаг выключен, чтобы поведение без параметра не менялось.
+ */
+export const queryBooleanSchema = z
+    .union([z.boolean(), z.string()])
+    .optional()
+    .default(false)
+    .transform(value => (typeof value === 'boolean' ? value : value === 'true' || value === '1'));

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@floristcloud/api-lib",
-    "version": "1.2.107",
+    "version": "1.2.109",
     "description": "",
     "main": "./build/index.js",
     "scripts": {

package/schemas/client/client.schema.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { ClientStatusEnum } from '../../enum/client-status.enum';
+import { ClientContractStatusEnum } from '../../enum/client-contract-status.enum';
 import { ClientTypeEnum } from '../../enum/client-type.enum';
 import { UserSchema } from '../user/user.schema';
 import { ClientIndividualProfileSchema } from './client-individual-profile.schema';
@@ -17,6 +18,7 @@ export const ClientSchema = z.object({
     isCommon: z.boolean(),
     contractNumber: z.string().nullable(),
     contractDate: z.date().nullable(),
+    contractStatus: z.nativeEnum(ClientContractStatusEnum),
     address: z.string().nullable(),
     city: z.string().nullable(),
     code: z.string().nullable(),

package/schemas/index.ts

@@ -22,6 +22,7 @@ export * from './product-image/product-image.schema';
 export * from './settings/settings.schema';
 export * from './payment-invoice/payment-invoice.schema';
 export * from './money-account/money-account.schema';
+export * from './money-account/money-account-with-balance.schema';
 export * from './domain/domain.schema';
 export * from './category/category.schema';
 export * from './branch/branch.schema';
@@ -52,6 +53,12 @@ export * from './consignment/consignment-distribution-validation.schema';
 export * from './product-image-template/product-image-template.schema';
 export * from './report/client-statement.schema';
 export * from './report/client-by-weeks.schema';
+export * from './report/inventory-stock-category-item.schema';
+export * from './report/inventory-stock-detailed-item.schema';
+export * from './report/inventory-turnover-category-item.schema';
+export * from './report/inventory-turnover-detailed-item.schema';
+export * from './report/sales-by-client-top-item.schema';
+export * from './report/sales-by-client-row.schema';
 export * from './action-log/index';
 export * from './delivery-route/delivery-route.schema';
 export * from './product/product-multiplicity-option.schema';
@@ -70,3 +77,4 @@ export * from './account-deletion-request/account-deletion-request.schema';
 export * from './consignment-transfer';
 export * from './api-error.schema';
 export * from './access-policy';
+export * from './report/report-order-filter.schema';

package/schemas/money-account/money-account-with-balance.schema.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+import { MoneyAccountSchema } from './money-account.schema';
+
+/**
+ * Денежный счёт в ответах списков. `balance` — текущий остаток счёта (приход минус расход),
+ * приходит только при `?withBalance=true`: поле аддитивное, клиенты без этого параметра
+ * получают ровно прежнюю форму ответа.
+ */
+export const MoneyAccountWithBalanceSchema = MoneyAccountSchema.extend({
+    balance: z.number().optional(),
+});

package/schemas/report/inventory-stock-category-item.schema.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+
+/** Строка отчёта об остатках в разрезе категорий (`detailed=false`). */
+export const InventoryStockCategoryItemSchema = z.object({
+    categoryUUID: z.string(),
+    categoryName: z.string(),
+    balance: z.number(),
+});

package/schemas/report/inventory-stock-detailed-item.schema.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+
+/** Строка отчёта об остатках с детализацией по name/size/grower (`detailed=true`). */
+export const InventoryStockDetailedItemSchema = 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(),
+});

package/schemas/report/inventory-turnover-category-item.schema.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+
+/** Строка отчёта об оборачиваемости в разрезе категорий (`detailed=false`). */
+export const InventoryTurnoverCategoryItemSchema = 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(), // коэффициент оборачиваемости
+});

package/schemas/report/inventory-turnover-detailed-item.schema.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+
+/** Строка отчёта об оборачиваемости с детализацией по name/size/grower (`detailed=true`). */
+export const InventoryTurnoverDetailedItemSchema = 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(), // коэффициент оборачиваемости
+});

package/schemas/report/report-order-filter.schema.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+import { ReportOrderDateBasisEnum } from '../../enum';
+import { REPORT_EXCLUDE_CLIENT_LIMIT } from '../../constant/report.constant';
+
+/**
+ * Общие фильтры отчётов, построенных на заказах: по какой дате заказ попадает в период и каких
+ * клиентов из него выкинуть. Схема одна на все такие отчёты — иначе `sales/summary` и
+ * `group-client` на одном экране разошлись бы в семантике при первой же правке.
+ *
+ * `excludeClientUUID` — типовой случай «отгружаем по себестоимости, в прибыли не учитываем».
+ * Принимается и CSV (`?excludeClientUUID=uuid1,uuid2`, как в get-notifications-status), и повтор
+ * параметра (`?excludeClientUUID=uuid1&excludeClientUUID=uuid2`) — Express отдаёт второй вариант
+ * массивом, и требовать от фронта именно CSV незачем.
+ */
+export const ReportOrderFilterSchema = z.object({
+    dateBasis: z
+        .nativeEnum(ReportOrderDateBasisEnum)
+        .default(ReportOrderDateBasisEnum.CREATED_AT)
+        .describe('Which order date puts the order into the period. Defaults to the order creation date.'),
+    excludeClientUUID: z
+        .union([z.string(), z.array(z.string())])
+        .transform(value => (Array.isArray(value) ? value : value.split(',')).map(item => item.trim()).filter(Boolean))
+        .pipe(z.array(z.string().uuid()).max(REPORT_EXCLUDE_CLIENT_LIMIT))
+        .optional()
+        .describe('Clients to drop from the report entirely — their orders, revenue and cost.'),
+});

package/schemas/report/sales-by-client-row.schema.ts

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

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

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+
+/** Элемент топа (категория или товар) внутри строки отчёта «продажи по клиентам». */
+export const SalesByClientTopItemSchema = z.object({
+    name: z.string(),
+    amount: z.number(),
+});