9.0 KiB
План редизайна пользовательской поверхности 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] Готово
Задачи
- Сохранить compile и visual baseline (→ Модуль: Тестирование)
- Зафиксировать Typst 0.15.1 (→ ADR-0001)
Тесты
- Unit: domain и numbering
- Интеграционный: четыре профиля и компании
- Визуальный: утверждённые snapshot pages
Фаза 2 — Оставить один main.typ
Цель: сделать все ежедневные настройки и #include видимыми в одном файле.
Результат: document.typ, draft.typ и clean-copy.typ отсутствуют; режим выбирается в main.typ.
Трудоёмкость: M
Статус: [x] Готово
Задачи
- Перенести компанию, режим, metadata и порядок глав в
main.typ(→ Рабочее пространство автора) - Сохранить единый фасад импорта (→ Публичный фасад)
- Проверить profile/options contract (→ Документ)
- Сохранить границы организаций, сторон и приложений (→ Организация, Стороны, Приложения)
- Проверить application flow и загрузку компаний (→ Сборка, Ресурсы компаний)
Тесты
- Static: единственный root entrypoint
- Интеграционный:
final,draft,clean-copyчерез profile fixtures - Ручной: порядок глав меняется только списком
#include
Фаза 3 — Открыть документацию и примеры
Цель: дать автору видимую справку и копируемые примеры без чтения реализации.
Результат: docs/ содержит навигацию, четыре полных документа и каталог оформления.
Трудоёмкость: L
Статус: [x] Готово
Задачи
- Разделить публичную и developer-документацию (→ Публичная документация)
- Сделать примеры источником выбора типа документа (→ Публичные примеры)
- Показать таблицы, формулы, подписи и media blocks (→ Компоненты, Основа вёрстки)
- Показать ссылки, bibliography и numbering (→ Ссылки, Нумерация)
- Подготовить адекватные примеры профилей (→ Отчёт, Письмо, ТКП, Договор)
Тесты
- Интеграционный: пять публичных примеров компилируются
- Semantic: ожидаемые подписи, ссылки, приложения и реквизиты присутствуют
- Ручной: весь
docs/доступен из корневого README
Фаза 4 — Упростить VS Code и приватные данные
Цель: оставить одну build task и безопасно подключать папку .private одним параметром.
Результат: выбор типа создаёт backup, обычная сборка работает с private media и без неё, отсутствующая подпись не ломает документ.
Трудоёмкость: M
Статус: [x] Готово
Задачи
- Оставить в Typewriter единственный
main.typи обновить задачи (→ Рабочая область VS Code) - Добавить публичный справочник сотрудников, фиксированные PNG names и private offsets (→ Приватные ресурсы)
- Использовать conditional import при явном
use-private-assets(→ ADR-0010)
Тесты
- Static:
.vscode/синхронизируется,docs/не скрыт - Интеграционный: clean fork компилируется без
.private - Интеграционный: private compile отображает реальные подписи и offsets
- Интеграционный:
enabled: falseоставляет пустую строку без ошибки
Фаза 5 — Hardening и выпуск
Цель: подтвердить отсутствие мёртвых путей, утечек и визуальных дефектов.
Результат: полный harness проходит, Markdown-ссылки валидны, приватные ресурсы игнорируются.
Трудоёмкость: M
Статус: [x] Готово
Задачи
- Обновить static workspace contract (→ Тестирование)
- Удалить скрытые дубликаты примеров и notes (→ Публичная документация)
- Проверить визуально все страницы публичных примеров (→ ADR-0006)
Тесты
- Полный automated harness
- Аудит Markdown links и legacy paths
- Визуальная проверка contact sheets и проблемных страниц