steelmorgan/technical-design-standard

Стандарт технического дизайна (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. Когда нужен технический дизайн

| Тип задачи | Нужен ТД | Обоснование | |------------|----------|-------------| | Новая функциональность (средняя/сложная) | MUST | Фиксирует архитектуру до начала разработки | | Доработка типовой конфигурации с изменением структуры | MUST | Нужно обосновать выбор подхода (расширение vs конфигурация) | | Интеграция с внешней системой | MUST | Контракты и data flow критичны | | Простое исправление бага | MAY | Только если баг требует архитектурных изменений | | Рефакторинг с изменением модульной структуры | SHOULD | Нужна прозрачность по границам изменений | | Внешняя обработка (EPF) с формой | SHOULD | Структура метаданных и UI требуют проектирования. MUST если EPF включает фоновые операции, права доступа или обмен данными |

---

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

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

# Технический дизайн: [Краткое название]

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

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

| § | Секция | Обязательность | Условие | |---|--------|---------------|---------| | 1 | Обзор | MUST | Всегда | | 2 | Стратегия решения | MUST | Всегда | | 3 | Структурные блоки | MUST | Всегда | | 4 | Данные и метаданные | MUST | Всегда | | 5 | Сквозные концепции | SHOULD | MUST если задача затрагивает >2 модулей или меняет сквозное поведение | | 6 | Ключевые решения | MUST | Всегда (минимум 1 решение) | | 7 | Риски и недостатки | MUST | Всегда | | 8 | Допущения и открытые вопросы | SHOULD | MUST если есть неопределённости, блокирующие часть дизайна | | 9 | Миграция и откат | Conditional MUST | MUST если изменяются существующие объекты метаданных или требуется миграция данных | | 10 | Трассируемость | MUST | Всегда |

Правило: если секция неприменима к задаче — указать 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 правило 18 | | Логирование | ЖР через БСП (ЗаписьЖурналаРегистрации) | ssl-patterns: стандартный механизм | | Права доступа | Роль через xml-gen, RLS не требуется | Данные не содержат разграничения по организациям | | Транзакции | НачатьТранзакцию/Попытка для записи в регистр | coding-standards правило 18 | | Клиент/Сервер | &НаСервереБезКонтекста для бизнес-логики | coding-standards правило 3 | | Использование БСП | ОбщегоНазначения.СообщитьПользователю для валидации | ssl-patterns: проверка заполнения | | Платформенные ограничения | [описать если есть workarounds] | — |

Если все аспекты стандартны и не требуют специальных решений — указать: «Используются стандартные паттерны, см. 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. Типичные ошибки

| Ошибка | Последствие | |--------|------------| | Non-goals пуст | Scope creep | | Drawbacks пуст | Ревьюер не может оценить trade-offs | | JSON DSL полностью inline | Документ раздувается, теряется обзор → DSL в artifacts/ | | Дублирование спецификации | Нарушение single source of truth | | Traceability отсутствует | Невозможно проверить покрытие требований | | Все секции заполнены на простой задаче | Формальный overhead → использовать N/A | | Constraints не указаны | Несовместимый подход (EDT vs Designer, версия БСП) |

---

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

---