@floristcloud/api-lib 1.2.114 → 1.2.116

package/build/commands/cash-flow-item/create-cash-flow-item.command.js

@@ -6,6 +6,7 @@ const schemas_1 = require("../../schemas");
 const CreateCashFlowItemRequestSchema = zod_1.z.object({
     name: zod_1.z.string().trim().min(1).max(255),
     sortOrder: zod_1.z.coerce.number().int().optional(),
+    excludeFromReports: zod_1.z.boolean().optional(),
 });
 const CreateCashFlowItemResponseSchema = zod_1.z.object({
     message: zod_1.z.string().optional(),

package/build/commands/cash-flow-item/update-cash-flow-item.command.js

@@ -8,6 +8,7 @@ const UpdateCashFlowItemRequestSchema = zod_1.z.object({
     name: zod_1.z.string().trim().min(1).max(255).optional(),
     status: zod_1.z.nativeEnum(cash_flow_item_status_enum_1.CashFlowItemStatusEnum).optional(),
     sortOrder: zod_1.z.coerce.number().int().optional(),
+    excludeFromReports: zod_1.z.boolean().optional(),
 });
 const UpdateCashFlowItemResponseSchema = zod_1.z.object({
     message: zod_1.z.string().optional(),

package/build/commands/report/get-cash-flow.query.js

@@ -32,7 +32,14 @@ const CashFlowItemRowSchema = zod_1.z.object({
     cashFlowItemName: zod_1.z.string().nullable(),
     income: money_schema_1.MoneySchema,
     expense: money_schema_1.MoneySchema,
+    // Часть `expense`, которая является расходом бизнеса: без выплат клиентам и возвратов
+    // предоплат — они двигают баланс клиента, а не прибыль. Для большинства статей совпадает
+    // с `expense`. Флаг статьи здесь НЕ применён: строка со своей суммой видна всегда, а
+    // складывать её или нет — решает `excludeFromReports`.
+    operatingExpense: money_schema_1.MoneySchema,
     transactionCount: zod_1.z.number(),
+    // Копия флага статьи. У строки "Без статьи" всегда false — такие платежи учитываются.
+    excludeFromReports: zod_1.z.boolean(),
 });
 const CashFlowMonthRowSchema = CashFlowItemRowSchema.extend({
     month: zod_1.z.string(),
@@ -48,6 +55,13 @@ const GetCashFlowResponseSchema = zod_1.z.object({
             // Сальдо (`income - expense`) — знаковая величина, минус здесь легален,
             // поэтому ограничения на знак нет и быть не должно.
             total: money_schema_1.MoneySchema,
+            // Расход, который вычитается из прибыли на странице отчётов: сумма `operatingExpense`
+            // по строкам с `excludeFromReports = false`, включая строку "Без статьи".
+            expenseForReports: money_schema_1.MoneySchema,
+            // Часть `expenseForReports` без проставленной статьи — величина "из них", а не слагаемое.
+            expenseWithoutItem: money_schema_1.MoneySchema,
+            // Сколько денег отсекли флагом статьи. Для сноски "мимо отчёта прошло X".
+            excludedExpense: money_schema_1.MoneySchema,
         }),
     }),
 });

package/build/commands/report/get-write-off-summary.query.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GetWriteOffSummaryContractQuery = void 0;
+const zod_1 = require("zod");
+const date_helper_1 = require("../../helpers/date.helper");
+const money_schema_1 = require("../../schemas/money.schema");
+const write_off_report_date_basis_enum_1 = require("../../enum/write-off-report-date-basis.enum");
+const report_constant_1 = require("../../constant/report.constant");
+const GetWriteOffSummaryRequestSchema = zod_1.z
+    .object({
+    startDate: zod_1.z.coerce.date(),
+    endDate: zod_1.z.coerce.date(),
+    dateBasis: zod_1.z.nativeEnum(write_off_report_date_basis_enum_1.WriteOffReportDateBasisEnum).default(write_off_report_date_basis_enum_1.WriteOffReportDateBasisEnum.WRITE_OFF_DATE),
+    // Тот же формат, что в ReportOrderFilterSchema: CSV или повтор параметра. Применяется
+    // только к разрезу по клиентам — у складских списаний клиента нет.
+    excludeClientUUID: zod_1.z
+        .union([zod_1.z.string(), zod_1.z.array(zod_1.z.string())])
+        .transform(value => (Array.isArray(value) ? value : value.split(',')).map(item => item.trim()).filter(Boolean))
+        .pipe(zod_1.z.array(zod_1.z.string().uuid()).max(report_constant_1.REPORT_EXCLUDE_CLIENT_LIMIT))
+        .optional(),
+    clientLimit: zod_1.z.coerce
+        .number()
+        .int()
+        .positive()
+        .max(report_constant_1.REPORT_WRITE_OFF_CLIENT_LIMIT_MAX)
+        .default(report_constant_1.REPORT_WRITE_OFF_CLIENT_LIMIT_DEFAULT),
+})
+    .refine(value => (0, date_helper_1.dateRangeCheck)(value.startDate, value.endDate), {
+    message: 'validation.dateRange',
+    path: ['endDate', 'startDate'],
+})
+    .refine(value => (0, date_helper_1.isStatementPeriodWithinLimit)(value.startDate, value.endDate), {
+    message: 'validation.reportPeriodMax',
+    path: ['endDate', 'startDate'],
+});
+const WriteOffSummaryReasonRowSchema = zod_1.z.object({
+    // Свободный текст из справочника причин, схлопнут только по краевым пробелам (TRIM).
+    // Регистр не нормализуем: «Брак» и «брак» останутся разными строками.
+    reason: zod_1.z.string(),
+    units: zod_1.z.number(),
+    cost: money_schema_1.MoneySchema,
+});
+const WriteOffSummaryClientRowSchema = zod_1.z.object({
+    clientUUID: zod_1.z.string(),
+    clientName: zod_1.z.string(),
+    orderCount: zod_1.z.number(),
+    units: zod_1.z.number(),
+    cost: money_schema_1.MoneySchema,
+    orderAmount: money_schema_1.MoneySchema,
+});
+const GetWriteOffSummaryResponseSchema = zod_1.z.object({
+    message: zod_1.z.string().optional(),
+    data: zod_1.z.object({
+        // totals = warehouse + byClient, считается по всем строкам — усечение `clientLimit`
+        // на итоги не влияет.
+        totals: zod_1.z.object({
+            units: zod_1.z.number(),
+            cost: money_schema_1.MoneySchema,
+        }),
+        // Списания без заказа: до этого отчёта они не попадали ни в одну сводку.
+        warehouse: zod_1.z.object({
+            units: zod_1.z.number(),
+            cost: money_schema_1.MoneySchema,
+            byReason: WriteOffSummaryReasonRowSchema.array(),
+        }),
+        // Списания по заказу: клиенту они уже вернулись на баланс, то есть это выручка,
+        // которой по факту не было.
+        byClient: zod_1.z.object({
+            units: zod_1.z.number(),
+            cost: money_schema_1.MoneySchema,
+            orderAmount: money_schema_1.MoneySchema,
+            rows: WriteOffSummaryClientRowSchema.array(),
+            // Сколько клиентов всего — чтобы отличить усечённый ответ от полного.
+            rowsTotal: zod_1.z.number(),
+        }),
+    }),
+});
+var GetWriteOffSummaryContractQuery;
+(function (GetWriteOffSummaryContractQuery) {
+    GetWriteOffSummaryContractQuery.RequestSchema = GetWriteOffSummaryRequestSchema;
+    GetWriteOffSummaryContractQuery.ResponseSchema = GetWriteOffSummaryResponseSchema;
+})(GetWriteOffSummaryContractQuery || (exports.GetWriteOffSummaryContractQuery = GetWriteOffSummaryContractQuery = {}));

package/build/commands/report/index.js

@@ -28,6 +28,7 @@ __exportStar(require("./export-client-statement.query"), exports);
 __exportStar(require("./get-report-by-client-weeks.query"), exports);
 __exportStar(require("./get-daily-orders-summary.query"), exports);
 __exportStar(require("./get-cash-flow.query"), exports);
+__exportStar(require("./get-write-off-summary.query"), exports);
 __exportStar(require("./get-inventory-stock.query"), exports);
 __exportStar(require("./get-inventory-turnover.query"), exports);
 __exportStar(require("./get-sales-by-client.query"), exports);

package/build/constant/error.js

@@ -1138,6 +1138,7 @@ exports.ERRORS = {
     REPORT_FETCH_FAILED: { code: 'REP001', message: 'Failed to fetch report', httpCode: 500 },
     REPORT_EXPORT_FAILED: { code: 'REP002', message: 'Failed to export report', httpCode: 500 },
     REPORT_NO_DATA: { code: 'REP003', message: 'No data available for the selected period', httpCode: 404 },
+    WRITE_OFF_SUMMARY_REPORT_FAILED: { code: 'REP004', message: 'Failed to build write-off summary report', httpCode: 500 },
     STATEMENT_PERIOD_TOO_LONG: { code: 'REP004', message: 'Statement period must not exceed 1 year', httpCode: 400 },
     // PAYMENT INVOICE
     PAYMENT_INVOICE_CREATE_FAILED: { code: 'PINV001', message: 'Failed to create payment invoice', httpCode: 500 },

package/build/constant/report.constant.js

@@ -1,9 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.REPORT_EXCLUDE_CLIENT_LIMIT = void 0;
+exports.REPORT_WRITE_OFF_CLIENT_LIMIT_MAX = exports.REPORT_WRITE_OFF_CLIENT_LIMIT_DEFAULT = exports.REPORT_EXCLUDE_CLIENT_LIMIT = void 0;
 /**
  * Потолок списка исключаемых из отчёта клиентов. Список едет в query-строке и дальше в SQL
  * как `= ANY($n::text[])`, поэтому ограничение защищает и от переполнения URL, и от запроса
  * с массивом в тысячи элементов.
  */
 exports.REPORT_EXCLUDE_CLIENT_LIMIT = 500;
+/**
+ * Сколько клиентов отдаётся в разрезе списаний по умолчанию и максимум. Итоги считаются по всем
+ * строкам независимо от лимита, поэтому усечение влияет только на список; отличить усечённый
+ * ответ от полного позволяет `rowsTotal`.
+ */
+exports.REPORT_WRITE_OFF_CLIENT_LIMIT_DEFAULT = 50;
+exports.REPORT_WRITE_OFF_CLIENT_LIMIT_MAX = 500;

package/build/enum/index.js

@@ -116,3 +116,4 @@ __exportStar(require("./payment-invoice-status.enum"), exports);
 __exportStar(require("./order-by.enum"), exports);
 __exportStar(require("./report-sort-by.enum"), exports);
 __exportStar(require("./report-order-date-basis.enum"), exports);
+__exportStar(require("./write-off-report-date-basis.enum"), exports);

package/build/enum/write-off-report-date-basis.enum.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WriteOffReportDateBasisEnum = void 0;
+/**
+ * По какой дате списание попадает в период отчёта.
+ *
+ * `WRITE_OFF_DATE` — дата самого списания. На ней живёт блок списаний вкладки «По продажам»:
+ * выручка там считается по дате заказа, поэтому списание, оформленное в июле по июньскому
+ * заказу, уменьшит операционную прибыль июля. Это осознанное допущение, оно подписано в UI.
+ *
+ * `CONSIGNMENT_DELIVERY_DATE` — дата поставки партии. На ней построен `/report/profit`, поэтому
+ * на этой оси итоги сходятся с его строками «Всего списано» и «Списано по заказам».
+ */
+var WriteOffReportDateBasisEnum;
+(function (WriteOffReportDateBasisEnum) {
+    WriteOffReportDateBasisEnum["WRITE_OFF_DATE"] = "WRITE_OFF_DATE";
+    WriteOffReportDateBasisEnum["CONSIGNMENT_DELIVERY_DATE"] = "CONSIGNMENT_DELIVERY_DATE";
+})(WriteOffReportDateBasisEnum || (exports.WriteOffReportDateBasisEnum = WriteOffReportDateBasisEnum = {}));

package/build/schemas/cash-flow-item/cash-flow-item.schema.js

@@ -9,6 +9,9 @@ exports.CashFlowItemSchema = zod_1.z.object({
     name: zod_1.z.string(),
     status: zod_1.z.nativeEnum(cash_flow_item_status_enum_1.CashFlowItemStatusEnum),
     sortOrder: zod_1.z.number(),
+    // Статья не участвует в расчёте прибыли: перевод между кассами, оплата поставщику (уже сидит
+    // в себестоимости), выплата учредителю. На отчёт ДДС не влияет — там остаются все обороты.
+    excludeFromReports: zod_1.z.boolean(),
     createdAt: zod_1.z.date(),
     updatedAt: zod_1.z.date(),
 });

package/commands/cash-flow-item/create-cash-flow-item.command.ts

@@ -4,6 +4,7 @@ import { CashFlowItemSchema } from '../../schemas';
 const CreateCashFlowItemRequestSchema = z.object({
     name: z.string().trim().min(1).max(255),
     sortOrder: z.coerce.number().int().optional(),
+    excludeFromReports: z.boolean().optional(),
 });
 
 const CreateCashFlowItemResponseSchema = z.object({

package/commands/cash-flow-item/update-cash-flow-item.command.ts

@@ -6,6 +6,7 @@ const UpdateCashFlowItemRequestSchema = z.object({
     name: z.string().trim().min(1).max(255).optional(),
     status: z.nativeEnum(CashFlowItemStatusEnum).optional(),
     sortOrder: z.coerce.number().int().optional(),
+    excludeFromReports: z.boolean().optional(),
 });
 
 const UpdateCashFlowItemResponseSchema = z.object({

package/commands/report/get-cash-flow.query.ts

@@ -31,7 +31,14 @@ const CashFlowItemRowSchema = z.object({
     cashFlowItemName: z.string().nullable(),
     income: MoneySchema,
     expense: MoneySchema,
+    // Часть `expense`, которая является расходом бизнеса: без выплат клиентам и возвратов
+    // предоплат — они двигают баланс клиента, а не прибыль. Для большинства статей совпадает
+    // с `expense`. Флаг статьи здесь НЕ применён: строка со своей суммой видна всегда, а
+    // складывать её или нет — решает `excludeFromReports`.
+    operatingExpense: MoneySchema,
     transactionCount: z.number(),
+    // Копия флага статьи. У строки "Без статьи" всегда false — такие платежи учитываются.
+    excludeFromReports: z.boolean(),
 });
 
 const CashFlowMonthRowSchema = CashFlowItemRowSchema.extend({
@@ -49,6 +56,13 @@ const GetCashFlowResponseSchema = z.object({
             // Сальдо (`income - expense`) — знаковая величина, минус здесь легален,
             // поэтому ограничения на знак нет и быть не должно.
             total: MoneySchema,
+            // Расход, который вычитается из прибыли на странице отчётов: сумма `operatingExpense`
+            // по строкам с `excludeFromReports = false`, включая строку "Без статьи".
+            expenseForReports: MoneySchema,
+            // Часть `expenseForReports` без проставленной статьи — величина "из них", а не слагаемое.
+            expenseWithoutItem: MoneySchema,
+            // Сколько денег отсекли флагом статьи. Для сноски "мимо отчёта прошло X".
+            excludedExpense: MoneySchema,
         }),
     }),
 });

package/commands/report/get-write-off-summary.query.ts

@@ -0,0 +1,90 @@
+import { z } from 'zod';
+import { dateRangeCheck, isStatementPeriodWithinLimit } from '../../helpers/date.helper';
+import { MoneySchema } from '../../schemas/money.schema';
+import { WriteOffReportDateBasisEnum } from '../../enum/write-off-report-date-basis.enum';
+import {
+    REPORT_EXCLUDE_CLIENT_LIMIT,
+    REPORT_WRITE_OFF_CLIENT_LIMIT_DEFAULT,
+    REPORT_WRITE_OFF_CLIENT_LIMIT_MAX,
+} from '../../constant/report.constant';
+
+const GetWriteOffSummaryRequestSchema = z
+    .object({
+        startDate: z.coerce.date(),
+        endDate: z.coerce.date(),
+        dateBasis: z.nativeEnum(WriteOffReportDateBasisEnum).default(WriteOffReportDateBasisEnum.WRITE_OFF_DATE),
+        // Тот же формат, что в ReportOrderFilterSchema: CSV или повтор параметра. Применяется
+        // только к разрезу по клиентам — у складских списаний клиента нет.
+        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(),
+        clientLimit: z.coerce
+            .number()
+            .int()
+            .positive()
+            .max(REPORT_WRITE_OFF_CLIENT_LIMIT_MAX)
+            .default(REPORT_WRITE_OFF_CLIENT_LIMIT_DEFAULT),
+    })
+    .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'],
+    });
+
+const WriteOffSummaryReasonRowSchema = z.object({
+    // Свободный текст из справочника причин, схлопнут только по краевым пробелам (TRIM).
+    // Регистр не нормализуем: «Брак» и «брак» останутся разными строками.
+    reason: z.string(),
+    units: z.number(),
+    cost: MoneySchema,
+});
+
+const WriteOffSummaryClientRowSchema = z.object({
+    clientUUID: z.string(),
+    clientName: z.string(),
+    orderCount: z.number(),
+    units: z.number(),
+    cost: MoneySchema,
+    orderAmount: MoneySchema,
+});
+
+const GetWriteOffSummaryResponseSchema = z.object({
+    message: z.string().optional(),
+    data: z.object({
+        // totals = warehouse + byClient, считается по всем строкам — усечение `clientLimit`
+        // на итоги не влияет.
+        totals: z.object({
+            units: z.number(),
+            cost: MoneySchema,
+        }),
+        // Списания без заказа: до этого отчёта они не попадали ни в одну сводку.
+        warehouse: z.object({
+            units: z.number(),
+            cost: MoneySchema,
+            byReason: WriteOffSummaryReasonRowSchema.array(),
+        }),
+        // Списания по заказу: клиенту они уже вернулись на баланс, то есть это выручка,
+        // которой по факту не было.
+        byClient: z.object({
+            units: z.number(),
+            cost: MoneySchema,
+            orderAmount: MoneySchema,
+            rows: WriteOffSummaryClientRowSchema.array(),
+            // Сколько клиентов всего — чтобы отличить усечённый ответ от полного.
+            rowsTotal: z.number(),
+        }),
+    }),
+});
+
+export namespace GetWriteOffSummaryContractQuery {
+    export const RequestSchema = GetWriteOffSummaryRequestSchema;
+    export type Request = z.infer<typeof RequestSchema>;
+
+    export const ResponseSchema = GetWriteOffSummaryResponseSchema;
+    export type Response = z.infer<typeof ResponseSchema>;
+}

package/commands/report/index.ts

@@ -12,6 +12,7 @@ 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-write-off-summary.query';
 export * from './get-inventory-stock.query';
 export * from './get-inventory-turnover.query';
 export * from './get-sales-by-client.query';

package/constant/error.ts

@@ -1185,6 +1185,7 @@ export const ERRORS = {
     REPORT_FETCH_FAILED: { code: 'REP001', message: 'Failed to fetch report', httpCode: 500 },
     REPORT_EXPORT_FAILED: { code: 'REP002', message: 'Failed to export report', httpCode: 500 },
     REPORT_NO_DATA: { code: 'REP003', message: 'No data available for the selected period', httpCode: 404 },
+    WRITE_OFF_SUMMARY_REPORT_FAILED: { code: 'REP004', message: 'Failed to build write-off summary report', httpCode: 500 },
     STATEMENT_PERIOD_TOO_LONG: { code: 'REP004', message: 'Statement period must not exceed 1 year', httpCode: 400 },
 
     // PAYMENT INVOICE

package/constant/report.constant.ts

@@ -4,3 +4,12 @@
  * с массивом в тысячи элементов.
  */
 export const REPORT_EXCLUDE_CLIENT_LIMIT = 500;
+
+/**
+ * Сколько клиентов отдаётся в разрезе списаний по умолчанию и максимум. Итоги считаются по всем
+ * строкам независимо от лимита, поэтому усечение влияет только на список; отличить усечённый
+ * ответ от полного позволяет `rowsTotal`.
+ */
+export const REPORT_WRITE_OFF_CLIENT_LIMIT_DEFAULT = 50;
+
+export const REPORT_WRITE_OFF_CLIENT_LIMIT_MAX = 500;

package/enum/index.ts

@@ -100,3 +100,4 @@ export * from './payment-invoice-status.enum';
 export * from './order-by.enum';
 export * from './report-sort-by.enum';
 export * from './report-order-date-basis.enum';
+export * from './write-off-report-date-basis.enum';

package/enum/write-off-report-date-basis.enum.ts

@@ -0,0 +1,14 @@
+/**
+ * По какой дате списание попадает в период отчёта.
+ *
+ * `WRITE_OFF_DATE` — дата самого списания. На ней живёт блок списаний вкладки «По продажам»:
+ * выручка там считается по дате заказа, поэтому списание, оформленное в июле по июньскому
+ * заказу, уменьшит операционную прибыль июля. Это осознанное допущение, оно подписано в UI.
+ *
+ * `CONSIGNMENT_DELIVERY_DATE` — дата поставки партии. На ней построен `/report/profit`, поэтому
+ * на этой оси итоги сходятся с его строками «Всего списано» и «Списано по заказам».
+ */
+export enum WriteOffReportDateBasisEnum {
+    WRITE_OFF_DATE = 'WRITE_OFF_DATE',
+    CONSIGNMENT_DELIVERY_DATE = 'CONSIGNMENT_DELIVERY_DATE',
+}

package/package.json

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

package/schemas/cash-flow-item/cash-flow-item.schema.ts

@@ -7,6 +7,9 @@ export const CashFlowItemSchema = z.object({
     name: z.string(),
     status: z.nativeEnum(CashFlowItemStatusEnum),
     sortOrder: z.number(),
+    // Статья не участвует в расчёте прибыли: перевод между кассами, оплата поставщику (уже сидит
+    // в себестоимости), выплата учредителю. На отчёт ДДС не влияет — там остаются все обороты.
+    excludeFromReports: z.boolean(),
     createdAt: z.date(),
     updatedAt: z.date(),
 });