From 554c9ed995090c630c231179973879a87d824c71 Mon Sep 17 00:00:00 2001 From: heaven Date: Tue, 4 Aug 2026 16:06:49 +0300 Subject: [PATCH] Sweep frontend zone docs: dated owner-decision amendments in standing prompt, S3 lock marked open and row-95 check retired --- frontend/docs/FRONTEND_SESSION_PROMPT.md | 9 +- frontend/docs/S2_SESSION_PROMPT.md | 113 ----------------------- frontend/docs/S3_SESSION_PROMPT.md | 7 +- 3 files changed, 9 insertions(+), 120 deletions(-) delete mode 100644 frontend/docs/S2_SESSION_PROMPT.md diff --git a/frontend/docs/FRONTEND_SESSION_PROMPT.md b/frontend/docs/FRONTEND_SESSION_PROMPT.md index b452d45e..a5e46cb3 100644 --- a/frontend/docs/FRONTEND_SESSION_PROMPT.md +++ b/frontend/docs/FRONTEND_SESSION_PROMPT.md @@ -51,6 +51,7 @@ **Бэкенда пока нет** — точнее, движок перевода есть, но HTTP-API к нему ещё не построено. Ты работаешь на моках (см. §6). Это не помеха: контракт данных зафиксирован ниже, замена моков на реальные запросы будет точечной. +> ⚠ **Поправка канона №2 (оркестратор, 04.08, D39.99/100/101):** контракт API v0 РАТИФИЦИРОВАН (`docs/architecture/14-api-contract/` — OpenAPI 3.1, типы генерятся из спеки), строка 95 закрыта; скелет платформы P0 существует (ждёт приёмки); слой данных S3 строится ПО КОНТРАКТУ, не по гипотезам. > ⚠ **Поправка канона (фронт-сессия S1, 02.08).** Формулировка выше читается как «однажды у движка появится HTTP-API». Это не так, и ошибка дорогая: **API будет у платформы, не у движка**, а движок фронту не виден вообще. Прежде чем писать слой данных, прочитай `FRONTEND_PLAN.md` §0.1–0.2 (карта канона и два провода) и первоисточник `docs/research/23-engine-platform-seam.md`. Там же цена ошибки: моки, снятые не с того уровня контракта, разойдутся с API — ровно то, ради предотвращения чего заведена строка 95 единого бэклога. --- @@ -138,6 +139,8 @@ ## 2. Раскладка нашего приложения +> ⚠ Раскладка частично устарела — перевешивают «Решения владельца по продукту» в `frontend-PROGRESS.md`; метки глав — из ДАННЫХ книги, зашитого «Глава N» не существует (D39.100 К-3). + Оболочка Fleet, наполнение наше. ``` @@ -189,7 +192,7 @@ Кнопка запуска перевода. Пока идёт: - **у каждой главы в дереве — свой индикатор выполнения** (крутящийся/прогресс), главы обрабатываются не по порядку и это нормально; -- общий прогресс по книге в статус-полосе; +- общий прогресс по книге в статус-полосе (+ ETA: решение владельца 04.08, D39.100 К-5 — поле `eta_seconds` добавит в спеку правка S3, опциональное); - ⚠ **не рассказывать, что происходит внутри.** Никаких «сейчас работает редактор», «идёт добыча глоссария», никаких названий моделей. Пользователь видит «идёт перевод» и прогресс. Всё. ### 3.5. Банк памяти — подпись @@ -246,7 +249,7 @@ ### Решения владельца от 02.08 — приняты, не переоткрывать -8. **Денег в интерфейсе MVP нет вообще.** Ни сумм, ни потолков, ни оценки стоимости до запуска, ни +8. **Денег в интерфейсе MVP нет вообще** (⚠ поправка 04.08, D39.100/ПТ-35: запрет СУММ в силе, но добавлены статус `paused`, оповещение «лимиты исчерпаны» и страница СТАТУСА использования в настройках — без долларов). Ни сумм, ни потолков, ни оценки стоимости до запуска, ни счётчика во время прогона, ни подписки, ни остатка. Оплаты в MVP не будет, показывать нечего. Учёт расхода остаётся внутри движка как телеметрия владельца. Если видишь денежное поле в каком-либо разделе этого промта — это остаток прошлой редакции, его быть не должно. @@ -317,7 +320,7 @@ HTTP-слоя ещё нет. **Весь доступ к данным — чер **Материал для фикстур бери реальный** — китайский текст с русским переводом, имена и термины. Выдуманный «Lorem ipsum» даст неверную плотность: кириллица длиннее латиницы, иероглифы короче всего, и колонки поедут. Пример реального фрагмента лежит в `backend/example/chapter1-zh.txt` (читать можно, править нельзя). -Состояния, которые обязаны быть в фикстурах и нарисованы: книга не начата · разбирается · переводится (первый проход) · ждёт подписи банка · переводится (финал) · готова · остановлена пользователем · отклонена (не удалось разобрать файл) · прервана ошибкой. +Состояния фикстур — по enum `BookStatus` контракта (`docs/architecture/14-api-contract/openapi.yaml`: десять значений; `paused` добавит правка S3 — D39.99/100 К-8); исторический список: книга не начата · разбирается · переводится (первый проход) · ждёт подписи банка · переводится (финал) · готова · остановлена пользователем · отклонена (не удалось разобрать файл) · прервана ошибкой. --- diff --git a/frontend/docs/S2_SESSION_PROMPT.md b/frontend/docs/S2_SESSION_PROMPT.md deleted file mode 100644 index aa3e8f72..00000000 --- a/frontend/docs/S2_SESSION_PROMPT.md +++ /dev/null @@ -1,113 +0,0 @@ -# Промт: фронт-сессия S2 — оболочка трёх панелей и слой `src/ui/` - -Ты — фронтенд-сессия TextMachine, третья по счёту. Зона записи — **только `frontend/`**; -сессия не коммитит — лендит оркестратор (протокол — стоящий промт -`FRONTEND_SESSION_PROMPT.md` §«Зона и git», он в силе целиком). Пре-коммит хук уже стоит -и самоустанавливается при `npm install`: коммит с frontend-путями не пройдёт без зелёного -`npm run check`, смесь зон и файлы «никогда не коммитить» блокируются. Хук — страховка, -не замена дисциплины. - -## Что уже стоит (входное состояние, проверено 02.08 второй сессией) - -- S0 (план) и S1 (инструменты) пройдены: `npm run check` — 5 гейтов (prettier · eslint - тип-осведомлённый · stylelint · tsc · vitest, 31 тест), `npm run check:full` — + сборка + - скриншот с гейтом доступности axe. Всё зелёное, `npm audit` — 0 уязвимостей. -- `tokens.css` сведён с `references/fleet.png` до пикселя по замеренным значениям; - контракт-тест держит каждое значение и полноту имён. -- Витрина `/showcase` — сверочная страница скриншот-цикла; раскладку владелец видел и правил. -- Шов данных: `src/api/` — единственный вход, `src/mock/` видит только он (закреплено линтом); - типы `src/api/types.ts` — рабочая гипотеза до контракта API. -- Гейты «одно место для цвета/размера/сети» работают и защищены от обхода; известные дыры - гейтов честно записаны в `BACKLOG.md` Ф-9/Ф-10 — часть твоей работы. - -## Обязательное чтение до кода (порядок) - -1. `frontend/docs/FRONTEND_SESSION_PROMPT.md` — стоящий промт: референсы §1, сценарий §3, - жёсткие ограничения §4, поддерживаемость §5.1, «как работать» §7. **Его не редактировать** - (правит не фронт-сессия). ⚠ Раскладка его §2 частично устарела — см. следующий пункт. -2. `frontend/docs/frontend-PROGRESS.md` — журнал зоны, целиком. Секция «Решения владельца по продукту» - **перевешивает §2 стоящего промта**: банк памяти живёт в ПРАВОЙ панели (вкладки справа: - `О книге · Замечания · Банк`; слева только `Книги · Поиск` + `Настройки` внизу), вход - в настройки один, центр — одна панель во всю высоту, подписной экран банка открывается - вкладкой в центре. -3. `frontend/docs/FRONTEND_PLAN.md` — §0.1–0.2 (карта канона и два провода: движок фронту - не виден никогда), §5 (замеры и протокол сведения), §5.4 (перечень форм обхода гейтов). -4. `frontend/docs/STACK_DECISIONS.md` — пины и ловушки. Не выбирай библиотеки сам и не - «обновляй» версии по памяти: твои знания об экосистеме устарели. -5. `frontend/docs/BACKLOG.md` — строки Ф-4, Ф-7, Ф-9, Ф-10, Ф-12 адресованы S2. -6. `references/fleet.png` и оба antigravity — **открой и посмотри** (ты умеешь читать - изображения). Витрину `.shots/showcase.png` — тоже, до первой правки. - -## Скоуп S2 — и ни шагом дальше - -Строишь **оболочку** и **примитивы**. Данных S2 не читает (диспозиция Ф-15 — два независимых -скептика подтвердили; не переоткрывать). - -1. **`src/shell/`** — верхняя полоса · три панели · статус-полоса. Панели — `react-resizable-panels` - (пин и API v4 `Group/Panel/Separator` — STACK_DECISIONS §2; там же персист раскладки через - `useDefaultLayout`). Сворачивание левой/правой панели кнопками верхней полосы. Вкладки - в шапках панелей. Раскладка — по решению владельца из frontend-PROGRESS.md (см. выше), не по §2. -2. **`src/ui/`** — примитивы на `react-aria-components` (ЕДИНСТВЕННАЯ библиотека примитивов, - пин в STACK_DECISIONS): кнопка · вкладки · строка дерева/списка · поле фильтра · выноска - замечания. Стили — только `.module.css` на токенах. Никаких UI-китов, никаких обёрток - над обёртками. Файл = компонент + модуль рядом, >150 строк — делить. -3. **Ф-12 (требование к S2, не после):** каждый список получает поведение при 10³ элементов - ДО того, как рисуется. Дерево глав обязано жить на 2284 главах — заведи в витрине - нагрузочную фикстуру такого размера и посмотри на неё скриншотом. Дефолт виртуализации — - RAC Virtualizer; `@tanstack/react-virtual` — только по замеру (Ф-6). -4. **Ф-9 + Ф-10 — хвосты гейтов и структурных тестов, адресованы «до S2 или в ней»:** закрой - или дай строкам явную диспозицию с причиной. Каждую закрытую дыру проверяй ЖИВЫМ нарушением - и перечисли формы, которые проверил (урок §5.4: «проверено» без перечня форм — ловушка). -5. **Ф-7 (часть S2):** `+` в конце рядов вкладок — вместе с действием, которое он запускает. -6. **Ф-4 — токен-гейт на отступы:** включить В КОНЦЕ сессии, когда оболочка обкатает шкалу - `--space-1…6`. Включённый гейт — тоже проверить живым нарушением. - -**Не в скоупе:** MSW и слой данных (S3 — вход заблокирован, см. ниже) · экраны S4–S7 · -светлая тема · мобильная · React Compiler (Ф-2) · Tauri (Ф-5) · редактор текста. - -⚠ **Вход в S3 заблокирован снаружи:** контракта API v0 нет (`docs/architecture/14-api-contract.md` -отсутствует; единый бэклог, строка 95). Моки, снятые не с того контракта, разойдутся с API — -ровно то, ради чего строка заведена. Если S2 закончилась и осталось время — отполируй список -Ф-14 (вход фронта в контракт), но S3 НЕ начинай без решения владельца. - -## Технические рамки - -- Новые зависимости — точными пинами, сверенными live по npm на дату сессии (`.npmrc` уже - держит `save-exact` и `engine-strict`). Каждый новый пин — строкой в таблицу - `FRONTEND_PLAN.md` с датой релиза и «зачем нам». -- Новый маршрут → сразу в `KNOWN_ROUTES` скрипта `scripts/shot.mjs` (тест сверяет списки - и упадёт, если забыл). Каждый экран открывается в изоляции своим маршрутом. -- Гейты не ослаблять. Понадобилось точечное подавление — только именованное правило - с причиной (голое отключение падает само). -- Комментарии — одна-две строки «почему». Имена человеческие, без аббревиатур. -- Тексты фикстур — реальные (кириллица/иероглифы в настоящих пропорциях), объём — минимум - под задачу: вопрос авторского права (В-2) у владельца, не расширяй цитаты. - -## Как работать - -1. **Скриншот-цикл — с первого компонента:** `npm run shot`, открыть PNG, сравнить - с `fleet.png`, править. Без этого код валиден, а вид случаен. Критерий сведения — - не растровое совпадение: цвета, промежутки 8px, радиусы 6px, плотность, впечатление - (стоящий промт §8). -2. **Ревью исполнением — обязательный мандат проекта:** приложение реально запускается, - скриншоты сняты и ПРОСМОТРЕНЫ, гейты проверены живыми нарушениями с перечнем форм, - `npm run check:full` зелёный перед каждым коммитом. Заявление «должно работать» ревью - не является. -3. **Адверсариальная самопроверка перед финишем:** пройди по своим находкам и правкам - с установкой опровергать (author≠reviewer); S1 так поймала пять дефектов в собственных - гейтах, соло-взгляд их не видел. -4. Спорное с каноном или новое продуктовое решение — НЕ решать самому: вопросом в - `frontend-PROGRESS.md` «Открытые вопросы к владельцу» и продолжать то, что вопроса не требует. - -## Готово — это когда - -- Оболочка стоит: три панели · вкладки · статус-полоса · сворачивание · персист раскладки; - примитивы `src/ui/` используются оболочкой, не лежат мёртвым грузом. -- Дерево на 2284 главах прокручивается без затыков и снято скриншотом (Ф-12). -- Ф-9/Ф-10 закрыты или явно диспозиционированы; Ф-4 включён и проверен нарушением. -- `npm run check:full` зелёный; новые маршруты в `shot.mjs`; скриншоты просмотрены, - расхождения с референсом названы вслух. -- Коммиты: только `frontend/`-пути, pathspec-формой, стейдж+коммит одной командой. -- `frontend/docs/frontend-PROGRESS.md`: обновлено «Текущее состояние», добавлена хроника сессии - (что построено · что видно на снимках · где отошёл от референса и почему · что осталось); - строки бэклога получили диспозиции. diff --git a/frontend/docs/S3_SESSION_PROMPT.md b/frontend/docs/S3_SESSION_PROMPT.md index be097942..c765af96 100644 --- a/frontend/docs/S3_SESSION_PROMPT.md +++ b/frontend/docs/S3_SESSION_PROMPT.md @@ -35,11 +35,10 @@ **Проверь сам, промту не верь** (он написан 04.08 и мог устареть): 1. Существует ли `docs/architecture/14-api-contract/` (спека + компаньон)? — **на 04.08 вечера: ДА, ратифицирован (D39.99), замок ОТКРЫТ**; -2. Что говорит строка **95** единого бэклога в `docs/PROGRESS.md` (контракт API v0 + продуктовый - словарь статусов) — она всё ещё «дизайн-промт по слову владельца» или уже исполнена? +2. Строки 95 в таблице единого бэклога больше НЕТ — она ЗАКРЫТА (D39.99, закрытые строки уходят в D-лог); если видишь её живой — дерево старее канона, стоп и пинг. **Открыт** (контракт есть и ратифицирован) → скоуп S3 ниже. -**Закрыт** (на 04.08 — закрыт: файла нет) → раздел «Если замок закрыт». Не начинай S3 «пока +**Закрыт** → раздел «Если замок закрыт» (контингенция; на вечер 04.08 замок ОТКРЫТ — D39.99). Не начинай S3 «пока на своих типах, потом поправим»: моки, снятые не с того контракта, разойдутся с API — ровно то, ради чего строка 95 заведена. @@ -122,7 +121,7 @@ React Compiler (Ф-2) · Tauri (Ф-5). ## Если замок закрыт -Это ожидаемое состояние на 04.08, и правильный ход — не ждать молча и не строить экраны +Контингенция на случай, если проверка замка даст «закрыт» (на вечер 04.08 замок ОТКРЫТ); тогда правильный ход — не ждать молча и не строить экраны на синхронных моках (порядок этапов Ф-1 стоит именно на слое данных). - **Доведи Ф-14 до артефакта, который можно отдать автору контракта:** не список намерений,