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

Связанные документы: архитектура, клавиши и команды, план разработки, экранный backend P2, результаты P2.1, результаты skeleton P2, результаты файловых панелей P3

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 байта:

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.
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.