version: "1.0.1" name: technical-design-standard description: "Use for написания технического дизайна (Phase 2). Defines структуру technical-design.md, правила заполнения секций (MUST/SHOULD/MAY) и чеклист качества для архитектора и ревьюера (scope=arch)."

Стандарт технического дизайна (Technical Design)

Технический дизайн (technical-design.md) — мост между спецификацией (ЧТО) и декомпозицией задач (КАК). Фиксирует архитектурные решения, модульную структуру, контракты и сквозные концепции. Расширяет high-level секцию Technical Design из спецификации.

Основа: Google Design Docs, arc42, MADR 4.0, Stripe RFC (Drawbacks), C4 Model.

2. Язык документа

Технический дизайн MUST быть написан на русском языке — заголовки секций, описания, обоснования, таблицы. Исключение — идентификаторы кода и метаданных (имена модулей, реквизитов, переменных, сигнатуры BSL), а также устоявшиеся термины (ADR, RFC 2119, C4, MUST/SHOULD/MAY).

3. Когда нужен технический дизайн

4. Обязательная структура technical-design.md

Заголовок и метаданные

# Технический дизайн: [Краткое название]
 
| Поле | Значение |
|------|----------|
| Спецификация | [SPEC-NNN](ссылка на spec.md) |
| Дата | YYYY-MM-DD |
| Статус | Черновик / Ревью / Утверждён |
| Explorer | [explorer-context.md](ссылка) |
| Декомпозиция | [task-breakdown.json](ссылка) |
| Каталог ADR | [task_dir/adr/](ссылка) |

Секции и правила обязательности

Правило: если секция неприменима к задаче — указать N/A с краткой причиной. Не удалять секцию.

5. Описание секций

§ 1. Обзор

1.1 Цели

Что должно быть достигнуто техническим решением. Формулировки через RFC 2119 (MUST/SHOULD/MAY) не нужны — они уже в спецификации. Здесь — технические цели дизайна.

1.2 Не-цели

Что дизайн явно НЕ решает. Самая ценная секция для предотвращения scope creep. Каждый non-goal — это осознанное исключение.

1.3 Предыстория

Текущее состояние системы (TOGAF Baseline). Какие модули/объекты существуют, как работают сейчас. Ссылка на explorer-context.md как базовый источник — не дублировать, а расширять только там, где нужно для дизайна.

1.4 Ограничения

Ограничения, влияющие на архитектуру:

• Режим разработки: расширение vs изменение основной конфигурации
• Версия платформы 1С и минимальная версия БСП
• Ограничения xml-gen (формат Designer, не EDT; SKD 85%)
• Организационные ограничения (сроки, доступ к серверу, лицензии)

§ 2. Стратегия решения

Высокоуровневое описание выбранного подхода (2–3 абзаца):

• Какие ключевые технологические/архитектурные решения приняты
• Какие паттерны выбраны и почему
• Как подход отвечает на Goals из §1.1

Это стратегия, не детали. Детали — в §3 и §4.

§ 3. Структурные блоки

3.1 Контекст системы (C4 Level 1)

Система в контексте внешних систем и пользователей. Для интеграционных задач — обязательная диаграмма (текстовая или ASCII).

Для задач внутри одной конфигурации — MAY быть кратким описанием затронутых подсистем.

3.2 Карта модулей (C4 Level 2–3)

Затронутые и новые модули, их связи:

| Модуль | Тип | Новый/Существующий | Ответственность |
|--------|-----|--------------------|-----------------|
| ОМ.РаботаСКонтрагентами | Общий модуль | Существующий (модификация) | Валидация, получение данных |
| МодульОбъекта.Контрагенты | Модуль объекта | Существующий (модификация) | Обработчики записи |

Для сложных задач — текстовая схема вызовов между модулями.

3.3 Интерфейсы и контракты

Сигнатуры ключевых процедур/функций с контрактами:

// Функция ПроверитьИНН(ИНН: Строка): Булево
//
// Параметры:
//   ИНН — Строка(10) или Строка(12), не пустая
// Возврат:
//   Истина — если ИНН корректен по алгоритму проверки контрольных разрядов
// Исключение:
//   Если ИНН пустая строка — ВызватьИсключение
// Директива: &НаСервереБезКонтекста

§ 4. Данные и метаданные

4.1 Объекты метаданных

Таблица всех затронутых объектов метаданных:

| Объект | Тип | Новый/Сущ. | Изменения | DSL |
|--------|-----|-----------|-----------|-----|
| Справочник.Контрагенты | Справочник | Сущ. | +Реквизит ИНН (Строка 12) | — |
| РС.ИсторияИзменений | Регистр сведений | Новый | Период, Объект, Автор, Описание | — |
| Форма.ФормаЭлемента | Управляемая форма | Новый | Поле ИНН, кнопка Проверить | [form-dsl.json](artifacts/form-dsl.json) |
| Роль.МенеджерПродаж | Роль | Новый | Права на справочник и регистр | [role-dsl.json](artifacts/role-dsl.json) |

Правило по JSON DSL:

• Сложные объекты (формы, SKD, роли): ссылка на DSL-файл в task_dir/artifacts/ MUST; inline-фрагмент в дизайне MAY (только ключевые элементы для понимания архитектуры)
• Простые объекты (справочники, документы, регистры): текстовое описание структуры MUST

4.2 Поток данных

Как данные движутся через систему для ключевых сценариев:

Пользователь → Форма.Контрагент
  → МодульОбъекта.ПриЗаписи()
    → ОМ.РаботаСКонтрагентами.ПроверитьИНН()
    → РС.ИсторияИзменений.Запись

Для интеграций — data flow между системами с указанием протоколов и форматов. Для каждой интеграционной точки SHOULD указать NFR-контракт: timeout, retry-политика, idempotency, аутентификация, маппинг ошибок.

§ 5. Сквозные концепции

Сквозные решения, пронизывающие все модули. SHOULD указать решение по каждому применимому аспекту:

Если все аспекты стандартны и не требуют специальных решений — указать: «Используются стандартные паттерны, см. coding-standards и ssl-patterns. Специальных решений нет.»

§ 6. Ключевые решения

Краткая таблица архитектурных решений:

| # | Решение | Варианты | Выбор | Обоснование | ADR |
|---|---------|---------|-------|-------------|-----|
| 1 | Хранение истории | A) ЖР, B) Отдельный регистр | B | Нужны запросы и отчёты по истории | [ADR-001](adr/ADR-001.md) |
| 2 | Валидация ИНН | A) Свой алгоритм, B) Внешний сервис | A | Нет зависимости от сети | — (тривиальное) |

Правило: для каждого неочевидного решения (≥2 альтернативы с разными trade-offs) — отдельный ADR-файл в task_dir/adr/.

Формат ADR (MADR 4.0 lean):

# ADR-NNN: [Название решения]
 
Status: Accepted
Date: YYYY-MM-DD
 
## Context
[Почему возник вопрос]
 
## Decision Drivers
-[Фактор 1]
-[Фактор 2]
 
## Considered Options
1.[Вариант A] — описание
2.[Вариант B] — описание
 
## Decision Outcome
Выбран вариант [X].
 
### Consequences
-Good: [что улучшится]
-Bad: [что ухудшится]
 
### Confirmation
[Как проверить, что решение реализовано корректно]

§ 7. Риски и недостатки

7.1 Недостатки

Что станет хуже, сложнее, дороже. Если drawbacks пуст — дизайн не проанализирован достаточно.

7.2 Риски

| # | Риск | Вероятность | Влияние | Mitigation |
|---|------|-------------|---------|------------|
| 1 | Производительность запроса при >100K записей | Средняя | High | Индекс + лимит выборки |

§ 8. Допущения и открытые вопросы

Допущения — принятые при неопределённости. Не блокируют дизайн, но могут повлиять на реализацию:

-Предполагаем, что максимальное кол-во контрагентов < 500K
-БСП версии 3.1+ (иначе нужен fallback для ДлительныеОперации)

Открытые вопросы — оставшиеся без ответа. Не блокируют архитектуру, но требуют уточнения до или во время реализации.

§ 9. Миграция и откат (условная)

Условие: секция MUST если изменяются существующие объекты метаданных или требуется миграция данных. Иначе — N/A: новые объекты, миграция не требуется.

9.1 План миграции

• Порядок обновления (конфигурация → данные → права)
• Обработки заполнения / конвертации данных
• Этапность (если поэтапное внедрение)

9.2 Стратегия отката

• Можно ли откатить изменения
• Что произойдёт с данными при откате
• Точка невозврата (если есть)

§ 10. Трассируемость

Матрица связи: требование из спецификации → секция дизайна → задача из декомпозиции.

| Spec Requirement | Design Section | Task IDs |
|------------------|---------------|----------|
| MUST-1: Валидация ИНН | §3.3 Interfaces, §4.1 Metadata | T-001, T-003 |
| MUST-2: История изменений | §4.1 Metadata, §4.2 Data Flow | T-002 |
| SHOULD-1: Отчёт по истории | §4.1 Metadata (SKD) | T-005 |

Правило: каждый MUST из спецификации MUST быть покрыт хотя бы одной секцией дизайна и одной задачей. SHOULD — SHOULD быть покрыт.

6. Критерии качества technical-design.md

Чеклист для ревьюера (scope=arch):

Структура и полнота

• [ ] Все MUST-секции заполнены (или N/A с причиной)
• [ ] Заголовок содержит ссылки на spec, explorer-context, task-breakdown
• [ ] Status корректен (Draft при создании)

Обзор (§1)

• [ ] Цели описывают технические цели, не дублируют требования спецификации
• [ ] Не-цели содержат минимум 1 осознанное исключение
• [ ] Предыстория опирается на explorer-context.md, не дублирует его
• [ ] Ограничения учитывают: режим разработки (расширение/конфигурация), версию платформы/БСП

Стратегия решения (§2)

• [ ] Стратегия отвечает на каждую Цель из §1.1
• [ ] Описание на уровне подхода, не на уровне кода

Структурные блоки (§3)

• [ ] Карта модулей покрывает все модули из scope спецификации
• [ ] Интерфейсы и контракты содержат сигнатуры с параметрами, возвратом, директивами компиляции
• [ ] Нет неявных зависимостей между модулями

Данные и метаданные (§4)

• [ ] Все объекты метаданных перечислены с типами и изменениями
• [ ] Сложные объекты (формы, SKD, роли) имеют ссылку на JSON DSL-файл
• [ ] Поток данных покрывает ключевые сценарии из плана тестирования

Сквозные концепции (§5)

• [ ] Решения по обработке ошибок, транзакциям, правам, клиент/серверной границе
• [ ] Обосновано использование или отказ от механизмов БСП (ssl-patterns)
• [ ] Платформенные ограничения с workarounds (если есть)

Ключевые решения (§6)

• [ ] Для каждого неочевидного решения (≥2 альтернативы) есть обоснование
• [ ] ADR-файлы содержат последствия и подтверждение
• [ ] Нет решений, противоречащих спецификации

Риски и недостатки (§7)

• [ ] Недостатки не пусты — каждое решение имеет цену
• [ ] Высокие риски имеют план смягчения
• [ ] Компромиссы описаны честно (плюсы + минусы)

Трассируемость (§10)

• [ ] Каждый MUST из спецификации покрыт секцией дизайна и задачей
• [ ] Нет требований без привязки к дизайну
• [ ] task IDs совпадают с task-breakdown.json

Декомпозиция задач (JSON)

• [ ] Все задачи имеют уникальные task_id
• [ ] depends_on валидны и не содержат циклов
• [ ] spec_refs ссылаются на существующие разделы спецификации
• [ ] task_type корректен (code/test/migration/docs/analysis/architecture)
• [ ] done_criteria проверяемы и конкретны
• [ ] JSON хранится отдельным файлом, в дизайне — ссылка

Согласованность с фреймворком

• [ ] Документ написан на русском языке (кроме идентификаторов кода и устоявшихся терминов)
• [ ] Совместимость с существующей конфигурацией (coding-standards)
• [ ] Дизайн реализуем в рамках scope спецификации
• [ ] Дизайн не противоречит решениям из Decision Log спецификации

7. Типичные ошибки

8. Связанные навыки

Входные: spec-standard. Выходные: task-breakdown-*. Критерии: coding-standards, ssl-patterns. Генерация метаданных: xml-generation.

depends_on:

• framework/skills/spec-writing/spec-standard/SKILL.md
• framework/skills/bsl-practices/ssl-patterns/SKILL.md
• framework/skills/bsl-practices/coding-standards/SKILL.md