@rt-tools/agent-kit 0.6.0 → 0.8.0

package/assets/patterns/ownership-session-procedure.md

@@ -1,102 +0,0 @@
----
-name: ownership-session-procedure
-kind: pattern
-rule: ownership-session
-description: Паттерн правила ownership-session. Брать, когда процедуре нужна владеющая сущность захода — объявление декоратором, чтение из контекста, отбивка чужой сущности в черновике, контекст в тесте. Не брать для объявления доступа к процедуре — это паттерн permissions-procedure, и не для формы самого класса — это паттерн ts-procedure.
----
-
-# Процедура, которой нужна сущность захода
-
-Паттерн правила `ownership-session`. Что при этом должно быть верно — закон
-`docs/constitution/application/ownership.md`.
-
-## Когда брать
-
-- Процедура работает с записями владеющей сущности и должна знать, в какой она работает.
-- Процедура читает идентификатор сущности из полей запроса — так больше не делают.
-- Пишется тест процедуры, которая сущность захода читает.
-
-## Объявление и чтение
-
-Две строки пишутся вместе: декоратор на классе и чтение из контекста в теле. Перехватчик читает
-сущность только для объявивших, поэтому чтение без декоратора отвечает внутренней ошибкой — и
-отвечает на первом вызове, а не на сборке.
-
-```ts
-@Injectable()
-@ConnectProcedure()
-@RequiresPermission('settings:view')
-@RequiresOwner()
-export class GetSettingsProcedure implements IConnectProcedure<typeof SettingsContract.method.getSettings> {
-    public async handle(
-        _request: GetSettingsRequest,
-        context: HandlerContext
-    ): Promise<MessageInitShape<typeof GetSettingsResponseSchema>> {
-        const settings: IOwnerSettings = await this.#settings.byOwner(ownerOf(context));
-        …
-    }
-}
-```
-
-Запрос при этом не читается вовсе — отсюда `_request`. Поля сущности в контракте нет: номер и
-имя помечены занятыми, а присланный ключ отбивается разбором запроса. Заводить его заново
-нельзя: сущность в запросе называет только тот, кто работает поверх всех сразу.
-
-Декоратор потребности стоит рядом с объявлением доступа, а не вместо него: объявлений доступа у
-процедуры по-прежнему ровно одно, и без него приложение не поднимется.
-
-## Идентификатор, названный в теле запроса
-
-Некоторые запросы несут сущность не отдельным полем, а внутри черновика. Расхождение с
-сущностью захода отбивается, а не выправляется молча:
-
-```ts
-const sessionOwnerId: string = ownerOf(context);
-if (draft.id && draft.id !== sessionOwnerId) {
-    throw new ConnectError('owner does not match the session owner', Code.InvalidArgument);
-}
-```
-
-Пустой идентификатор в черновике законен: он приходит пустым, когда админка сохраняет то, чего
-ещё не загружала.
-
-## Контекст в тесте
-
-Двойника перехватчика заводить не надо — в контекст кладётся готовое значение:
-
-```ts
-function context(ownerId: string): HandlerContext {
-    const values: ContextValues = createContextValues();
-    values.set(kSessionOwner, ownerId);
-
-    return { values } as unknown as HandlerContext;
-}
-```
-
-Тест на то, что присланный идентификатор не читается, пишется отдельным случаем: запрос несёт
-чужую сущность, а спросили у хранилища свою.
-
-```ts
-it('SC-OWN-54 — читает сущность захода и присланный идентификатор не смотрит', async () => {
-    const request: GetSettingsRequest = create(GetSettingsRequestSchema, { ownerId: FOREIGN_OWNER });
-
-    await procedure.handle(request, context(SESSION_OWNER));
-
-    expect(asked).toEqual([SESSION_OWNER]);
-});
-```
-
-## Частые промахи
-
-- Декоратор забыт, а чтение в теле стоит. Сборка и линт молчат, отказ приходит на первом вызове.
-  Ловится тестом процедуры, а не проверками дерева.
-- Декоратор поставлен вместо объявления доступа. Приложение не поднимется: у процедуры обязано
-  быть ровно одно объявление доступа, а потребность в сущности к ним не относится.
-- Сущность прочитана из запроса «на всякий случай, если контекст пуст». Пустой контекст здесь
-  означает забытое объявление, и подстановка прячет его до самого прода.
-- Процедура читает сущность захода у гостя. Вошедшего у гостевых процедур нет, и сущности в
-  контексте у них тоже нет: они берут её у записи, с которой пришли, — у страницы, у разговора
-  по токену, — а когда записи нет вовсе, у единственной сущности хранилища. Второй в хранилище
-  они отвечают отказом по состоянию.
-- Отказ на снятую принадлежность подан как отказ в доступе. Транспорт админки уводит на вход
-  только по коду неаутентифицированного, а на второй код человек остаётся на закрытом разделе.

package/assets/patterns/pricing-quote.md

@@ -1,71 +0,0 @@
----
-name: pricing-quote
-kind: pattern
-rule: pricing
-description: Паттерн правила pricing. Брать при правке расчёта цены, механик скидки, работы с курсом валют и сумм в письмах и документах — где округлять, как выбирается одна скидка, что кладётся в бронь. Не брать для доступа к процедурам цен — это паттерн permissions-procedure.
----
-
-# Расчёт цены
-
-Паттерн правила `pricing`. Что при этом должно быть верно — закон
-`docs/constitution/application/money.md`.
-
-## Когда брать
-
-- Правится расчёт цены или механика скидки.
-- В код заходит сумма в чужой валюте.
-- Сумма попадает в заказ, письмо, документ или сводку.
-
-## Всё считается один раз
-
-Расчёт живёт в `calculateQuote` и отдаёт готовые числа: ночи, подытог, скидку, итог, признак
-минимального срока. Показ, письмо и запись в базу берут одни и те же числа, а не пересчитывают
-их каждый у себя.
-
-```typescript
-const quote: IQuoteResult = calculateQuote({
-    checkIn,
-    checkOut,
-    basePriceThb,
-    defaultMinNights,
-    seasons,
-    lengthDiscounts,
-    promoCode,
-});
-```
-
-## Одна скидка — наибольшая
-
-Механики считаются по отдельности, а выбор между ними один:
-
-```typescript
-const best: IDiscountCandidate | undefined = bestCandidateOf([
-    lengthCandidateOf(nights, input, subtotalThb),
-    promoCandidateOf(input.promoCode, subtotalThb),
-]);
-```
-
-При равных суммах побеждает промокод: владелец выдал его адресно, а скидка за длительность
-досталась бы гостю и без него. Новая механика добавляется третьим кандидатом в тот же вызов, а
-не отдельным вычитанием из итога.
-
-## Чужая валюта — на показ
-
-В заказе лежат сумма в валюте хранения и код валюты, в которой гость смотрел цену. Само число в чужой
-валюте не хранится нигде:
-
-```typescript
-export const SUPPORTED_QUOTE_CURRENCIES: readonly string[] = ['USD', 'RUB', 'EUR', 'CNY'];
-```
-
-Курс тянется по расписанию и кэшируется в хранилище. Курса нет — сумма показывается в валюте хранения без
-пересчёта.
-
-## Частые промахи
-
-- Округление на показе: сумма гостя, сумма письма и сумма в базе разойдутся на единицы.
-- Сложение двух скидок: владелец таких сумм не закладывал, и объяснить гостю итог нечем.
-- Сохранённое число в чужой валюте: оно устареет вместе с курсом.
-- Справочная сумма, подписанная как сумма к оплате, — оплата идёт в валюте хранения.
-- Письмо в валюте, отличной от той, что гость выбирал на сайте: оно читается как другая цена.
-- Дробная часть в сумме: единица хранения целая.

package/assets/rules/ownership-scope.md

@@ -1,66 +0,0 @@
----
-name: ownership-scope
-kind: rule
-law: ownership
-description: Правило под «Закон о владеющей сущности». Брать, когда процедура или экран работает с записью, принадлежащей владеющей сущности — разрешение идентификатора, умолчание при единственной действующей, сводки по всем. Называет обе формы разрешения и коды отказа. Готовый код — в паттерне ownership-scope-resolve. Чем это названо здесь — в implementation.md рядом.
----
-
-# Владеющая сущность — как это устроено здесь
-
-Правило под закон `docs/constitution/application/ownership.md`. Закон говорит, что должно быть
-верно; здесь — каким приёмом это держится. Как владеющая сущность названа в этом дереве и какие
-экраны считаются сводками — в `implementation.md` рядом.
-
-## Как это называется здесь
-
-| В законе                           | Здесь                                                                           |
-| ---------------------------------- | ------------------------------------------------------------------------------- |
-| владеющая сущность                 | запись своего домена; в запросах — поле `<сущность>_id`                         |
-| пустой идентификатор               | пустая строка, а не отсутствующее поле: необязательных скаляров в контракте нет |
-| сводка                             | списки и статистика, отвечающие сразу по всем действующим                       |
-| отказ при двух и более действующих | `Code.InvalidArgument`                                                          |
-| отказ, когда действующих нет вовсе | `Code.FailedPrecondition`                                                       |
-| ненайденный явный идентификатор    | `Code.NotFound`                                                                 |
-
-У списков, переведённых на общую выборку, идентификатор отдельным полем запроса не приходит
-вовсе: это условие отбора в модели фильтра, а прежний номер поля помечен `reserved`.
-
-## Где это лежит
-
-В этом дереве — таблица в `implementation.md` рядом. Пути живут там, а не здесь: правило
-переносится между репозиториями, раскладка — нет, и путь, названный в правиле, врёт в первом
-же дереве, которое держит код иначе.
-
-## Как закон применяется здесь
-
-- **Запись принадлежит владеющей сущности, а не системе.** Общих настроек, действующих сразу
-  на все, нет: заведение второй не меняет поведение первой.
-- **Пустой идентификатор означает единственную действующую.** Пока она одна, клиент вправе её
-  не называть.
-- **При двух и более действующих запрос обязан назвать сущность.** Умолчание перестаёт быть
-  однозначным, и запрос отбивается как неверный.
-- **Названная явно находится, даже если она скрыта.** У скрытой остаются записи, деньги и
-  переписка.
-- **Там, где показана сводка, пустой идентификатор означает все действующие.** Списки и
-  статистика отвечают по всему набору, а не требуют сперва выбрать одну.
-- **Когда действующих нет вовсе, запрос отбивается.** Скрытая вместо отсутствующей действующей
-  не подставляется.
-
-## Паттерны
-
-- `ownership-scope-resolve` — разрешение сущности в процедуре и обе формы умолчания.
-
-## Ловушки
-
-- **Разрешение разложено на две части намеренно:** чистая функция разбирает случай, обёртка
-  ходит в хранилище и переводит случай в отказ. Вторая реализация того же правила однажды уже
-  жила у обработчика статистики соседнего домена и успела разойтись порядком выборки.
-- **Отсутствие действующей сущности и ненайденный явный идентификатор — разные случаи для
-  вызывающего:** первое отвечает `FailedPrecondition`, второе — `NotFound`.
-- Таблица владеющих сущностей читается целиком одним запросом — она маленькая, и выборки ей не
-  нужно.
-- **Выбор сущности живёт в общем сторе, а рисует переключатель тот экран, которому он нужен.**
-  Выбор переживает переход между разделами, но экран без своего переключателя показывает то,
-  что выбрали на другом, — и это читается как чужие числа в своём разделе. Где переключатель
-  стоит, названо в именах дерева; снаружи выбора нет вовсе: пользователь приходит на страницу
-  конкретной сущности.

package/assets/rules/ownership-session.md

@@ -1,124 +0,0 @@
----
-name: ownership-session
-kind: rule
-law: ownership
-description: Правило под «Закон о владеющей сущности». Брать при правке процедуры, которой нужна сущность захода, перехватчика доступа и выборок принадлежности — чем названа сущность захода, откуда она берётся, каким условием отбираются записи и какими кодами отвечают отказы. Готовый код — в паттерне ownership-session-procedure. Не брать для разрешения идентификатора в запросе — это правило ownership-scope.
----
-
-# Владеющая сущность захода — как это устроено здесь
-
-Правило под закон `docs/constitution/application/ownership.md`. Закон говорит, что должно быть
-верно, когда владеющих сущностей больше одной; здесь — как приложение узнаёт, в какой из них
-работает вошедший, и чем держится граница между ними. Разрешение идентификатора, названного в
-запросе, — правило `ownership-scope` под тем же законом.
-
-## Как это называется здесь
-
-| В законе                                       | Здесь                                                                            |
-| ---------------------------------------------- | -------------------------------------------------------------------------------- |
-| владеющая сущность                             | запись своего домена; имя — в `implementation.md` рядом                          |
-| принадлежность человека сущности               | своя запись на пару «человек и сущность»                                         |
-| сущность захода                                | колонка учётной записи; внутри запроса — ключ контекста, читаемый одной функцией |
-| потребность процедуры в сущности захода        | декоратор на её классе, стоящий рядом с объявлением доступа                      |
-| отказ вошедшему, у которого принадлежности нет | тот же код, что на неверный пароль, — вошедшего надо увести на вход              |
-| отказ на чужую сущность, названную в черновике | неверный аргумент                                                                |
-| забытый декоратор                              | внутренняя ошибка — отказ приложения, а не вызывающему                           |
-
-## Где это лежит
-
-В этом дереве — таблица в `implementation.md` рядом. Пути живут там, а не здесь: правило
-переносится между репозиториями, раскладка — нет, и путь, названный в правиле, врёт в первом
-же дереве, которое держит код иначе.
-
-## Как закон применяется здесь
-
-- **Сущность захода приезжает в процедуру контекстом запроса, а не полем запроса.** Ключ и его
-  читатель лежат рядом, как ключ вошедшего и его читатель: вторая копия проверки разошлась бы с
-  первой в коде отказа.
-- **Процедура объявляет потребность декоратором, и чтение без объявления — отказ приложения.**
-  Править такое нечего ни вызывающему, ни владельцу: это забытое объявление, и оно видно
-  отказом, а не работой неизвестно в какой сущности.
-- **Сущность захода приезжает в контекст только процедурам, объявившим потребность.** Читает её
-  перехватчик всё равно — тем же обращением, которым читает права вошедшего, — но без
-  объявления в контекст она не попадает. Потребность стоит рядом с объявлением доступа и счёт
-  объявлений доступа не меняет.
-- **Сущность захода лежит у учётной записи, а не в выданном входе.** Выбор переживает
-  перезагрузку и не зависит от того, что шлёт клиент; выданный вход говорит только о том, кто
-  пришёл.
-- **Принадлежность человека сущности — своя запись, и в одной сущности она одна.** Две
-  принадлежности пришлось бы складывать, а результат сложения запретов и разрешений по двум
-  строкам не прочитать.
-- **Человек, у которого принадлежности нет, не входит и не работает: оба отказа те же, что на
-  неверный пароль.** Принадлежность снимают, пока выданный вход ещё жив, — и тогда отказ
-  приходит уже посреди работы. Транспорт админки на этот код чистит хранилище и уводит на
-  страницу входа.
-- **Чужая сущность, названная в черновике настроек, отбивается, а не выправляется молча.** Иначе
-  одним ответом скрывались бы и подделанный запрос, и админка, которая загрузила одну сущность,
-  а сохраняет в другую.
-- **Выборка админки отбирает записи по сущности захода, и снять это условие нечем.** Оно
-  складывается с условиями отбора клиента, а не заменяется ими: иначе список, поиск и число в
-  сводке показывают чужое.
-- **Запись, названную в запросе своим номером, выборка берёт с условием по сущности, и правка
-  со снятием идут тем же условием.** Сущность уезжает параметром рядом с идентификатором в то
-  же условие; у записи без своей колонки граница выводится связью. Чужая запись отвечает так же,
-  как несуществующая, — и связанный идентификатор сверяется наравне с основным.
-- **Выборку по номеру без сущности в условии ловит проверка охвата.** Список точек умер бы со
-  слиянием: следующая процедура завелась бы без условия, и не заметил бы этого никто. Путь, где
-  сущности законно нет, назван в списке известного строкой с причиной.
-- **Адрес публичной страницы уникален внутри сущности, а не по всей системе.** Пара «сущность и
-  адрес» стоит уникальным индексом и у записей, и у их прежних адресов; сквозную уникальность
-  между двумя таблицами держит хранилище — оно читает ту же пару. У прежнего адреса сущность
-  продублирована колонкой: связью пара в уникальный индекс не собирается.
-- **Занятость адреса спрашивается внутри сущности, и чужая занятость владельцу не видна.** Отказ
-  «адрес занят» на имя, которое держит сосед, выдал бы существование его записи.
-- **Публичный вход, нашедший под адресом больше одной записи, отвечает как на
-  несуществующую.** Гость приходит по адресу и сущности не называет, поэтому признак совпадения
-  едет отдельным полем результата выборки: пустой ответ забыли бы разобрать, а показ первого
-  попавшегося отдал бы гостю чужую запись молча. Владелец узнаёт о таком случае строкой лога,
-  заведённой в списке отбираемых.
-- **Принадлежность записи сущности записана колонкой везде, где её не из чего вывести.** Там,
-  где у записи обязательна связь с другой записью сущности, граница выводится связью; у визита,
-  события и разговора выводить её не из чего — заход бывает записан на несуществующий путь, а
-  разговор начат с корня сайта.
-
-## Чего из закона здесь нет
-
-Внутри сущности границ нет: право открывает раздел целиком, и сотрудник, которому доверена одна
-запись, видит все записи своей сущности.
-
-Признака, по которому гость назвал бы сущность, может не быть вовсе — тогда там, где гость не
-назвал ничего, читатель берёт единственную сущность хранилища и отвечает отказом по состоянию,
-когда их больше одной. Тем же вызвана и временная граница у адреса страницы: совпавший адрес
-недоступен обеим сущностям, потому что выбрать между ними нечем.
-
-Роль живёт у учётной записи, а не у принадлежности, пока принадлежность у человека одна:
-колонки прав у принадлежности стоят и не читаются, а права читаются у учётной записи при каждом
-вызове.
-
-Выбора сущности сотрудником может не быть: сущностью захода остаётся то, что записано у учётной
-записи, и сменить это значение нечем, пока нет ни селектора, ни процедуры. Тогда выбором
-остаётся единственная принадлежность.
-
-## Паттерны
-
-- `ownership-session-procedure` — процедура, которой нужна сущность захода: объявление, чтение,
-  отказы, контекст в тесте.
-
-## Ловушки
-
-- **Сущность захода и принадлежность — разные вещи.** Колонка учётной записи говорит, в какой
-  сущности человек работает сейчас; принадлежность — в каких он вправе работать вообще.
-  Значение колонки без принадлежности к той же сущности ничего не значит: выборка сверяет их
-  между собой и отдаёт пусто, когда они разошлись.
-- **Забытый декоратор не ловится ни сборкой, ни линтером.** Процедура, читающая сущность захода
-  без объявления потребности, собирается и проходит проверки — отказ приходит на первом же
-  вызове. Пишутся эти две строки вместе, а покрывается это тестом процедуры.
-- **Потребность в сущности доступом не является.** Объявлений доступа у процедуры по-прежнему
-  ровно одно, и декоратор потребности к этому счёту не относится: сущность нужна и процедуре с
-  правом, и процедуре, открытой любому вошедшему.
-- **Отказ снятой принадлежности — тот же, что на неверный пароль, а не отказ в доступе.**
-  Второй оставил бы человека на закрытом разделе с непонятной причиной и без выхода, хотя
-  лечится это только новым входом.
-- **Снятое поле контракта не заводится заново под тем же номером.** Номер и имя помечены как
-  занятые, и метка снимается только вместе с решением отдать номер новому полю, — а такое
-  решение ломает уже выкаченного клиента молча: он прочитает чужое значение как своё.

package/assets/rules/pricing.md

@@ -1,68 +0,0 @@
----
-name: pricing
-kind: rule
-law: money
-description: Правило под «Закон о деньгах». Брать при правке расчёта цены, скидок, курсов валют, сумм в заказах, письмах и сводках. Называет хранение в целых единицах валюты хранения, единственное округление, выбор одной наибольшей скидки и справочный пересчёт. Готовый код — в паттерне pricing-quote. Чем это названо здесь — в implementation.md рядом.
----
-
-# Суммы — как это устроено здесь
-
-Правило под закон `docs/constitution/application/money.md`. Закон говорит, что должно быть
-верно; здесь — каким приёмом это держится. Валюта хранения, набор справочных валют и имена
-колонок — при этом дереве, в `implementation.md` рядом.
-
-## Как это называется здесь
-
-| В законе      | Здесь                                                                                          |
-| ------------- | ---------------------------------------------------------------------------------------------- |
-| сумма         | целое число единиц валюты хранения; код валюты стоит в имени поля — `total<Код>`, `price<Код>` |
-| валюта показа | поле заказа с кодом валюты, в которой пользователь смотрел цену                                |
-| расчёт цены   | одна чистая функция: на входе — что заказано, на выходе — подытог, скидка и итог               |
-| скидка        | механики перечислены в `implementation.md`; правило про выбор одно на все                      |
-| курс          | кэш в хранилище, обновляется по расписанию                                                     |
-
-## Где это лежит
-
-В этом дереве — таблица в `implementation.md` рядом. Пути живут там, а не здесь: правило
-переносится между репозиториями, раскладка — нет, и путь, названный в правиле, врёт в первом
-же дереве, которое держит код иначе.
-
-## Как закон применяется здесь
-
-- **Сумма хранится в целых единицах валюты хранения.** Дробная часть даёт расхождение между
-  подытогом и итогом: показанное построчно перестаёт складываться в показанное внизу. Если
-  дробная часть в предметной области значима, единицей хранения становится она сама.
-- **Код валюты стоит в имени поля, а не подразумевается.** Поле `total` без кода читается как
-  «сумма вообще», и первый же пересчёт кладёт в него чужую валюту.
-- **Округление происходит один раз — при расчёте цены.** Сумма на экране, сумма в письме и
-  сумма в хранилище — одно и то же число, а не три результата одного пересчёта.
-- **Из подходящих скидок применяется одна — наибольшая.** Сравниваются они в валюте хранения:
-  доля и сумма иначе несравнимы.
-- **При равной выгоде побеждает та скидка, которую пользователь ввёл руками.** Он ждёт
-  подтверждения своему действию, а «код не сработал» при той же итоговой цене читается как
-  поломка.
-- **Скидка суммой ограничена подытогом.** Иначе она увела бы цену ниже нуля.
-- **Пересчёт в чужую валюту не хранится.** В заказе лежат сумма в валюте хранения и код валюты
-  показа; само число вычисляется на показ.
-- **Оплата идёт в валюте хранения, остальные валюты — справка.** Ни подтверждение, ни документ
-  не называют справочное число суммой к оплате.
-- **Валюта показа следует за пользователем.** Он выбрал её на экране — в письме сумма
-  пересчитана в неё же.
-- **Курс недоступен — сумма показывается в валюте хранения без пересчёта.** Пересчёт по
-  неизвестно какому курсу хуже отсутствующего: отсутствие видно, а неверный курс — нет.
-
-## Паттерны
-
-- `pricing-quote` — расчёт цены, выбор скидки, работа с курсом.
-
-## Ловушки
-
-- **Курс тянется по расписанию и кэшируется.** Само число в чужой валюте нигде не сохраняется.
-- **Дробная сумма в контракте — признак того, что округление уехало на показ.** Округление
-  одно, и живёт оно в расчёте.
-- **Справочная сумма рядом с суммой к оплате читается как цена.** В письме и в документе
-  справочное число подписывается как справка.
-- **Набор валют переключателя бывает шире набора курсов.** Набор переключателя собирается из
-  начальных валют локалей, и валюты, курса для которых никто не тянет, попадают в него сами:
-  гость такой локали получает отказ курса, ничего не выбирая. Два набора сверяются между собой,
-  а расхождение чинится задачей — правкой текста оно не лечится.