# AGENT-GUIDE — карта workspace и как дорабатывать iya.ru platform

> Для агента в новом окне. Companion-документ: **`docs/RESILIENCE-PLAYBOOK.md`**
> (самый важный — как выживать при потерях; грабли и процедуры восстановления).
> Точка правды по статусу: `REWORK-STATE.md §0`; следующий шаг: `§9`;
> история: хвост `WORKLOG.md`.

## 1. Что где лежит (корень Workspace = `/home/user`)

```
/home/user/
├── iya-platform/               # ВЕСЬ проект (repo + .git — история внутри)
│   ├── REWORK-STATE.md         # §0 статус-снапшот, §1 ADR-лог, §5.4 i18n-контракт,
│   │                           # §8 known bugs (B-001..B-005), §9 NEXT STEP + правила 1–11
│   ├── WORKLOG.md              # дневник всех сессий (читать ХВОСТ)
│   ├── CHANGELOG.md            # Keep-a-Changelog; [Unreleased] → release:notes
│   ├── bin/iya                 # CLI: migrate|seed|serve|worker|lint|doctor|version|
│   │                           #      schema:dump|state:dump|release:notes|key:generate
│   ├── src/                    # PHP 8.2, stdlib-only: Core(Config/Container/Bootstrap),
│   │                           # Http(Kernel/Router/Middleware), Web(Controllers/Templates/View),
│   │                           # Domain(Auth/Link/Visit/Swarm/Analytics/Notification/Team/...),
│   │                           # Security(IpUtil/RateLimiter/IpBlockGuard/SsrfGuard/ThreatDetection/...),
│   │                           # Agents(SwarmApiController), Workers(MaintenanceWorker), Api/V1
│   ├── migrations/sqlite/      # 001..008 (MySQL DDL — только 001, остальное sqlite-only)
│   ├── tests/                  # кастомный раннер run.php (483 теста), unit/ + integration/,
│   │                           # bootstrap.php (TestDatabase::fresh/app), TestCase.php (список assert'ов!)
│   ├── scripts/                # sync.sh, pack_p12.sh, pack_p12_quick.sh, backup_i18n.sh,
│   │                           # build_i18n.php, setup-env.sh, dev-router.php,
│   │                           # ДРИЛЛЫ: _beta_journey.py, _p14_edge_check.py, _sec_admin_check.py,
│   │                           # _rbac_check.py и др. (_*_check.py — one-off live-проверки фич)
│   ├── web/i18n/               # _base.en.json (1409 ключей-источник) + _platform.<code>.json
│   │                           # (42 локали) → build_i18n.php ГЕНЕРИРУЕТ <code>.json (руками не править!)
│   ├── public/                 # документ-рут: web/css (tokens/base/components/utilities/rtl),
│   │                           # web/js (app/realtime/tracker), index.php
│   ├── docs/                   # этот файл, RESILIENCE-PLAYBOOK, BETA.md, RELEASE.md, API.md,
│   │                           # I18N-STATUS.md, SCHEMA.md, FILE_MAP.md, ARCHITECTURE.md
│   ├── legacy/iya-ru-source/   # архив оригинального сервиса (lang/*.php — источник тона локалей)
│   ├── .env                    # dev-конфиг (ОТЛЕЖИВАЕТСЯ в git!): ADMIN_REQUIRE_2FA=false,
│   │                           # TARGET_CHECK_BUDGET=0, DEV_ALLOW_HOST_OVERRIDE=true...
│   └── var/                    # runtime (НЕ в архивах): data/iya.sqlite3, logs, cache, test
├── backup/
│   ├── versions/               # свежайший versioned-тарболл (полная история — в /mnt/oss)
│   └── i18n/                   # дубликаты переводов + .milestone-N маркеры
├── P12.tar.gz                  # фазовый архив «всё сделанное» (правило 6, перезаписывается)
├── P12-MANIFEST.md             # его манифест (авто-статус: гейты, покрытие, коммит)
├── IYA-DEV-BUNDLE.tar.gz       # ПОЛНЫЙ бандл для переноса (repo+.git+i18n+гайды+env)
├── AGENT-GUIDE.md              # копия этого файла (видна сразу при входе)
└── RESILIENCE-PLAYBOOK.md      # копия playbook (видна сразу при входе)
```

**Внешние durable-слои:** `/mnt/oss/iya-platform-backups/` (per-commit история +
зеркала P12), `/mnt/oss/iya-i18n/` (переводы), `/mnt/oss/iya-agent-bundle/`
(бандл+гайды), внешняя копия пользователя `https://iya.ru/qwen_access/`.

## 2. Развёртывание (свежая песочница)

```bash
bash /home/user/iya-platform/scripts/setup-env.sh   # apt: php8.2 + расширения (идемпотентен)
cd /home/user/iya-platform
php bin/iya doctor          # самодиагностика
php bin/iya migrate         # schema
php bin/iya seed            # демо-данные (demo@iya.ru / Demo-Password-2026!) — опционально
php bin/iya serve --host=127.0.0.1 --port=8080   # web (php -S, workers=4)
php bin/iya worker --once   # ingest/rollups/outbox/target-checks (в проде — каждую минуту)
```
Если `/home/user` пуст — сначала восстановление из бандла/тарболла по
**RESILIENCE-PLAYBOOK §4** (ветка B), затем эти команды.

**Проверка здоровья (обязательна после любого восстановления):**
```bash
php tests/run.php | tail -2        # сверить с REWORK-STATE §0 (сейчас 483/3109/0)
php bin/iya lint | tail -1         # 223 files / 0 failures
php scripts/build_i18n.php --check # full coverage: 42/66
```
Live-проверка без curl (его нет) — python urllib; паттерны в `_beta_journey.py`.

## 3. Как вести доработку

1. **Прочитать §0 и §9 REWORK-STATE + хвост WORKLOG** — что сделано, что дальше.
2. Работать блоками 15–25 вызовов инструментов; **после каждого блока —
   ритуал чекпоинта** (RESILIENCE-PLAYBOOK §3: гейты → коммит → §0/§9 →
   WORKLOG → sync → pack_p12 → зеркала → trim → du<128M).
3. Крупные файлы писать частями ≤200 строк; JSON-переводы — python
   read-update-write батчами; после правок PHP — `php -l`.
4. Каждая фича: unit-тесты + live-дрель (с откатом состояния!) + полный прогон.
5. Новый конфиг-ключ → ОБЯЗАТЕЛЬНО в `Config::defaults()` (иначе env игнорируется).
6. Новые UI-строки: P12 заморожен — композировать из существующих ключей, либо
   (если разморозят) en-first workflow по §5.4 + перевод на ВСЕ 42 локали.
7. Дриллы перед релизом: `_beta_journey.py` (13), `_p14_edge_check.py` (12),
   `_sec_admin_check.py`, `_rbac_check.py` — см. docs/BETA.md §5.
8. Релиз: docs/RELEASE.md (freeze CHANGELOG → bump Version.php → release:notes
   → tag → sync/pack → docker build).
9. **Правила пользователя (не нарушать):** вопросы не задавать — решения
   принимать самому и писать ADR в §1; архив P12 в корень на каждом чекпоинте;
   в конце каждого раунда отчёт «что осталось + %» (rule 11); дублировать
   артефакты туда, где они не пропадают (правила 8–9, ADR-014).

## 4. Текущий статус и куда двигаться

* **P1–P16 закрыты** (2026-10-18). Платформа релизопригодна.
* Возможные направления (по §9 и BETA.md fix list): пост-релизные follow-ups
  (B-004/B-005, account/*-стабы, rollup read-rewire), возобновление 24
  замороженных локалей (инструкция в §9 P12 FROZEN), релиз 1.0.0, или новая
  задача пользователя.
* Ключевые контракты заморожены: §5.1 visit capture, §5.2 redirect engine,
  §5.3 IP intel, §5.4 i18n. Менять — только через MAJOR-версию (docs/RELEASE.md).

## 5. Среда: чего нет и чем заменять

| Нет | Замена |
|---|---|
| curl | python3 urllib/http.client (готовые хелперы в `scripts/_*.py`) |
| ps / pkill | скан `/proc/[0-9]*/cmdline`; паттерн собирать из частей или `[y]`-trick (иначе kill-петля убьёт собственный шелл) |
| docker (в песочнице) | Dockerfile валидируется в CI (`.github/workflows/ci.yml`) |
| sqlite3 CLI | `php -r 'new PDO("sqlite:...")'` |
| composer (runtime) | не нужен: stdlib-only; тесты несут свой bootstrap |

Часовой пояс контейнера ≠ пользовательский (Asia/Shanghai) — штампы писать
`date -u`, в доках указывать оба времени при необходимости.