Sprinter-SDCC/applications/Volkov/docs/commander-requirements.md

# Sprinter Commander: требования к PoC и границы проекта

Статус: требования PoC зафиксированы; gate P1 и ядро P2.1 пройдены в MAME

Целевая платформа: Sprinter Sp2000, Z80, DSS 1.71.57

Инструментарий: SDCC 4.5, `sprinter-cc`, MAME 0.287 / BIOS 3.06

Связанные документы:
[архитектура](commander-architecture.md),
[клавиши и команды](commander-keymap.md),
[план разработки](commander-roadmap.md),
[экранный backend P2](p2-screen-backend.md),
[результаты P2.1](p2-screen-probe-results.md),
[результаты skeleton P2](p2-skeleton-results.md),
[результаты файловых панелей P3](p3-panel-results.md)

## 1. Назначение документа

Документ фиксирует проверяемые требования к первой работающей версии
файлового менеджера для Sprinter. Рабочее имя проекта — **Sprinter
Commander**, рабочее имя исполняемого файла — `SPRCMD.EXE`.

PoC не является портом Volkov Commander. Это новая программа на C,
повторяющая привычную модель двухпанельного файлового менеджера с учётом
архитектуры памяти и API Sprinter.

## 2. Референсы и правила их использования

### 2.1. Volkov Commander 4.05

Используется как минимальный поведенческий образец:

- компоновка двух панелей;
- клавиатурная навигация;
- назначение функциональных клавиш;
- общий сценарий работы пользователя.

### 2.2. Volkov Commander 4.99

Используется как образец декомпозиции и источник функций для дальнейших
версий:

- отдельные подсистемы панелей, экрана, клавиатуры и диалогов;
- отдельные операции копирования, удаления и изменения атрибутов;
- просмотрщик, редактор, поиск и дерево каталогов;
- описания файлов и архивные панели;
- разделение резидентного ядра и загружаемых частей.

### 2.3. Dos Navigator 1.51

Используется только как архитектурный референс:

- единый цикл событий и команды приложения;
- отделение модели панели от её представления;
- абстракция источника файлов;
- длительные операции с прогрессом и отменой;
- виртуальные панели для архивов и результатов поиска;
- история, конфигурация и внешние инструменты.

Объектная система Turbo Vision, DOS overlays, XMS/EMS-код и прикладные
модули DN не переносятся.

Исходный код, строки интерфейса и ресурсы референсов не копируются без
отдельного решения по лицензированию. Реализация проекта должна оставаться
собственной реализацией по описанному поведению.

## 3. Определения версий

**PoC 0.1** доказывает техническую реализуемость панелей, EMM-хранилища,
экранного буфера, копирования и запуска программ.

**Рабочая версия** пригодна для повседневной работы с файлами и включает
безопасные групповые и рекурсивные операции.

**Полная версия 1.0** соответствует основным возможностям VC 4.99, но не
пытается повторить весь набор утилит Dos Navigator.

## 4. Пользовательский сценарий PoC

После запуска программа переключается в текстовый режим 80x32, выделяет
необходимую память и показывает две панели. Обе панели первоначально
открывают текущий каталог запуска.

Пользователь может:

1. Перемещать курсор по активной панели.
2. Переключать активную панель клавишей `Tab`.
3. Входить в каталог клавишей `Enter`.
4. Возвращаться в родительский каталог.
5. Перечитывать содержимое активной панели.
6. Копировать один обычный файл в каталог пассивной панели.
7. Запускать выбранный `.EXE` и возвращаться в Commander.
8. Выйти по `F10` с освобождением всех ресурсов.

## 5. Компоновка экрана PoC

Экран имеет 80 столбцов и 32 строки.

| Строки | Назначение |
|---:|---|
| 0 | Заголовки и текущие пути обеих панелей |
| 1–27 | Списки файлов, по 27 видимых записей |
| 28 | Итоги панелей: число записей и общий размер |
| 29 | Информация о текущей записи активной панели |
| 30 | Строка состояния, ошибок и прогресса |
| 31 | Подсказки функциональных клавиш |

Левая панель занимает столбцы 0–39, правая — 40–79. Точные символы рамок
и палитра не являются контрактом PoC, но все символы должны корректно
отображаться в CP866.

Renderer задаёт смысловые роли атрибутов независимо от конкретной палитры.
P2.2 подтвердил многоцветные планы в MAME: тема сохраняет исходные записи,
задаёт обе FLASH-пары и восстанавливает палитру при выходе. До аппаратного
подтверждения активная и пассивная панели всё равно различаются не только
цветом, но и глифами/маркерами.

Полная перерисовка выполняется из собственного экранного буфера через
`sc_video`. Commander не использует дескрипторы окон BIOS: панели, меню и
диалоги — логические прямоугольники приложения. `sc_video` выводит их в
координаты глобального экрана через ESTEX/BIOS-функции без идентификатора
окна; прямой доступ к VRAM не используется.
Изменение курсора или одной строки панели не должно требовать повторного
чтения каталога.

Прокрутка списка на одну строку может использовать прямоугольный ESTEX
`SCROLL 55h`, как `mdview2`, но рамка и соседняя панель остаются неподвижны,
а экранный EMM-буфер обновляется синхронно. Эта служба не является BIOS-
дескриптором окна; её аппаратная реализация исходниками `mdview2` не
доказана. Псевдографика задаётся raw-кодами CP866 из единого `sc_glyphs.h`.

## 6. Функциональные требования PoC

### REQ-BOOT: запуск и завершение

- **REQ-BOOT-01.** Программа должна явно установить текстовый режим 80x32.
- **REQ-BOOT-02.** Перед изменением видеорежима и текущего каталога должны
  быть сохранены исходные значения, если DSS позволяет их получить.
- **REQ-BOOT-03.** При штатном выходе освобождаются все EMM-блоки и закрываются
  все открытые файлы.
- **REQ-BOOT-04.** Ошибка инициализации не должна оставлять изменённый
  видеорежим или выделенную память.
- **REQ-BOOT-05.** Если обязательные четыре EMM-страницы выделить нельзя,
  программа выводит понятную ошибку и завершает работу.
- **REQ-BOOT-06.** `F10` в обычном режиме открывает подтверждение выхода;
  положительный ответ запускает штатный cleanup, отрицательный возвращает к
  панелям.

### REQ-PANEL: панели

- **REQ-PANEL-01.** Панели имеют независимые пути, курсор и позицию прокрутки.
- **REQ-PANEL-02.** Активная панель визуально отличается от пассивной.
- **REQ-PANEL-03.** Каталоги отображаются перед обычными файлами.
- **REQ-PANEL-04.** Внутри групп записи сортируются по имени без учёта
  регистра ASCII.
- **REQ-PANEL-05.** Для записи отображаются имя, размер, дата, время и
  атрибут каталога/файла в объёме, который помещается в ширину панели.
- **REQ-PANEL-06.** После перечитывания каталог по возможности сохраняет
  курсор на прежнем имени; если оно исчезло — на ближайшей допустимой
  позиции.
- **REQ-PANEL-07.** Полный scan DSS использует `*.*`; шаблон `*` не считается
  эквивалентным, поскольку не возвращает обычные имена с расширением.
- **REQ-PANEL-08.** Пустой каталог отображается корректно и остаётся
  управляемым.
- **REQ-PANEL-09.** Родительский каталог представлен синтетической записью
  `..`, кроме корня диска.
- **REQ-PANEL-10.** Записи `.` и `..`, возвращённые DSS, не должны
  дублировать синтетическую запись.
- **REQ-PANEL-11.** Во всей линейке 0.1–1.0 панель хранит не более
  640 записей, включая синтетическую `..`. При превышении лимита
  показывается предупреждение; запись за границу EMM-страницы
  запрещена. Многостраничные панели и предел более 640 записей
  относятся только к версии 2.0+.
- **REQ-PANEL-12.** Если DSS завершил `F_FIRST/F_NEXT` кодом 35
  (`TOO_MANY_FILES_IN_DIR`), уже прочитанные записи остаются доступны, а
  последней добавляется красная виртуальная запись `>>> MORE...`. Она
  сообщает о недоступном остатке каталога, не сортируется вместе с файлами
  и не может быть целью файловой операции.

### REQ-NAV: навигация

- **REQ-NAV-01.** Поддерживаются `Up`, `Down`, `PgUp`, `PgDn`, `Home`, `End`.
- **REQ-NAV-02.** `Tab` переключает активную панель без изменения каталогов.
- **REQ-NAV-03.** `Enter` на каталоге открывает его в активной панели.
- **REQ-NAV-04.** `Ctrl+PgUp` и `Backspace` открывают родительский каталог.
- **REQ-NAV-05.** `Ctrl+R` перечитывает активную панель.
- **REQ-NAV-06.** Навигация внутри уже прочитанной панели не обращается к
  файловой системе.
- **REQ-NAV-07.** Операция с активной панелью не должна неожиданно менять
  путь пассивной панели.

### REQ-FS: работа с DSS и путями

- **REQ-FS-01.** PoC работает с именами DOS 8.3. Длинные имена не входят в
  требования до отдельного подтверждения поддержки DSS.
- **REQ-FS-02.** Максимальный внутренний путь — 255 байт плюс завершающий
  ноль.
- **REQ-FS-03.** Склейка пути и имени проверяет переполнение до обращения к
  DSS.
- **REQ-FS-04.** Контекст текущего каталога DSS считается глобальным
  ресурсом. После временной смены каталога модуль обязан восстановить
  ожидаемый каталог приложения.
- **REQ-FS-05.** Одновременно приложение держит не более трёх файловых
  дескрипторов; штатная операция копирования использует два.
- **REQ-FS-06.** Конец перебора каталога отличается от настоящей ошибки
  `fnext()` по `errno` и контексту операции.

### REQ-COPY: безопасное копирование одного файла

- **REQ-COPY-01.** `F5` копирует выбранный обычный файл в текущий каталог
  пассивной панели.
- **REQ-COPY-02.** Копирование каталогов и групп файлов в PoC запрещено с
  явным сообщением.
- **REQ-COPY-03.** Если конечное имя уже существует, PoC отказывается от
  операции и не изменяет существующий файл.
- **REQ-COPY-04.** Данные копируются блоками, а общий размер и позиция имеют
  32-битный тип.
- **REQ-COPY-05.** Поддерживаются файлы больше 64 КБ.
- **REQ-COPY-06.** Целевой файл сначала создаётся под уникальным временным
  именем через семантику `O_EXCL`, после успешного закрытия переименовывается
  в конечное имя.
- **REQ-COPY-07.** При ошибке или отмене временный файл закрывается и
  удаляется.
- **REQ-COPY-08.** Между блоками проверяется `Esc`, а строка состояния
  обновляет прогресс.
- **REQ-COPY-09.** Нулевой файл копируется корректно.
- **REQ-COPY-10.** В PoC сохранение времени и атрибутов файла не обязательно,
  но должно быть предусмотрено в интерфейсе операции.
- **REQ-COPY-11.** Непосредственно перед переименованием временного файла
  конечное имя проверяется повторно. Если оно появилось, операция завершается
  без его изменения.
- **REQ-COPY-12.** Данные между открытыми файлами проходят непосредственно
  через выделенную EMM-страницу, отображаемую в W3. Полноразмерный блоковый
  буфер в W2 и изменяемый буфер внутри банка кода запрещены.
- **REQ-COPY-13.** Начиная с P18 успешно скопированный обычный файл получает
  исходные FAT date/time и атрибуты readonly/hidden/system/archive. Время
  задаётся temp до `close`, атрибуты — конечному имени после commit.
- **REQ-COPY-14.** Начиная с P19 существующий файл обрабатывается policy
  overwrite/skip/rename; варианты overwrite-all и skip-all ограничены одним
  F5. Overwrite использует backup в том же каталоге и rollback при отказе
  commit, а readonly требует явного повторного решения.

### REQ-EXEC: запуск программ

- **REQ-EXEC-01.** `Enter` на имени с расширением `.EXE` запускает программу
  через ESTEX `EXEC`.
- **REQ-EXEC-02.** Перед запуском Commander сохраняет логическое состояние
  панелей и закрывает временные ресурсы операции.
- **REQ-EXEC-03.** После возврата восстанавливаются видеорежим, экран и
  ожидаемый текущий каталог.
- **REQ-EXEC-04.** Активная панель перечитывается после возврата; пассивная
  перечитывается, если запущенная программа могла изменить её каталог.
- **REQ-EXEC-05.** Ошибка загрузки `.EXE` показывается без завершения
  Commander.
- **REQ-EXEC-06.** Обычный файл неизвестного типа в PoC не запускается.

### REQ-UI: сообщения и состояние

- **REQ-UI-01.** Ошибки не выводятся поверх структуры панели случайными
  вызовами `printf`; они проходят через единый модуль сообщений.
- **REQ-UI-02.** Для каждой ошибки показываются действие, имя объекта и
  текст/код ошибки, если они доступны.
- **REQ-UI-03.** `Esc` закрывает сообщение или отменяет текущую длительную
  операцию; в обычном состоянии он не завершает программу.
- **REQ-UI-04.** Неподдерживаемые в PoC функциональные клавиши либо не
  показаны, либо показаны неактивным цветом.
- **REQ-UI-05.** F6 local rename и F7 mkdir принимают только один проверенный
  компонент DOS 8.3; `..`, маркер DSS и неоднозначная группа не передаются
  файловой системе.
- **REQ-UI-06.** Rename обязан проверить отсутствие нового имени до DSS
  `RENAME`, сохранить CWD и восстановить его после успеха или ошибки.
- **REQ-UI-05.** После закрытия сообщения восстанавливается экран из
  логического экранного буфера.

### REQ-MEM: память

- **REQ-MEM-01.** Целевая конфигурация PoC — `--memory big --safe`.
- **REQ-MEM-02.** W2 содержит резидентное ядро, обычные данные, heap и стек;
  банковские функции размещаются в W1; W3 используется только для EMM-
  данных.
- **REQ-MEM-03.** PoC выделяет четыре 16-КБ страницы: две для панелей, одну
  для экранного буфера и одну для рабочей области копирования.
- **REQ-MEM-04.** Прикладной код не хранит указатели в диапазон
  `0xC000–0xFFFF` между вызовами хранилища.
- **REQ-MEM-05.** Любой модуль, временно меняющий W3, восстанавливает прежнюю
  страницу до возврата и до вызова чужого кода.
- **REQ-MEM-06.** Повторное чтение каталогов не выделяет новые блоки.
- **REQ-MEM-07.** Освобождение частично созданного приложения идемпотентно на
  уровне состояния приложения: каждый реально выделенный блок освобождается
  ровно один раз.
- **REQ-MEM-08.** Рабочая EMM-страница копирования принадлежит общему блоку
  `ScApp`; copy job не выделяет и не освобождает её на каждый файл.

## 7. Формат записи каталога PoC

Логический формат записи фиксирован как 24 байта:

```c
typedef struct {
    char     name[13];
    uint32_t size;
    uint16_t date;
    uint16_t time;
    uint8_t  attr;
    uint8_t  flags;
    uint8_t  reserved;
} ScDirEntry;
```

На этапе реализации обязательна compile-time или build-time проверка
`sizeof(ScDirEntry) == 24`.

Флаги PoC:

- `SC_ENTRY_PARENT` — синтетическая запись `..`;
- `SC_ENTRY_SELECTED` — выбор обычной записи в версии 0.2;
- `SC_ENTRY_DSS_LIMIT` — виртуальная запись о недоступном остатке каталога;
- остальные биты должны быть нулевыми.

В одной странице используется не более 640 записей; последние 1024 байта
остаются резервом и не входят в массив записей. Служебное
состояние панели хранится в W2, а не в начале EMM-страницы.

## 8. Нефункциональные требования

- **REQ-NF-01.** Исходный код и комментарии проекта ведутся на русском.
- **REQ-NF-02.** Сборка выполняется штатным `sprinter-cc` без отдельной
  проприетарной цепочки.
- **REQ-NF-03.** После каждого этапа сохраняется отчёт размеров HOME и
  банков; переполнение банка является ошибкой сборки.
- **REQ-NF-04.** Реакция на навигационную клавишу в уже прочитанной панели не
  должна визуально зависать; целевой ориентир в MAME — менее 100 мс.
- **REQ-NF-05.** Операция дольше 500 мс должна показывать состояние или
  прогресс.
- **REQ-NF-06.** Все воспроизводимые дефекты DSS или SDCC подтверждаются
  отдельным тестом, `.asm`, дампом или другим артефактом.
- **REQ-NF-07.** Рабочая версия должна проверяться в MAME и на реальном
  Sprinter; PoC может быть принят по MAME с обязательным последующим
  hardware smoke-test.

## 9. Что не входит в PoC 0.1

- удаление файлов;
- перезапись существующих файлов;
- перемещение и переименование пользователем;
- создание каталогов;
- рекурсивные операции;
- групповое выделение и маски;
- командная строка и история;
- встроенные viewer/editor;
- дерево и поиск;
- архивы и виртуальные панели;
- мышь;
- конфигурационный файл, темы и локализация;
- длинные имена;
- фоновые операции и многозадачность.

## 10. Критерии приёмки PoC

PoC считается завершённым, если одновременно выполнены условия:

1. Программа стабильно запускается в MAME с двухпанельным экраном.
2. Обе панели независимо проходят дерево каталогов и корректно работают с
   пустым каталогом.
3. Хранилище панели проверено синтетическим source на границах 640/641 без
   выхода за EMM-страницу; на DSS 1.71 превышение его границы 512 физических
   FAT-записей даёт управляемый частичный список с красным маркером.
   Оба случая подтверждены MAME-пробами в
   [результатах P3](p3-panel-results.md).
4. Сто последовательных перечитываний и переходов не меняют число свободных
   EMM-страниц.
5. Копируются и побайтно совпадают файлы размеров 0, 1, 4095, 4096, 65535,
   65536 байт и более 1 МБ.
6. Отмена и ошибка записи не оставляют временный файл.
7. Существующий целевой файл никогда не меняется.
8. Тестовый `.EXE` запускается, завершается, после чего Commander полностью
   восстанавливает экран и продолжает работу.
9. Все пути ошибок возвращают приложение в управляемое состояние.
10. На выходе восстановлен видеорежим, закрыты дескрипторы и освобождены
    выделенные EMM-блоки.

## 11. Граница полной версии 1.0

Версия 1.0 должна дополнительно включать:

- групповые и рекурсивные копирование, перемещение и удаление;
- безопасную политику перезаписи;
- сохранение атрибутов и времени;
- независимую для каждой панели сортировку по имени, расширению,
  размеру и дате файла в обоих направлениях;
- переключение дисков;
- командную строку, историю, интерактивный полноэкранный
  режим псевдооболочки по `Ctrl+O` и ассоциации;
- настраиваемую подсветку имён по расширению;
- просмотрщик и редактор, допустимо отдельными `.EXE`;
- меню, диалоги, помощь и конфигурацию;
- быстрый поиск, дерево и поиск файлов;
- информационную и quick-view панели;
- базовую работу с архивами;
- мышь.

Обязательные детали этих функций:

- групповые `+`, `-` и `*` работают только над файлами и не меняют флаг
  каталога, даже если он был установлен отдельным `Insert`;
- `Ctrl+O` не просто скрывает панели, а переключает между ними и
  управляемым полноэкранным режимом командной строки;
- полноэкранный режим и однострочный prompt используют один редактор строки и
  общую историю; внешние `.EXE` запускаются через ESTEX `EXEC`;
- синтетическая `..` всегда первая, каталоги остаются перед файлами,
  а направление применяется внутри этих групп;
- пункт сортировки «дата» использует метку создания/модификации, которую
  реально возвращает файловая система; DSS `F_FIRST/F_NEXT` сейчас даёт
  метку last-write, поэтому отдельный выбор creation не имитируется
  дубликатом даты и требует отдельной платформенной пробы;
- при отсутствии файла цветов каталоги и `..` имеют белый цвет, `.EXE` —
  жёлтый, остальные файлы — светло-серый;
- предел 640 записей не снимается ни одной из этих функций.

Многостраничное/динамическое хранилище панели, межстраничная сортировка и
показ 1024/2048 или неограниченного числа файлов не входят в 1.0 и
резервируются для 2.0+.

Терминал, модем, CD-плеер, форматирование, восстановление дисков, электронная
таблица, игры и многооконный desktop Dos Navigator не входят в определение
Commander 1.0.