@rt-tools/agent-kit 0.5.3 → 0.7.0

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,63 +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/pricing.md

@@ -1,64 +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` — расчёт цены, выбор скидки, работа с курсом.
-
-## Ловушки
-
-- **Курс тянется по расписанию и кэшируется.** Само число в чужой валюте нигде не сохраняется.
-- **Дробная сумма в контракте — признак того, что округление уехало на показ.** Округление
-  одно, и живёт оно в расчёте.
-- **Справочная сумма рядом с суммой к оплате читается как цена.** В письме и в документе
-  справочное число подписывается как справка.