# План редизайна пользовательской поверхности Scientia

## Обзор

| Фаза | Результат | Статус |
|------|-----------|--------|
| 1 | Зафиксирован baseline до редизайна | [x] |
| 2 | В корне оставлен один настраиваемый `main.typ` | [x] |
| 3 | Публичные инструкции и компилируемые примеры перенесены в `docs/` | [x] |
| 4 | Выбор типа выполняется задачей VS Code, private media — одним параметром | [x] |
| 5 | Полная регрессия и визуальная приёмка | [x] |

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

**Текущее до редизайна**: пользовательская справка находилась в скрытой `.template/help/`, конфигурация была разделена между `document.typ`, `main.typ`, `draft.typ` и `clean-copy.typ`, а учебные примеры лежали среди developer fixtures.

**Целевое состояние**: автор видит `main.typ`, `chapters/`, `assets/` и `docs/`. Режим задаётся одной переменной. Примеры четырёх типов документов и форматирования видимы, компилируемы и используются как заготовки. Приватная папка подключается одним параметром и содержит настройки индивидуальных подписей.

**Стратегия**: атомарное переключение пользовательского контракта без compatibility-файлов. Обратная совместимость не требуется.

| Фаза | Rollback |
|------|----------|
| 1 | Не требуется: только фиксация baseline |
| 2 | Восстановить предыдущие четыре корневых файла одним change set |
| 3 | Вернуть справку в `.template/help/`, не меняя библиотеку |
| 4 | Отключить задачи и использовать обычную сборку с placeholders |
| 5 | Откатить конкретную правку, повторить compile и visual suites |

---

## Фаза 1 — Зафиксировать baseline

**Цель**: доказать работоспособность библиотеки до изменения пользовательского контракта.  
**Результат**: unit, negative, company matrix, semantic и visual suites проходят.  
**Трудоёмкость**: S  
**Статус**: [x] Готово

### Задачи

- [x] Сохранить compile и visual baseline (→ [Модуль: Тестирование](../modules/testing.md))
- [x] Зафиксировать Typst 0.15.1 (→ [ADR-0001](adr/0001-typst-015.md))

### Тесты

- [x] Unit: domain и numbering
- [x] Интеграционный: четыре профиля и компании
- [x] Визуальный: утверждённые snapshot pages

---

## Фаза 2 — Оставить один `main.typ`

**Цель**: сделать все ежедневные настройки и `#include` видимыми в одном файле.  
**Результат**: `document.typ`, `draft.typ` и `clean-copy.typ` отсутствуют; режим выбирается в `main.typ`.  
**Трудоёмкость**: M  
**Статус**: [x] Готово

### Задачи

- [x] Перенести компанию, режим, metadata и порядок глав в `main.typ` (→ [Рабочее пространство автора](../modules/author-workspace.md))
- [x] Сохранить единый фасад импорта (→ [Публичный фасад](../modules/facade.md))
- [x] Проверить profile/options contract (→ [Документ](../modules/domain-document.md))
- [x] Сохранить границы организаций, сторон и приложений (→ [Организация](../modules/domain-company.md), [Стороны](../modules/domain-parties.md), [Приложения](../modules/domain-attachments.md))
- [x] Проверить application flow и загрузку компаний (→ [Сборка](../modules/application-render.md), [Ресурсы компаний](../modules/infrastructure-assets.md))

### Тесты

- [x] Static: единственный root entrypoint
- [x] Интеграционный: `final`, `draft`, `clean-copy` через profile fixtures
- [x] Ручной: порядок глав меняется только списком `#include`

---

## Фаза 3 — Открыть документацию и примеры

**Цель**: дать автору видимую справку и копируемые примеры без чтения реализации.  
**Результат**: `docs/` содержит навигацию, четыре полных документа и каталог оформления.  
**Трудоёмкость**: L  
**Статус**: [x] Готово

### Задачи

- [x] Разделить публичную и developer-документацию (→ [Публичная документация](../modules/user-documentation.md))
- [x] Сделать примеры источником выбора типа документа (→ [Публичные примеры](../modules/starter-packs.md))
- [x] Показать таблицы, формулы, подписи и media blocks (→ [Компоненты](../modules/components.md), [Основа вёрстки](../modules/presentation-foundation.md))
- [x] Показать ссылки, bibliography и numbering (→ [Ссылки](../modules/references.md), [Нумерация](../modules/numbering.md))
- [x] Подготовить адекватные примеры профилей (→ [Отчёт](../modules/presentation-report.md), [Письмо](../modules/presentation-letter.md), [ТКП](../modules/presentation-commercial-offer.md), [Договор](../modules/presentation-contract.md))

### Тесты

- [x] Интеграционный: пять публичных примеров компилируются
- [x] Semantic: ожидаемые подписи, ссылки, приложения и реквизиты присутствуют
- [x] Ручной: весь `docs/` доступен из корневого README

---

## Фаза 4 — Упростить VS Code и приватные данные

**Цель**: оставить одну build task и безопасно подключать папку `.private` одним параметром.  
**Результат**: выбор типа создаёт backup, обычная сборка работает с private media и без неё, отсутствующая подпись не ломает документ.  
**Трудоёмкость**: M  
**Статус**: [x] Готово

### Задачи

- [x] Оставить в Typewriter единственный `main.typ` и обновить задачи (→ [Рабочая область VS Code](../modules/vscode-workspace.md))
- [x] Добавить публичный справочник сотрудников, фиксированные PNG names и private offsets (→ [Приватные ресурсы](../modules/private-assets.md))
- [x] Использовать conditional import при явном `use-private-assets` (→ [ADR-0010](adr/0010-private-folder-and-employees.md))

### Тесты

- [x] Static: `.vscode/` синхронизируется, `docs/` не скрыт
- [x] Интеграционный: clean fork компилируется без `.private`
- [x] Интеграционный: private compile отображает реальные подписи и offsets
- [x] Интеграционный: `enabled: false` оставляет пустую строку без ошибки

---

## Фаза 5 — Hardening и выпуск

**Цель**: подтвердить отсутствие мёртвых путей, утечек и визуальных дефектов.  
**Результат**: полный harness проходит, Markdown-ссылки валидны, приватные ресурсы игнорируются.  
**Трудоёмкость**: M  
**Статус**: [x] Готово

### Задачи

- [x] Обновить static workspace contract (→ [Тестирование](../modules/testing.md))
- [x] Удалить скрытые дубликаты примеров и notes (→ [Публичная документация](../modules/user-documentation.md))
- [x] Проверить визуально все страницы публичных примеров (→ [ADR-0006](adr/0006-visual-regression.md))

### Тесты

- [x] Полный automated harness
- [x] Аудит Markdown links и legacy paths
- [x] Визуальная проверка contact sheets и проблемных страниц