Бизнес-правило, которое можно прочитать, выполнить и проверить.

/**
 * HTTP-сервис расчёта скидки поверх FTS.
 *
 * Разделение ответственности, ради которого всё и затевалось:
 *   — FTS отвечает за бизнес-правило (какая скидка положена);
 *   — Node.js отвечает за эффекты (сокет, маршруты, коды ответа, лимит тела).
 *
 * Примеры из модели выполняются на старте: если предметный тест не проходит,
 * сервис не поднимается вообще. Правило, которое не проходит собственные
 * примеры, до продакшена не доезжает.
 *
 * Запуск:  node examples/fts/discount-api/server.mjs
 * Проверка: curl -s localhost:8788/discount -d '{"сумма":20000,"постоянный клиент":true}'
 */
import { createServer } from 'node:http';
import { readFile } from 'node:fs/promises';
import { fileURLToPath, pathToFileURL } from 'node:url';
import { resolve } from 'node:path';

import { assertValid, compile, executeUtility, testUtilities } from '../../../static/js/vendor/fts/browser.js';

const here = fileURLToPath(new URL('.', import.meta.url));
export const MODEL_FILE = resolve(here, '../../../static/fts/models/order-discount.fts');
const UTILITY = 'Рассчитать скидку';
const MAX_BODY = 64 * 1024;

export async function createCalculator(modelFile = MODEL_FILE) {
  const document = assertValid(compile(await readFile(modelFile, 'utf8')));
  const tests = testUtilities(document);
  if (!tests.valid) {
    const failed = tests.results.filter((result) => !result.passed);
    throw new Error(
      `FTS-примеры не прошли (${failed.length} из ${tests.total}): ` +
        failed.map((result) => `«${result.example}» ожидалось ${result.expected}, получено ${result.actual}`).join('; '),
    );
  }
  return { document, tests, calculate: (purchase) => executeUtility(document, UTILITY, purchase) };
}

export async function createDiscountServer(modelFile = MODEL_FILE) {
  const { calculate, tests, document } = await createCalculator(modelFile);
  const fields = document.structures.find((structure) => structure.name === 'Покупка').fields;

  return createServer(async (request, response) => {
    try {
      if (request.method === 'GET' && request.url === '/health') {
        return send(response, 200, { ok: true, model: document.category, examples: `${tests.passed}/${tests.total}` });
      }
      if (request.method === 'GET' && request.url === '/contract') {
        return send(response, 200, { utility: UTILITY, input: fields, output: 'Деньги' });
      }
      if (request.method !== 'POST' || request.url !== '/discount') {
        return send(response, 404, { error: 'используйте POST /discount' });
      }
      const purchase = JSON.parse(await readBody(request));
      return send(response, 200, { discount: calculate(purchase) });
    } catch (error) {
      /* Нарушенное свойство и неизвестное поле — это ошибка запроса, а не сбой
         сервиса: клиенту возвращается причина, диагностика FTS не теряется. */
      return send(response, 400, {
        error: error instanceof Error ? error.message : String(error),
        diagnostics: error?.diagnostics ?? [],
      });
    }
  });
}

async function readBody(request) {
  const chunks = [];
  let size = 0;
  for await (const chunk of request) {
    size += chunk.length;
    if (size > MAX_BODY) throw new Error('тело запроса больше 64 КБ');
    chunks.push(chunk);
  }
  return Buffer.concat(chunks).toString('utf8');
}

function send(response, status, body) {
  response.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
  response.end(`${JSON.stringify(body, null, 2)}\n`);
}

if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
  const port = Number.parseInt(process.env.FTS_HTTP_PORT ?? '8788', 10);
  const server = await createDiscountServer();
  server.listen(port, '127.0.0.1', () => {
    process.stdout.write(`Discount API: http://127.0.0.1:${port} (POST /discount, GET /contract, GET /health)\n`);
  });
}

/**
 * Допуск команды «отгрузить заказ» через доказательство на реальных данных.
 *
 * Это шаблон для агентских сценариев: модель (или человек) формулирует
 * утверждение на FTS, а решение принимает не текст ответа, а движок. Если факт
 * в данных не подтверждается, prove() отклоняет теорему и команда не выполняется.
 * Эффект (реальная отгрузка) живёт снаружи и вызывается только после allow.
 *
 * Запуск: node examples/fts/shipment-guard/guard.mjs ЗК-7781
 *         node examples/fts/shipment-guard/guard.mjs ЗК-7781 --blocked
 */
import { readFile } from 'node:fs/promises';
import { fileURLToPath, pathToFileURL } from 'node:url';
import { resolve } from 'node:path';

import { compile, prove } from '../../../static/js/vendor/fts/browser.js';

const here = fileURLToPath(new URL('.', import.meta.url));
const models = resolve(here, '../../../static/fts/models');

/* Кавычки внутри имени сломали бы разбор, поэтому номер заказа проверяется
   до подстановки: в теорему попадают только допустимые идентификаторы. */
const ORDER_NUMBER = /^[\p{L}\p{N}-]{1,32}$/u;

export function shipmentTheorem(orderNumber) {
  if (!ORDER_NUMBER.test(orderNumber)) throw new Error(`недопустимый номер заказа: ${orderNumber}`);
  return `категория «Исполнение заказа»

  объект Заказ
    номер является строкой
    клиент является строкой
    оплачен является признаком
    «склад подтвердил» является признаком
    «готов к отгрузке» является состоянием «Готов к отгрузке»

  морфизм «Готовый заказ можно отгрузить»
    если «Готов к отгрузке»
    то «Отгрузить заказ разрешено»

  теорема «Заказ ${orderNumber} можно отгрузить»
    дано Заказ имеет «готов к отгрузке» равное да
    в данных заказы найти где номер равен «${orderNumber}»
    по морфизму «Готовый заказ можно отгрузить»
    следовательно «Отгрузить заказ разрешено»
`;
}

export function decideShipment(orderNumber, context) {
  const source = shipmentTheorem(orderNumber);
  try {
    const proof = prove(compile(source), context);
    return { allowed: true, source, proof };
  } catch (error) {
    return {
      allowed: false,
      source,
      reason: error instanceof Error ? error.message : String(error),
      diagnostics: error?.diagnostics ?? [],
    };
  }
}

export async function loadContext(blocked = false) {
  const file = resolve(models, blocked ? 'order-shipment.blocked.context.json' : 'order-shipment.context.json');
  return JSON.parse(await readFile(file, 'utf8'));
}

if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
  const orderNumber = process.argv[2] ?? 'ЗК-7781';
  const decision = decideShipment(orderNumber, await loadContext(process.argv.includes('--blocked')));
  process.stdout.write(`${JSON.stringify(decision, null, 2)}\n`);
  /* Ненулевой код возврата делает guard пригодным для shell и CI. */
  process.exit(decision.allowed ? 0 : 1);
}

// Generated by FTS. Do not edit by hand.

export interface FtsInput0 {
  "сумма": number
  "постоянный клиент": boolean
}

export const ftsUtilities = {
  "Рассчитать скидку": (input: FtsInput0): number => {
    let result: number = 0
    if (input["сумма"] >= 10000 && input["сумма"] <= 100000) {
      result += (10 / 100) * input["сумма"]
    }
    if (input["постоянный клиент"] === true && input["сумма"] > 0 && input["сумма"] <= 100000) {
      result += (5 / 100) * input["сумма"]
    }
    if (input["сумма"] > 100000) {
      result += 15000
    }
    if (!(result <= 15000)) throw new Error("Нарушено свойство «Скидка ограничена»")
    return result
  },
} as const

/**
 * Форма скидки на React.
 *
 * Компонент не знает, что покупка состоит из суммы и признака постоянного
 * клиента: поля приходят из той же FTS-модели, которую проверяет бэкенд.
 * Добавили в модель поле — форма получила контрол без правки JSX.
 *
 * Предпросчёт скидки выполняется прямо в браузере тем же компилятором, поэтому
 * пользователь видит результат без сетевого запроса. Сервер всё равно считает
 * заново: браузеру доверять нельзя, но и ждать его не нужно.
 */
import { useMemo, useState } from 'react';
import { compile, executeUtility } from '@digitable/fts/browser';

import { ftsFormSchema } from '../form-schema/schema.mjs';

export function DiscountForm({ source, objectName = 'Покупка', utility = 'Рассчитать скидку', onSubmit }) {
  const document = useMemo(() => compile(source), [source]);
  const schema = useMemo(() => ftsFormSchema(document, objectName), [document, objectName]);
  const [value, setValue] = useState(() =>
    Object.fromEntries(schema.fields.map((field) => [field.name, field.control === 'checkbox' ? false : ''])),
  );

  const preview = useMemo(() => {
    try {
      const input = Object.fromEntries(
        schema.fields.map((field) => [
          field.name,
          field.control === 'checkbox' ? Boolean(value[field.name]) : Number(value[field.name] || 0),
        ]),
      );
      return { ok: true, amount: executeUtility(document, utility, input) };
    } catch (error) {
      /* Нарушенное свойство модели — это нормальный ответ формы, а не падение UI. */
      return { ok: false, reason: error.message };
    }
  }, [document, schema, utility, value]);

  return (
    <form
      onSubmit={(event) => {
        event.preventDefault();
        onSubmit?.(value);
      }}
    >
      <h2>{schema.title}</h2>

      {schema.fields.map((field) => (
        <label key={field.name}>
          <span>{field.label}</span>
          <input
            type={field.control === 'checkbox' ? 'checkbox' : field.control === 'text' ? 'text' : 'number'}
            required={field.required}
            checked={field.control === 'checkbox' ? Boolean(value[field.name]) : undefined}
            value={field.control === 'checkbox' ? undefined : value[field.name]}
            onChange={(event) =>
              setValue((current) => ({
                ...current,
                [field.name]: field.control === 'checkbox' ? event.target.checked : event.target.value,
              }))
            }
          />
        </label>
      ))}

      <output>
        {preview.ok ? `Скидка: ${preview.amount} ₽` : `Правило не выполняется: ${preview.reason}`}
      </output>

      <button type="submit" disabled={!preview.ok}>
        Оформить
      </button>
    </form>
  );
}

# Предметные правила как обычный шаг CI.
#
# Смысл шага не в «ещё одном линтере»: примеры внутри .fts — это тесты,
# написанные на языке предметной области, а сгенерированный TypeScript
# сверяется с моделью. Правило, изменённое в коде мимо модели, ломает сборку.
#
# Файл кладётся в .github/workflows/fts-check.yml
name: fts

on:
  push:
    branches: [master]
  pull_request:

jobs:
  rules:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 24
          cache: npm

      - run: npm ci

      # Модель разобралась, типы сошлись, ссылки на объекты и поля существуют.
      - name: Проверить модели
        run: npx fts check static/fts/models/order-discount.fts

      # Примеры из .fts выполняются как предметные unit-тесты.
      - name: Выполнить предметные примеры
        run: npx fts test static/fts/models/order-discount.fts --pretty

      # Сгенерированный TypeScript обязан совпадать с закоммиченным.
      - name: Сверить сгенерированный код
        run: node examples/fts/typescript-codegen/generate.mjs --check

      # Интеграции: HTTP-сервис, guard допуска команды, схема формы.
      - name: Тесты интеграций
        run: node --test "examples/fts/**/*.test.mjs"