sharix-open-landing/CODING_POLICY.md

Coding policy: landing

Статус и область действия

Этот документ дополняет корневой CODING_POLICY.md установленного ShariX Open. При конфликте действует более строгое правило. Он описывает архитектурные границы и порядок изменения модуля, но не заменяет README и профильную документацию.

Ответственность модуля

Модуль владеет публичными landing-страницами и формами первичного взаимодействия. Он не содержит критическую бизнес-логику, жизненный цикл заказа или альтернативную систему авторизации.

Архитектурные слои

• Views/forms: HTTP-ввод, валидация и вызов публичных use cases.
• Templates/static: публичное представление.
• Models: только данные landing, если они действительно долговечны.
• Integration helpers: чтение публичных данных сервиса через стабильные contracts.

Направление зависимостей

Landing зависит от публичных helpers/API базового проекта. Base не импортирует landing. Отсутствие модуля не ломает кабинет и API. Формы не обращаются напрямую к внутренним моделям профильных модулей при наличии публичного use case.

Источники истины, коды и контракты

Коды форм/действий берутся из models/forms и публичного backend contract. Название сервиса и брендинг берутся из актуальной конфигурации/metaservice, а не дублируются строками в шаблонах.

Конфигурация

• В конфигурацию выносятся свойства конкретной установки: адреса и порты, секреты, режимы интеграций, feature switches, эксплуатационные лимиты, timeout/retry/interval, размеры пакетов и пути к локальным данным.
• В конфигурацию не выносятся стабильные доменные коды, имена полей API, правила целостности, обязательные проверки безопасности и значения, изменение которых меняет смысл уже сохранённых данных.
• Перед добавлением параметра проверяется общая конфигурация проекта и ближайший модуль-владелец. Нельзя создавать отдельную mobile/frontend/module-копию уже существующей общей настройки.
• Новая env-настройка добавляется в соответствующий .env.example, слой чтения и валидации, README и, когда это безопасно, system check. Секреты не получают небезопасных значений по умолчанию.
• Возможность изменения через web UI добавляется только для безопасной административной настройки с явной валидацией, атомарной записью, аудитом и понятным моментом применения. Секреты, системные пути и параметры запуска остаются в файловой конфигурации.
• После изменения примеров конфигурации указываются штатные команды conf/utils/normalize_env.py: --diff, затем --write, затем --check. --only-root используется только если изменён исключительно корневой .env.example.

Конфигурируются публичные links, analytics IDs, anti-spam, feature switches и deployment-specific content sources. Доменные действия и роли не задаются landing-конфигурацией.

Локализация и терминология

• Новый или изменяемый пользовательский текст web/API создаётся через штатный механизм Django i18n. Технические логи и CLI-сообщения не используются как пользовательские подписи или условия бизнес-логики.
• Стабильные коды статусов, ролей, действий, типов и словарей отделяются от отображаемых подписей. В БД и интеграционных контрактах передаются коды; подписи локализуются на границе представления.
• Актуальные коды и словари ищутся у владельца понятия: в model enum/choices, каноническом словарном модуле, domain policy и документации контракта. Их нельзя восстанавливать по кнопкам, шаблонам или старым примерам README.
• Код должен допускать будущую замену отдельных терминов через локализацию. Не использовать глобальную замену строк и не собирать пользовательские предложения конкатенацией фрагментов; применять placeholders, plural и locale-aware форматирование дат, времени, чисел и валют.
• При введении нового понятия определяются его стабильный код, владелец словаря, локализуемая подпись и правила безопасного отображения неизвестного кода.

Инварианты и обработка ошибок

Все формы имеют серверную валидацию, CSRF и защиту от спама/повторов. Ошибка необязательного внешнего блока отображается fail-soft. Landing не раскрывает внутренние данные и не создаёт бизнес-сущность в обход backend use case.

Сопровождение policy и README

• CODING_POLICY.md является частью модуля. Если изменение уточняет ответственность, слои, направление зависимостей, источник кодов/словарей, конфигурацию, локализацию или обязательные проверки, вместе с основным патчем предлагается соответствующая правка policy.
• Уточнение policy сначала явно описывается пользователю и согласовывается. Нельзя незаметно закреплять новое архитектурное решение только изменением документации.
• README.md описывает фактически доступные функции, установку, настройку, запуск и эксплуатацию. При изменении этих аспектов README обновляется в том же согласованном этапе.
• Policy не дублирует README и docs/: policy задаёт правила принятия решений, README объясняет использование, профильная документация фиксирует актуальные контракты и устройство.

Обязательные проверки

compileall landing; manage.py check; targeted tests форм/permissions/redirects; проверка страниц без optional integrations; collectstatic при static changes.

Проверки и подготовка патча

• Перед изменением используется самый свежий переданный исходник или фактическое рабочее состояние пользователя. Проверяется, какие предыдущие этапы уже применены; имя старого архива не считается доказательством актуальности.
• Патч относится к одному согласованному этапу и проверяется patch --dry-run --batch -p1 на точной базе. В выводе не должно быть FAILED, Reversed и интерактивных вопросов.
• В отчёте указываются база, затронутые контракты, необходимость миграций, collectstatic, нормализации конфигурации, рестарта units и реально выполненные проверки. Нельзя заявлять о проверке, которая не запускалась.
• Тесты выбираются по изменённому контракту. Новые тестовые файлы не включаются в рабочий patch без отдельного согласования.

Stage 14 touched-page UI contract

Stage 14 uses progressive touched-page coverage. When a page, form, template or user-visible workflow in this repository is new or materially changed, the same change must provide ru/en localization for the touched surface, operation-aware contextual help where applicable, explanatory empty states, informative form labels/choices/validation, and regression evidence for invalid input/rendered body as appropriate. Canonical model/API/status/role/action identifiers are not renamed for presentation.