119 lines
11 KiB
Markdown
119 lines
11 KiB
Markdown
# preland#22 — план реализации единой админки
|
||
|
||
Спецификация: ../specs/2026-10-25-preland22-admin-design.md; основной реестр preland#22.
|
||
Владелец 25.10 поручил выполнение командой до production без повторного подтверждения.
|
||
Метод: writing-plans, dispatching-parallel-agents для независимых файловых областей,
|
||
TDD, систематическая диагностика при сбоях, независимое review и verification-before-completion.
|
||
Работа в уже изолированном wt/preland21; исходные checkout/ветки не переключаются.
|
||
|
||
**Цель:** безопасно редактировать поля runtime-конфигов и публиковать indpic на выбранных доменах.
|
||
**Архитектура:** отдельное PHP-приложение admin/, прямые local/SFTP+SSH-адаптеры,
|
||
приватный файловый реестр/очередь заданий, повторное использование CPanel indpic UI/валидатора.
|
||
**Стек:** PHP8.3, phpseclib3, Imagick/ZIP, Apache, отдельный CLI-worker, Docker, nginx/TLS.
|
||
Python используется в инструментах QA/инфраструктуры, Yii2 — источник совместимого контракта,
|
||
новые прикладные микросервисы без функциональной причины не добавляются.
|
||
|
||
## Общие ограничения и карта поверхности
|
||
|
||
- Русский интерфейс/документация, все поля config через формы, JSON-editor отсутствует.
|
||
- Четыре начальные цели, произвольный дальнейший реестр; .online кроме stage не включать.
|
||
- Изменения только выбранных полей/целей, конфликты версий, резерв вне webroot,
|
||
атомарная публикация и повторное чтение, статусы/повтор каждой цели независимо.
|
||
- Секреты только вне Git/webroot; ключ root приложению не передаётся.
|
||
- indpic1–9, ZIP и 90файлов проверяются действующим валидатором CPanel.
|
||
- Сохранить runtime config и /N/ при кодовом deploy; guard runtime проверяет контракт,
|
||
а статические ресурсы остаются привязаны к manifest Git.
|
||
- Все зависимости/тесты в Docker. Browser plugin not available: реальный UI в Docker Playwright.
|
||
- Карта UI: login, домены/подключения, настройки/доп.поля, выбор целей/полей,
|
||
задания/частичный успех/конфликт/повтор, резерв/восстановление, indpic ZIP/SFTP/default.
|
||
|
||
## Общий HTTP-контракт для независимой реализации
|
||
|
||
Все ответы JSON: {ok:true,...} либо {ok:false,error:"понятный текст"}; безопасные HTTP-коды.
|
||
POST/PUT/DELETE требуют header X-CSRF-Token после login; multipart также использует header.
|
||
- POST /api/login {username,password}; GET /api/state → {csrf,user,targets}; POST /api/logout.
|
||
- targets имеют id,name,domain,environment,type(local|sftp),host,port,user,root,host_key,
|
||
enabled,has_secret; сервер никогда не возвращает secret/private_key.
|
||
- POST /api/targets {target:{...},secret?:string}; DELETE /api/targets {id};
|
||
POST /api/targets/test {id} проверяет подключение и безопасные пути.
|
||
- GET /api/config?target=id → {config,version,warnings,sets}; version=SHA256 текущего файла.
|
||
- POST /api/apply {targets:[{id,version}],changes:[{path:[string...],value:any,delete?:bool}]}
|
||
→ {job}; версии каждой цели берутся её собственным чтением, не от исходного домена.
|
||
- GET /api/jobs?id=id → {job}; без id → {jobs}; POST /api/jobs/retry {id,targets:[id...]} → {job}.
|
||
job={id,status,results:[{target,status,message,version?}],...}; статусы queued,running,
|
||
success,error,conflict,unknown; статус задания queued,running,completed.
|
||
- GET /api/backups?target=id → {backups:[{id,created_at}]};
|
||
POST /api/restore {target,id,version} → {job}.
|
||
- GET /api/sets?target=id → {sets:[{number,name,exists,default,in_use}],version};
|
||
POST /api/sets/upload multipart file,number,name,targets(JSON-массив id) → {job};
|
||
POST /api/sets/check {targets:[id],number} → {job}; POST /api/sets/register аналогично +name;
|
||
POST /api/sets/name {target,number,name}; POST /api/sets/delete {target,number};
|
||
default задаётся /api/apply по path utm/indpic/default и текущей version.
|
||
Технические расширения контракта допустимы с синхронизацией агентов и записью в #22.
|
||
|
||
## Задача 1 (#22): серверная логика и файловый контракт
|
||
|
||
Владелец: backend (Yii2 senior/PHP senior, security/transport).
|
||
Файлы: admin/src/*, admin/public/index.php, admin/bootstrap.php,
|
||
admin/bin/*, admin/composer.json/lock, admin/tests/backend*.php; не менять UI/Docker/CI.
|
||
|
||
- [ ] RED: выбранный patch сохраняет поля/типы, чужая версия не затирается,
|
||
массовая ошибка одной цели не откатывает другие, резерв восстанавливается по версии.
|
||
- [ ] Реализовать auth/CSRF, защищённый реестр соединений, транспорт local и SFTP/SSH,
|
||
серверные задания/worker, конфиги/валидацию/историю и HTTP-контракт выше.
|
||
- [ ] Перенести IndpicSetStorage с атрибуцией; проверять ZIP до доставки, затем хеши,
|
||
публикацию/откат; регистрацию SFTP-набора, имена/default/удаление из реестра.
|
||
- [ ] GREEN в Docker, реальные подключения через локальную SFTP-цель, auth/error/race/ZIP tests.
|
||
|
||
## Задача 2 (#22): интерфейс на основе CPanel
|
||
|
||
Владелец: frontend senior, дизайнер, верстальщик.
|
||
Файлы: admin/views/dashboard.php, admin/public/assets/*, admin/tests/ui*.cjs.
|
||
Вход public/index.php рендерит dashboard.php для обычных URL; API выше.
|
||
|
||
- [ ] Форма входа, домены, редактор всех config-полей и UTM, один/несколько выбранных
|
||
доменов и только изменённые поля; версии до редактирования, без silent overwrite.
|
||
- [ ] Таблица/действия indpic копируют CPanel, включая ZIP/SFTP и понятное окно проверки.
|
||
- [ ] Подключения/история/резерв, задания/частичные ошибки/повтор, loading/error/recovery;
|
||
безопасный текстовый вывод любых серверных полей, desktop/mobile/keyboard.
|
||
- [ ] Реальные browser сценарии login→чтение→ввод→выбор2целей→применить→reload;
|
||
ошибка/восстановление/ZIP; сохранить screenshot и console evidence вне repo.
|
||
|
||
## Задача 3 (#22): runtime guard и доставка
|
||
|
||
Владелец: DevOps/QA (независимо от admin/).
|
||
Файлы: bin/release-assets.php, новый bin/check-runtime-sets.php, tests/check-runtime-sets.php,
|
||
.gitea/workflows/deploy.yml, AGENTS.md/CLAUDE.md/README.md только относящиеся части.
|
||
|
||
- [ ] RED: корректно заменённый runtime-набор не требует Git; повреждённый активный
|
||
набор/невалидный default выявляется; общая проверка статики не ослабевает.
|
||
- [ ] Изменить --stage-sets/--remote на контрактную проверку runtime /N/ и manifest
|
||
только кода/поставляемых ресурсов; admin/ и приватные файлы не входят в preland releaseFiles.
|
||
- [ ] GREEN в Docker + старые preland tests/manifest; документация обновляет #11 явно.
|
||
|
||
## Задача 4 (#22): интеграция, инфраструктура и приёмка
|
||
|
||
Владелец: ведущий агент (Senior DevOps/Linux/Windows, QA и release).
|
||
Файлы: admin/Dockerfile, admin/compose.yaml, admin/deploy/*, admin/README.md,
|
||
локальные output/preland22/*; KB Спеки/Планы/Инфраструктура и индекс.
|
||
|
||
- [ ] Создать образ/локальный стенд и SSH/SFTP fixture, запустить backend/guard тесты.
|
||
- [ ] Реальный UI-клик в Docker Playwright 1440/390: все общие состояния и контракты
|
||
из спецификации, с отдельными read/save/conflict/partial/retry/ZIP свидетельствами.
|
||
- [ ] Независимое review всего diff; исправить существенные замечания, повторить
|
||
затронутые сценарии, подготовить rollback и неизменяемую версию образа.
|
||
- [ ] Настроить admin.zoomstage.online DNS/TLS/nginx, ограниченные local mount/SFTP
|
||
доступы, секреты в приватном состоянии, отдельный worker; текущий трафик не прерывать.
|
||
- [ ] Проверить на установленной админке вход/чтение всех4целей, реальный безопасный
|
||
write/read/ZIP/error/recovery с возвратом исходных runtime; никаких ложных PASS.
|
||
- [ ] Опубликовать код и KB, занести итог/проверки/версии/ограничения в #22, закрыть
|
||
только после завершения. Неисполненные обязательные сценарии оставить открытыми.
|
||
|
||
## Особое внимание review
|
||
|
||
1. Разные версии/типы/legacy-alias четырёх файлов и потеря неизвестных полей — тест задачи1.
|
||
2. Таймаут после фактической записи/обновление страницы — задания/повтор задачи1+2.
|
||
3. Повреждённый ZIP/размер/traversal/лимит/ошибка активации — задача1 и UI задачи2.
|
||
4. Подмена пути/host key, утечка пароля, CSRF/сессия и незавершённые задания — задача1/4.
|
||
5. Runtime-изменения не должны блокировать выпуск или публиковать admin-секреты — задача3/4.
|