59 lines
5.2 KiB
Markdown
59 lines
5.2 KiB
Markdown
# Сверка с дорожной картой
|
||||
|
|
|
|||
|
|
Дорожная карта — единственный трекер задач команды: https://locshare.ru/roadmap/
|
|||
|
|
AI-ассистент **только читает** её. Изменения в карту вносят люди через интерфейс; ассистент готовит для них текст (блок «Для дорожной карты», `PROTOCOL.md`, раздел 5).
|
|||
|
|
|
|||
|
|
## Основной способ
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
node tools/roadmap-context/roadmap-context.mjs # текущий шаг, статусы задач, последние изменения
|
|||
|
|
node tools/roadmap-context/roadmap-context.mjs 2 # обзор шага 2
|
|||
|
|
node tools/roadmap-context/roadmap-context.mjs 2.11 # задача полностью: описание, вопросы и ответы, решение, пункты, обсуждение, ссылки
|
|||
|
|
node tools/roadmap-context/roadmap-context.mjs --all # всё подробно (много текста, только при подведении итогов шага)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
План (`data.js`) берётся из `roadmap/data.js` в репозитории, если файл есть, иначе с сервера. Если локальная копия отличается от сервера, скрипт выводит предупреждение — сообщи об этом пользователю. Прогресс всегда берётся с сервера.
|
|||
|
|
|
|||
|
|
Переменные окружения (задаются локально, в git не попадают):
|
|||
|
|
|
|||
|
|
| Переменная | По умолчанию | Назначение |
|
|||
|
|
|---|---|---|
|
|||
|
|
| `ROADMAP_URL` | `https://locshare.ru/roadmap` | Адрес roadmap-server |
|
|||
|
|
| `ROADMAP_AUTH` | — | `логин:пароль` для Basic Auth, когда на сервере включён пароль |
|
|||
|
|
| `ROADMAP_DATA` | `roadmap/data.js` | Путь к локальному плану |
|
|||
|
|
|
|||
|
|
## Что проверять
|
|||
|
|
|
|||
|
|
В начале сессии:
|
|||
|
|
- текущий шаг (`meta.current`) и есть ли задача сессии в этом шаге;
|
|||
|
|
- статус задачи и исполнители: не делает ли её уже другой человек;
|
|||
|
|
- ответы на вопросы `В1…Вn` и поле «Решение» — это решения команды, они обязательны к исполнению;
|
|||
|
|
- незакрытые сообщения «Блокер» и «Вопрос» по задаче;
|
|||
|
|
- «свои пункты» команды — работа, которой нет в плане, но она согласована.
|
|||
|
|
|
|||
|
|
Расхождения, о которых нужно сказать пользователю:
|
|||
|
|
- в коде/журнале пункт сделан, а в карте не отмечен (или наоборот);
|
|||
|
|
- решение в карте противоречит ADR или коду;
|
|||
|
|
- задача «В работе» у другого человека, а мы её трогаем;
|
|||
|
|
- работа идёт по задаче вне текущего шага.
|
|||
|
|
|
|||
|
|
## Как устроены данные (для разбора вручную)
|
|||
|
|
|
|||
|
|
| Запрос | Что возвращает |
|
|||
|
|
|---|---|
|
|||
|
|
| `GET {ROADMAP_URL}/api/health` | `{"revision": N}` — номер ревизии, растёт при каждом изменении |
|
|||
|
|
| `GET {ROADMAP_URL}/api/progress` | JSON `shtil-roadmap-progress/2` — работа команды |
|
|||
|
|
| `GET {ROADMAP_URL}/roadmap/data.js` | Содержание плана: `window.SHTIL_ROADMAP = { meta, areas, types, phases[].steps[].tasks[] }` |
|
|||
|
|
|
|||
|
|
Разделы `progress`: `members` (id → имя, роль), `tasks` (статус `todo/doing/review/done/blocked`, `assignees`, `priority`, `due`), `items` (ID пункта → `done`), `decisions` (статус `open/discuss/accepted/postponed`, `text`), `answers` (ключ `<задача>~<номер вопроса>`), `comments` (`task`, `kind`: `comment/question/proposal/blocker/decision`, `resolved`, `deleted`), `notes`, `custom` (свои пункты), `links`.
|
|||
|
|
|
|||
|
|
**Запрещено:** `POST /api/ops` и любые другие запросы на запись, правка `progress.json`, перенумерация ID в `data.js`.
|
|||
|
|
|
|||
|
|
## Если сервер недоступен
|
|||
|
|
|
|||
|
|
1. Попросить пользователя: «Настройки → Сводка для AI» → скопировать и вставить в чат (или скачать `.md`).
|
|||
|
|
2. Работать по `roadmap/data.js` и `docs/status/*`, явно предупредив, что статусы могут быть устаревшими.
|
|||
|
|
|
|||
|
|
## Раскрытие следующего шага
|
|||
|
|
|
|||
|
|
В конце шага пользователь передаёт ассистенту «Сводку для AI» и комментарий. Ассистент обновляет `roadmap/data.js` по правилам из шапки файла: новые пункты получают следующий свободный номер, «свои пункты» из `custom` переносятся в план новыми ID, `meta.current` и `meta.changelog` обновляются. Это отдельный PR `docs(roadmap): …`.
|