technical-design-standard

---
name: technical-design-standard
description: Стандарт технического дизайна для задач разработки 1С. Задаёт структуру technical-design.md, правила заполнения секций (MUST/SHOULD/MAY), чеклист качества и guidance по уровню детализации. Используется архитектором (Phase 2) и ревьюером (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 | Фиксирует архитектуру до начала разработки |
| Доработка типовой конфигурации с изменением структуры | MUST | Нужно обосновать выбор подхода (расширение vs конфигурация) |
| Интеграция с внешней системой | MUST | Контракты и data flow критичны |
| Простое исправление бага | MAY | Только если баг требует архитектурных изменений |
| Рефакторинг с изменением модульной структуры | SHOULD | Нужна прозрачность по границам изменений |
| Внешняя обработка (EPF) с формой | SHOULD | Структура метаданных и UI требуют проектирования. MUST если EPF включает фоновые операции, права доступа или обмен данными |

---

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

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

```markdown
# Technical Design: [Краткое название]

| Поле | Значение |
|------|----------|
| Spec | [SPEC-NNN](ссылка на spec.md) |
| Date | YYYY-MM-DD |
| Status | Draft / Review / Approved |
| Explorer | [explorer-context.md](ссылка) |
| Task Breakdown | [task-breakdown.json](ссылка) |
| ADR Directory | [task_dir/adr/](ссылка) |
```

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

| § | Секция | Обязательность | Условие |
|---|--------|---------------|---------|
| 1 | Overview | **MUST** | Всегда |
| 2 | Solution Strategy | **MUST** | Всегда |
| 3 | Building Blocks | **MUST** | Всегда |
| 4 | Data & Metadata | **MUST** | Всегда |
| 5 | Crosscutting Concepts | **SHOULD** | MUST если задача затрагивает >2 модулей или меняет сквозное поведение |
| 6 | Key Decisions | **MUST** | Всегда (минимум 1 решение) |
| 7 | Risks & Drawbacks | **MUST** | Всегда |
| 8 | Assumptions & Open Questions | **SHOULD** | MUST если есть неопределённости, блокирующие часть дизайна |
| 9 | Migration & Rollback | **Conditional MUST** | MUST если изменяются существующие объекты метаданных или требуется миграция данных |
| 10 | Traceability | **MUST** | Всегда |

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

---

## 4. Описание секций

### § 1. Overview

#### 1.1 Goals

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

#### 1.2 Non-goals

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

#### 1.3 Background

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

#### 1.4 Constraints

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

---

### § 2. Solution Strategy

Высокоуровневое описание выбранного подхода (2–3 абзаца):
- Какие ключевые технологические/архитектурные решения приняты
- Какие паттерны выбраны и почему
- Как подход отвечает на Goals из §1.1

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

---

### § 3. Building Blocks

#### 3.1 System Context (C4 Level 1)

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

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

#### 3.2 Module Map (C4 Level 2–3)

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

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

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

#### 3.3 Interfaces & Contracts

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

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

---

### § 4. Data & Metadata

#### 4.1 Metadata Objects

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

```markdown
| Объект | Тип | Новый/Сущ. | Изменения | 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

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

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

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

---

### § 5. Crosscutting Concepts

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

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

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

---

### § 6. Key Decisions

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

```markdown
| # | Решение | Варианты | Выбор | Обоснование | 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):

```markdown
# 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. Risks & Drawbacks

#### 7.1 Drawbacks

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

#### 7.2 Risks

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

---

### § 8. Assumptions & Open Questions

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

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

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

---

### § 9. Migration & Rollback (conditional)

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

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

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

---

### § 10. Traceability

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

```markdown
| 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 быть покрыт.

---

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

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

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

### Overview (§1)
- [ ] Goals описывают технические цели, не дублируют требования спецификации
- [ ] Non-goals содержат минимум 1 осознанное исключение
- [ ] Background опирается на explorer-context.md, не дублирует его
- [ ] Constraints учитывают: режим разработки (расширение/конфигурация), версию платформы/БСП

### Solution Strategy (§2)
- [ ] Стратегия отвечает на каждый Goal из §1.1
- [ ] Описание на уровне подхода, не на уровне кода

### Building Blocks (§3)
- [ ] Module Map покрывает все модули из scope спецификации
- [ ] Interfaces & Contracts содержат сигнатуры с параметрами, возвратом, директивами компиляции
- [ ] Нет неявных зависимостей между модулями

### Data & Metadata (§4)
- [ ] Все объекты метаданных перечислены с типами и изменениями
- [ ] Сложные объекты (формы, SKD, роли) имеют ссылку на JSON DSL-файл
- [ ] Data Flow покрывает ключевые сценарии из Test Plan спецификации

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

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

### Risks & Drawbacks (§7)
- [ ] Drawbacks не пуст — каждое решение имеет цену
- [ ] Высокие риски имеют mitigation
- [ ] Trade-offs описаны честно (Good + Bad)

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

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

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

---

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

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

---

## 7. Связанные навыки

Входные: `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
---