hh-contracts 0.0.85 → 0.0.86

package/AGENTS.md

@@ -1,66 +1,71 @@
-# agents.md — Каркас для Codex/LLM-агентов
-
-## 1. Введение
-
-Этот документ описывает агентов (AI-ассистентов), их роли, правила и форматы работы.  
-Цель — стандартизировать использование Codex/LLM внутри проекта, сделать промптинг воспроизводимым и согласованным.
-
----
-
-## 2. Таксономия агентов
-
-Определены следующие агенты:
-
-- **Contracts Agent** — ведёт Zod-схемы, DTO, enums в `hh-contracts`.
-
----
-
-## 3. Общие принципы
-
-1. **Single Source of Truth**: все типы и схемы берутся из `hh-contracts`.
-2. **Чёткие форматы**: каждый агент возвращает только согласованный формат (TSX, SQL, JSON и т.д.).
-3. **ASSUMPTIONS/GAPS**: если данных не хватает, агент явно указывает предположения и пробелы.
-4. **Пошаговость**: сложные задачи делятся на дизайн → реализация → тесты.
-5. **Безопасность**: никаких секретов, токены только через `process.env` и Zod-валидацию.
-
----
-
-## 4. Описание агентов
-
-### Contracts Agent
-
-**Назначение**: ведёт контракты (Zod v4 схемы/DTO).  
-**Вход**: описание сущностей, версия `hh-contracts`.  
-**Выход**: TypeScript-файл со схемами, без README.  
-**Стиль**: TS 5.x strict, без `any`.  
-**Ограничения**: не использовать class-validator.  
-**Инструменты**: zod.  
-**Few-shot**:
-
-```
-Запрос: Добавь сущность Permission (id, name, action, subject, conditions?)
-Ответ: TypeScript-файл с Zod-схемой и типом.
-```
-
----
-
-## 5. Чек-лист качества (для каждого ответа)
-
-- [ ] Соответствует контрактам.
-- [ ] Нет магических значений.
-- [ ] Типизировано строго.
-- [ ] Есть тесты или примеры.
-- [ ] Код ≤ 400 строк.
-
----
-
-## 6. Версионирование
-
-- Изменения фиксируются внизу файла (Changelog).
-- MAJOR — при смене форматов, MINOR — при добавлении агентов.
-
----
-
-## Changelog
-
+AGENTS.md — инструкции для Codex/LLM-агентов
+
+## 1. Контекст проекта
+
+`hh-contracts` — типизированное ядро контрактов для всей платформы управления отелями. Репозиторий публикуется как npm‑пакет и содержит только исходные типы/схемы (`*.ts`) и скомпилированный артефакт в `build/`. Любые изменения в доменных сервисах должны начинаться здесь.
+
+### Основные каталоги
+
+- `common/` — общие константы, вспомогательные схемы и утилиты. Использовать их при любой возможности вместо дублирования.
+- `*/contracts/` — файловая зона для REST/gRPC/WebSocket контрактов конкретного домена (roles, permissions, tenants и т. д.).
+- `*/index.ts` — публичные реэкспорты. Добавляя новый файл, обязательно обновляйте соответствующий `index.ts`.
+- `build/` — артефакты TypeScript‑компиляции. **Не редактировать вручную.**
+
+## 2. Роли агентов
+
+- **Contracts Agent** — отвечает за модели и схемы. Любая доработка (добавление сущности, изменение поля, экспорт типов) выполняется через него.
+- Если создаётся новый тип агента, описать его в этом файле и зафиксировать правила в разделе 5.
+
+## 3. Правила разработки
+
+1. **Single Source of Truth**. Типы, перечисления, схемы валидируются и объявляются здесь. Копирование структур из других сервисов запрещено.
+2. **Zod v4.** Использовать только `zod@^4`. Схемы пишем декларативно, избегая `any`. Для произвольных словарей применять `z.record` с ограничениями.
+3. **Строгая типизация.** `tsconfig.json` находится в strict‑режиме. Новые файлы не должны снижать строгие настройки.
+4. **Именование:**
+   - Файлы схем — `*.schema.ts` или `*.contract.ts` в зависимости от назначения.
+   - Типы, полученные из схем, объявлять через `export type TSome = z.infer<typeof SomeSchema>;`.
+   - Enum‑образные наборы значений хранить в `common/constants`, экспортировать через `as const` и соответствующий `z.enum`.
+5. **Повторное использование:** сначала ищите подходящую схему в `common/models` и `common/constants`. При необходимости расширяйте через `.extend(...)` или `.merge(...)`.
+6. **Версионирование:** после любых изменений обновляйте `package.json` вручную только по согласованию. Как минимум фиксируйте запись в Changelog (см. раздел 6).
+7. **Документация контрактов:** не нужно составлять документацию контрактов.
+8. **Переводы:** схемы переводов для сущностей хранятся рядом со схемами сущностей. `translate/` — эндпоинт для переводов. умеет работать как с отдельными строками, так и с полными наборами переводов для сущности. в случшае добавления сущности с переводами нужно обновить TranslateObjectContract - `translate/contracts/translate-object.contract.ts`
+9. **Не оставляйте TODO** без описания задачи. Используйте формат `// TODO(#issue-id): описание`.
+
+## 4. Рабочий процесс для задач
+
+1. **Анализ**
+   - Изучите существующие схемы домена.
+   - Определите, какие общие константы/типажи можно переиспользовать.
+2. **Дизайн**
+   - При сложных задачах сначала предложите структуру (таблица полей, связи, вариативность).
+   - Согласуйте новые enum/константы и ключи переводов.
+3. **Реализация**
+   - Создайте/обновите схемы, типы, константы и индексы.
+   - Проверьте, что экспорты доступны из корня пакета (`index.ts`).
+4. **Проверка**
+   - Выполните `npm run build` перед коммитом.
+   - Убедитесь, что сгенерированный `build/` совпадает с ожиданиями (git diff должен показывать изменения только при добавлении новых файлов/типов).
+5. **Ответ**
+   - В финальном сообщении используйте структуру Summary + Testing.
+   - Каждое тестовое действие сопровождайте командой и результатом.
+
+## 5. Требования к коду
+
+- Отсутствие магических строк: используйте константы.
+- Для дат и меток времени используйте `TimestampSchema`.
+- Обязательные поля явно помечать `z.string()` и т. п.; опциональные — через `.optional()` или `z.nullable()`.
+- Для массивов всегда задавайте схему элементов (`z.array(SomeSchema)`).
+- Если поле может принимать несколько форматов, используйте `z.union` с понятными вариантами.
+- Обязательный минимум тестового покрытия — пример использования схемы в виде объектной литералы или демо‑валидации в комментарии.
+
+## 6. Чек-лист перед PR
+
+- [ ] Все новые сущности экспортируются из соответствующего `index.ts`.
+- [ ] Нет изменений в `build/` (если только намеренно не обновляли после `npm run build`).
+- [ ] Запущен `npm run build` без ошибок.
+- [ ] Changelog дополнен.
+
+## 7. Changelog
+
+- 1.1 — актуализированы инструкции, добавлены требования к структуре ответов и чек-лист перед PR.
 - 1.0 — первоначальная версия каркаса.

package/README.md

@@ -1 +1,12 @@
-# hh-contracts
+## Обзор системы
+
+Система управления отелем состоит из 8 основных компонентов (не монорепо):
+
+1. **Контракты** - типизированные API контракты - ts package - zod
+2. **Общий API** - централизованный backend - nestjs CQRS DDD (mysaas.com/api)
+3. **Клиент на локальном сервере отеля** - клиент(подключется к api websocket или брокер собщений у устанавливается на локальный сервер в гостинице) позволяющий интегрироваться с сервером гостиничной программы отеля и получать из нее данные - go или nestjs или C#
+4. **Админка** - административная панель - react - chakra-ui (admin.mysaas.com)
+5. **Приложение персонала** - управление услугами, тарифами, администрирование отеля - react - chakra-ui (app.mysaas.com)
+6. **Сайт отеля и приложение сервисов для гостей** - сайты отелей (hotel1.mysaas.com, hotel2.mysaas.com  если у телей есть свой домены то приложение открывается по адресу - hotel1.com hotel2.com) и сервисы(просмотр и заказ услуг) (services.hotel1.mysaas.com, services.hotel2.mysaas.com  если у телей есть свой домены то приложение открывается по адресу - services.hotel1.com services.hotel2.com) - nextjs - chakra-ui сайты отелей
+7. **Лэндинг** - сайт самого сервиса - nextjs - chakra-ui
+8. **Digital Signage (экраны/плеер)** — отдельный PWA/SPA‑клиент для экранов (ресепшн, лобби, лифты, конференц‑залы и т. д.) с оффлайн‑кэшем и режимом киоска; управление контентом через **admin** и быстрые действия через **app**. Домены: player.mysaas.com, screens.hotel1.com.

package/build/translate/contracts/index.js

@@ -14,4 +14,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./batch-translate.contract"), exports);
+__exportStar(require("./translate-text.contract"), exports);
+__exportStar(require("./translate-object.contract"), exports);

package/build/translate/contracts/translate-object.contract.js

@@ -0,0 +1,65 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TranslateObjectContract = void 0;
+const z = __importStar(require("zod"));
+const common_1 = require("../../common");
+const translate_api_1 = require("../translate.api");
+const permissions_1 = require("../../permissions");
+const roles_1 = require("../../roles");
+const translate_schemas_1 = require("../translate.schemas");
+const makeReqVariant = (entity, schema) => translate_schemas_1.BaseTranslateSchema.extend({ entity: z.literal(entity), object: schema });
+const makeResVariant = (entity, schema) => z.object({
+    entity: z.literal(entity),
+    translations: z.partialRecord(common_1.LanguageKeysSchema, schema),
+});
+const TranslateObjectRequestVariants = [
+    makeReqVariant(common_1.ENTITIES.permissions, permissions_1.PermissionTranslationsSchema),
+    makeReqVariant(common_1.ENTITIES.roles, roles_1.RoleTranslationsSchema),
+];
+const TranslateObjectResponseVariants = [
+    makeResVariant(common_1.ENTITIES.permissions, permissions_1.PermissionTranslationsSchema),
+    makeResVariant(common_1.ENTITIES.roles, roles_1.RoleTranslationsSchema),
+];
+const TranslateObjectContractRequestSchema = z.discriminatedUnion('entity', TranslateObjectRequestVariants);
+const TranslateObjectContractResponseSchema = z.discriminatedUnion('entity', TranslateObjectResponseVariants);
+var TranslateObjectContract;
+(function (TranslateObjectContract) {
+    TranslateObjectContract.getUrl = translate_api_1.TRANSLATE_API.object;
+    TranslateObjectContract.endpoint = translate_api_1.TRANSLATE_CONTROLLER.endpoints.object;
+    TranslateObjectContract.httpMethod = common_1.HTTP_METHODS.post;
+    TranslateObjectContract.RequestSchema = TranslateObjectContractRequestSchema;
+    TranslateObjectContract.ResponseSchema = TranslateObjectContractResponseSchema;
+})(TranslateObjectContract || (exports.TranslateObjectContract = TranslateObjectContract = {}));

package/build/translate/contracts/{batch-translate.contract.js → translate-text.contract.js}

@@ -33,26 +33,22 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BatchTranslateContract = void 0;
+exports.TranslateTextContract = void 0;
 const z = __importStar(require("zod"));
 const common_1 = require("../../common");
 const translate_api_1 = require("../translate.api");
-const BatchTranslateContractRequestSchema = z.object({
+const translate_schemas_1 = require("../translate.schemas");
+const TranslateTextContractRequestSchema = translate_schemas_1.BaseTranslateSchema.extend({
     text: z.string().min(1),
-    fromLang: common_1.LanguageKeysSchema,
-    toLangs: z.array(common_1.LanguageKeysSchema).min(1),
 });
-const TranslationsSchema = z
-    .object(Object.fromEntries(common_1.LANGUAGE_KEYS.map(l => [l, z.string().min(1).nullable()])))
-    .partial();
-const BatchTranslateContractResponseSchema = z.object({
-    translations: TranslationsSchema,
+const TranslateTextContractResponseSchema = z.object({
+    translations: z.partialRecord(common_1.LanguageKeysSchema, z.string().min(1).nullable()),
 });
-var BatchTranslateContract;
-(function (BatchTranslateContract) {
-    BatchTranslateContract.getUrl = translate_api_1.TRANSLATE_API.batch;
-    BatchTranslateContract.endpoint = translate_api_1.TRANSLATE_CONTROLLER.endpoints.batch;
-    BatchTranslateContract.httpMethod = common_1.HTTP_METHODS.post;
-    BatchTranslateContract.RequestSchema = BatchTranslateContractRequestSchema;
-    BatchTranslateContract.ResponseSchema = BatchTranslateContractResponseSchema;
-})(BatchTranslateContract || (exports.BatchTranslateContract = BatchTranslateContract = {}));
+var TranslateTextContract;
+(function (TranslateTextContract) {
+    TranslateTextContract.getUrl = translate_api_1.TRANSLATE_API.batch;
+    TranslateTextContract.endpoint = translate_api_1.TRANSLATE_CONTROLLER.endpoints.batch;
+    TranslateTextContract.httpMethod = common_1.HTTP_METHODS.post;
+    TranslateTextContract.RequestSchema = TranslateTextContractRequestSchema;
+    TranslateTextContract.ResponseSchema = TranslateTextContractResponseSchema;
+})(TranslateTextContract || (exports.TranslateTextContract = TranslateTextContract = {}));

package/build/translate/translate.api.js

@@ -5,7 +5,8 @@ const utils_1 = require("../common/utils");
 exports.TRANSLATE_CONTROLLER = {
     prefix: 'translate',
     endpoints: {
-        batch: '',
+        batch: 'text',
+        object: 'object',
     },
 };
 exports.TRANSLATE_API = (0, utils_1.createApi)(exports.TRANSLATE_CONTROLLER);

package/build/translate/translate.schemas.js

@@ -0,0 +1,42 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseTranslateSchema = void 0;
+const z = __importStar(require("zod"));
+const common_1 = require("../common");
+exports.BaseTranslateSchema = z.object({
+    fromLang: common_1.LanguageKeysSchema,
+    toLangs: z.array(common_1.LanguageKeysSchema).min(1),
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hh-contracts",
-  "version": "0.0.85",
+  "version": "0.0.86",
   "description": "",
   "main": "./build/index.js",
   "scripts": {

package/translate/contracts/index.ts

@@ -1 +1,2 @@
-export * from './batch-translate.contract';
+export * from './translate-text.contract';
+export * from './translate-object.contract';

package/translate/contracts/translate-object.contract.ts

@@ -0,0 +1,52 @@
+import * as z from 'zod';
+import { HTTP_METHODS, LanguageKeysSchema, ENTITIES } from '../../common';
+import { TRANSLATE_API, TRANSLATE_CONTROLLER } from '../translate.api';
+import { PermissionTranslationsSchema } from '../../permissions';
+import { RoleTranslationsSchema } from '../../roles';
+import { BaseTranslateSchema } from '../translate.schemas';
+
+const makeReqVariant = <E extends (typeof ENTITIES)[keyof typeof ENTITIES], S extends z.ZodTypeAny>(
+  entity: E,
+  schema: S,
+) => BaseTranslateSchema.extend({ entity: z.literal(entity), object: schema });
+
+const makeResVariant = <E extends (typeof ENTITIES)[keyof typeof ENTITIES], S extends z.ZodTypeAny>(
+  entity: E,
+  schema: S,
+) =>
+  z.object({
+    entity: z.literal(entity),
+    translations: z.partialRecord(LanguageKeysSchema, schema),
+  });
+
+const TranslateObjectRequestVariants = [
+  makeReqVariant(ENTITIES.permissions, PermissionTranslationsSchema),
+  makeReqVariant(ENTITIES.roles, RoleTranslationsSchema),
+] as const;
+
+const TranslateObjectResponseVariants = [
+  makeResVariant(ENTITIES.permissions, PermissionTranslationsSchema),
+  makeResVariant(ENTITIES.roles, RoleTranslationsSchema),
+] as const;
+
+const TranslateObjectContractRequestSchema = z.discriminatedUnion(
+  'entity',
+  TranslateObjectRequestVariants,
+);
+
+const TranslateObjectContractResponseSchema = z.discriminatedUnion(
+  'entity',
+  TranslateObjectResponseVariants,
+);
+
+export namespace TranslateObjectContract {
+  export const getUrl = TRANSLATE_API.object;
+  export const endpoint = TRANSLATE_CONTROLLER.endpoints.object;
+  export const httpMethod = HTTP_METHODS.post;
+
+  export const RequestSchema = TranslateObjectContractRequestSchema;
+  export type TRequest = z.infer<typeof RequestSchema>;
+
+  export const ResponseSchema = TranslateObjectContractResponseSchema;
+  export type TResponse = z.infer<typeof ResponseSchema>;
+}

package/translate/contracts/translate-text.contract.ts

@@ -0,0 +1,24 @@
+import * as z from 'zod';
+import { HTTP_METHODS, LanguageKeysSchema } from '../../common';
+import { TRANSLATE_API, TRANSLATE_CONTROLLER } from '../translate.api';
+import { BaseTranslateSchema } from '../translate.schemas';
+
+const TranslateTextContractRequestSchema = BaseTranslateSchema.extend({
+  text: z.string().min(1),
+});
+
+const TranslateTextContractResponseSchema = z.object({
+  translations: z.partialRecord(LanguageKeysSchema, z.string().min(1).nullable()),
+});
+
+export namespace TranslateTextContract {
+  export const getUrl = TRANSLATE_API.batch;
+  export const endpoint = TRANSLATE_CONTROLLER.endpoints.batch;
+  export const httpMethod = HTTP_METHODS.post;
+
+  export const RequestSchema = TranslateTextContractRequestSchema;
+  export type TRequest = z.infer<typeof RequestSchema>;
+
+  export const ResponseSchema = TranslateTextContractResponseSchema;
+  export type TResponse = z.infer<typeof ResponseSchema>;
+}

package/translate/translate.api.ts

@@ -3,7 +3,8 @@ import { createApi, TController } from '../common/utils';
 export const TRANSLATE_CONTROLLER = {
   prefix: 'translate',
   endpoints: {
-    batch: '',
+    batch: 'text',
+    object: 'object',
   },
 } as const satisfies TController;
 

package/translate/translate.schemas.ts

@@ -0,0 +1,7 @@
+import * as z from 'zod';
+import { LanguageKeysSchema } from '../common';
+
+export const BaseTranslateSchema = z.object({
+  fromLang: LanguageKeysSchema,
+  toLangs: z.array(LanguageKeysSchema).min(1),
+});

package/translate/contracts/batch-translate.contract.ts

@@ -1,29 +0,0 @@
-import * as z from 'zod';
-import { HTTP_METHODS, LanguageKeysSchema, LANGUAGE_KEYS } from '../../common';
-import { TRANSLATE_API, TRANSLATE_CONTROLLER } from '../translate.api';
-
-const BatchTranslateContractRequestSchema = z.object({
-  text: z.string().min(1),
-  fromLang: LanguageKeysSchema,
-  toLangs: z.array(LanguageKeysSchema).min(1),
-});
-
-const TranslationsSchema = z
-  .object(Object.fromEntries(LANGUAGE_KEYS.map(l => [l, z.string().min(1).nullable()])))
-  .partial();
-
-const BatchTranslateContractResponseSchema = z.object({
-  translations: TranslationsSchema,
-});
-
-export namespace BatchTranslateContract {
-  export const getUrl = TRANSLATE_API.batch;
-  export const endpoint = TRANSLATE_CONTROLLER.endpoints.batch;
-  export const httpMethod = HTTP_METHODS.post;
-
-  export const RequestSchema = BatchTranslateContractRequestSchema;
-  export type TRequest = z.infer<typeof RequestSchema>;
-
-  export const ResponseSchema = BatchTranslateContractResponseSchema;
-  export type TResponse = z.infer<typeof ResponseSchema>;
-}