From ccd60aea7d65500e3f4d589e67ebf0b22abc0db7 Mon Sep 17 00:00:00 2001 From: lekss361 Date: Mon, 11 May 2026 13:43:15 +0300 Subject: [PATCH] upd readme --- README.md | 95 ++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 76 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index ea4bfc6b..8e9f0d55 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ --- -## Текущий статус (апрель 2026) +## Текущий статус (май 2026) **Live:** [https://gendsgn.ru/](https://gendsgn.ru/) — HTTP/2+HTTP/3, валидный TLS, [/health](https://gendsgn.ru/health) `{"status":"ok"}`. Полный CI/CD: GitHub Actions → GHCR → SSH-deploy на Beget VPS. Sentry активен (release tracking привязан к git-sha). @@ -16,13 +16,16 @@ |---|---| | Аналитический калькулятор `/analytics/recommend` (Tier 3 per-bucket эластичность, кадастр vs рынок) | ✅ | | DOM.РФ kn-API скрейпер (442 строящихся ЖК Свердл, sale_graph + infra + photos) | ✅ Celery beat + admin UI | +| NSPD geo bulk-fetcher (rosreestr2coord lite, без Playwright) | ✅ admin UI с per-target логами | | Rosreestr CSV-сделки 2024Q1—2026Q1 (9 квартирных партиций, 7M строк) | ✅ | | NSPD кадастровые кварталы + здания (709 cad-кварталов, 10 590 cad_buildings ЕКБ) | ✅ Celery beat + admin UI | | OSM ekb_districts_geom (PostGIS-полигоны 8 районов ЕКБ) | ✅ | +| Objective ETL (Anton SQLite → PG, ports на psycopg v3) | ✅ admin UI | +| Obsidian Self-hosted LiveSync vault на `obsidian.gendsgn.ru` (268 entities из KG) | ✅ multi-device sync | | Concept page (`/concept`) — Stage 1 Generative | 🟡 skeleton | | Site Finder (`/site-finder`) — Stage 2 | 🔴 заглушка | -**Подробности и текущий backlog** — [Issues](https://github.com/lekss361/-gendesign/issues), milestones по этапам. +**Backlog:** [GitHub Issues](https://github.com/lekss361/-gendesign/issues) (трекаемые задачи с PR-связью) + [Obsidian vault](https://obsidian.gendsgn.ru) (планы, ADR, research — см. ниже про разделение). --- @@ -53,13 +56,18 @@ curl http://localhost:8000/health # → {"status":"ok","environment":"dev"} Структура монорепо: ``` -backend/ FastAPI app, services (analytics_queries, scrapers, generative, site_finder), workers (Celery) -frontend/ Next.js app router (analytics, admin, concept, site-finder) -data/sql/ ETL артефакты — миграции схемы, загрузчики rosreestr/anton/nspd -ops/ backup.sh + deploy скрипты -docs/ стратегия (снимок) — актуальное состояние в графе памяти -memory/ hardlink на C:\mcp\.aim\memory-gendesign.jsonl (knowledge graph) -.github/workflows/ deploy.yml (build → GHCR → SSH-deploy) +backend/ FastAPI app, services (analytics_queries, scrapers, generative, site_finder), workers (Celery) +frontend/ Next.js app router (analytics, admin, concept, site-finder) +data/sql/ ETL артефакты — миграции схемы, загрузчики rosreestr/anton/nspd +ops/ backup.sh + deploy скрипты +scripts/ утилиты (migrate_kg_to_obsidian.py, setup-couchdb.sh, cleanup_ghosts.py) +docs/ стратегические снапшоты (актуальное knowledge — в Obsidian vault) +memory/ legacy JSONL knowledge graph (deprecated, не обновляется — данные в Obsidian) +docker-compose.prod.yml main стек (backend, frontend, postgres, redis, worker, beat, caddy) +docker-compose.obsidian.yml obsidian-стек (CouchDB) — деплоится отдельно +.github/workflows/ + ├── deploy.yml main → пересборка backend/frontend образов + SSH deploy + └── deploy-obsidian.yml obsidian-стек (CouchDB compose changes + bootstrap) ``` --- @@ -76,7 +84,7 @@ memory/ hardlink на C:\mcp\.aim\memory-gendesign.jsonl (knowledge graph) **Калькулятор `/analytics/recommend`** считает квартирографию (5 size-бакетов) с per-bucket эластичностью через регрессию sale_graph, нормировкой на район/класс/конкурентов, кадастр-vs-рынок cross-check, и инверсным режимом «требуемая цена для срока X мес». -Подробное описание схемы БД, helper-views, FK и 27.04 history — в графе памяти, сущности `Analytics_Dashboard_Apr27`, `DomRF_Lazy_Loaded_Apr27_2026`, `Anton_Imported_Apr27_2026`, `NSPD_Scrape_Complete_Apr30`. См. также `data/sql/*.sql` (DDL артефакты). +Подробное описание схемы БД, helper-views, FK и 27.04 history — в Obsidian vault: `domains/analytics/Analytics_Dashboard_Apr27`, `domains/domrf/events/DomRF_Lazy_Loaded_Apr27_2026`, `events/Anton_Imported_Apr27_2026`, `domains/cadastre/Cad_Quarter_Backfill_Apr30`. См. также `data/sql/*.sql` (DDL артефакты). --- @@ -84,16 +92,24 @@ memory/ hardlink на C:\mcp\.aim\memory-gendesign.jsonl (knowledge graph) **Beget Cloud, Москва, 2 vCPU / 4 GB / 40 GB NVMe.** Стоимость ~1 140 ₽/мес сервер + ~17 ₽/мес домен. -5 контейнеров через `docker-compose.prod.yml`: `postgres` + `redis` + `backend` (FastAPI) + `worker` + `beat` (Celery, Chromium только в worker) + `frontend` + `caddy` (auto-TLS Let's Encrypt). Backend/frontend bind на `127.0.0.1` — наружу только Caddy. +**Два изолированных стека через docker compose, общая Docker network `gendesign_shared`:** + +1. **Main стек** (`docker-compose.prod.yml`, project `gendesign`): + `postgres` + `redis` + `backend` (FastAPI) + `worker` + `beat` (Celery, Chromium только в worker) + `frontend` + `caddy` (auto-TLS Let's Encrypt). Backend/frontend bind на `127.0.0.1` — наружу только Caddy. + +2. **Obsidian стек** (`docker-compose.obsidian.yml`, project `gendesign-obsidian`): + `couchdb:3` — Self-hosted LiveSync remote для multi-device sync vault'а на `obsidian.gendsgn.ru`. Caddy в main-стеке маршрутизирует через `gendesign_shared` network. + +**Split deploy** — изменения в main НЕ перезагружают obsidian (и наоборот). Каждый стек со своим workflow. **SSH-only по ключу к non-root пользователю `gendesign`**, fail2ban активен. UFW: 22/80/443. -**GitHub Actions deploy** ([`.github/workflows/deploy.yml`](.github/workflows/deploy.yml)): -1. Build обоих образов (backend lean + worker-with-chromium + frontend) -2. Push в приватный GHCR -3. SSH `git pull`, пишет `SENTRY_RELEASE=$IMAGE_TAG` в `backend/.env.runtime`, `compose pull && up -d`, `caddy reload`, `curl /health` +**GitHub Actions deploys:** -**GitHub Secrets:** `DEPLOY_HOST`, `DEPLOY_USER`, `DEPLOY_SSH_KEY`, `DEPLOY_PORT`. Сервер авторизуется в GHCR однократно через PAT с `read:packages`. +- [`.github/workflows/deploy.yml`](.github/workflows/deploy.yml) — main: триггер на `backend/**`, `frontend/**`, `Caddyfile`, `docker-compose.prod.yml`. Build backend lean + worker-with-chromium + frontend → push в приватный GHCR → SSH `git reset --hard`, sed `SENTRY_RELEASE=$IMAGE_TAG` в `backend/.env.runtime`, `compose pull && up -d`, `caddy reload`, `curl /health`. +- [`.github/workflows/deploy-obsidian.yml`](.github/workflows/deploy-obsidian.yml) — obsidian: триггер на `docker-compose.obsidian.yml`, `scripts/setup-couchdb.sh`, `docs/obsidian-livesync.md`. Без сборки образов (couchdb:3 с DockerHub), SSH `compose up -d` + idempotent bootstrap (CORS, DB, лимиты). + +**GitHub Secrets:** `DEPLOY_HOST`, `DEPLOY_USER`, `DEPLOY_SSH_KEY`, `DEPLOY_PORT`. Сервер авторизуется в GHCR однократно через PAT с `read:packages`. `COUCHDB_USER`/`COUCHDB_PASSWORD` — в `backend/.env.runtime` на VPS (не в репе). **Триггеры миграции на Yandex Cloud:** 3-й платящий пилот / Раунд А / госзаказ (нужен реестр ПО) / БД >10 GB / >50 RPS. На YC ~10–15 тыс ₽/мес. @@ -127,9 +143,49 @@ memory/ hardlink на C:\mcp\.aim\memory-gendesign.jsonl (knowledge graph) **2 фуллстек-разработчика, part-time 20 ч/нед**, ритм: 1 синк/нед, daily-async в Telegram, PR-review обязательный, trunk-based. Codegen TS-типов из Pydantic — `npm run codegen`. -Все решения, факты, KPI, протоколы валидации хранятся в **графе памяти** (`memory/memory-gendesign.jsonl`, hardlink на `C:\mcp\.aim\memory-gendesign.jsonl`), не в .md-документах. Правило (`Feedback_MemoryFirst`): источник правды = граф, документы = снимки. Синхронизация между коллегами — через git pull/push. +### Knowledge base — Obsidian vault -**Подключение коллеги к knowledge-graph** ([#11](https://github.com/lekss361/-gendesign/issues/11)) — пошаговая инструкция в issue. +**Источник правды** — Obsidian vault на `obsidian.gendsgn.ru` (Self-hosted LiveSync + CouchDB). Markdown-файлы с `[[wiki-links]]`, MOC-страницами, Graph View и тегами. Multi-device sync: desktop / laptop / iPhone / Android. **268 entities** мигрированы из исторического JSONL knowledge graph (`scripts/migrate_kg_to_obsidian.py`), который теперь deprecated. + +Структура vault: +- `meta/` — гайды, credentials, project meta (Project_GenDesign, TechStack, NorthStar) +- `domains/{domrf,cadastre,rosreestr,analytics,ui,api,geo,infra}/` — knowledge по бизнес-доменам +- `code/{modules,schemas,patterns,hooks,tasks}/` — code-level entities +- `decisions/` — ADR / планы / политики +- `fixes/` — bug-журналы +- `sessions/`, `sprints/`, `events/` — chronological logs +- `research/`, `sources/`, `feedback/`, `github/`, `limitations/` — прочее +- `old/` — архив legacy paths (redirect-stubs) + +**Подключение коллеги** — гайды в самом vault'е: +- `meta/01_connect_devices.md` — установка Obsidian + LiveSync на любую платформу (через Setup URI или 4 поля) +- `meta/03_obsidian_plugins.md` — какие плагины ставить (Local REST API, Templater, Dataview) +- `meta/04_mcp_obsidian_setup.md` — подключение Claude к vault через MCP + +**Legacy:** старый knowledge graph JSONL (`memory/memory-gendesign.jsonl`) — снапшот на момент 2026-05-11, не обновляется. Все новые факты пишутся в Obsidian. + +### Где вести задачи — GitHub Issues vs Obsidian + +Используем **оба**, но с чёткой ролью: + +| | GitHub Issues | Obsidian vault | +|---|---|---| +| Что сюда | Bug + Feature + Refactor — всё с **связью с кодом / PR** | Knowledge: research, ADR, planning, draft-ideas | +| Lifecycle | Open → Assigned → PR → Merged → Closed | Append-only журнал решений и контекста | +| Уведомления | GitHub email/mobile + integrations | Никаких (читаешь когда сам пришёл) | +| Поиск | GitHub search + labels + milestones | BM25 + tags + Graph + MOC | +| Видимость | Команде в reviewer'ах | Всем у кого есть vault password | +| Сроки | Milestones (12-week roadmap) | Frontmatter `date:`, `status:`, `due:` | + +**Правило перехода:** Obsidian `fixes/Bug_X.md` со `status: OPEN` → когда требует PR — создаём **GitHub Issue**, ссылку прописываем во frontmatter `.md` (`github_issue: 42`). Bug-исследование живёт в vault'е, action item — в Issues. + +**Что куда:** + +- `Bug_*` (vault) + GitHub Issue с тегом `bug` → обнаружен баг, фикс через PR +- `decisions/*` (vault) — ADR, не нужен GitHub Issue +- `research/*` (vault) — анализ источников, конкуренты, метрики +- `sessions/*` (vault) — журналы рабочих сессий +- GitHub Issues `feat/*` — фичи + PR на 1+ files, видимые в milestones --- @@ -140,9 +196,10 @@ memory/ hardlink на C:\mcp\.aim\memory-gendesign.jsonl (knowledge graph) | 🌐 Production | https://gendsgn.ru/ | | 🩺 Health | https://gendsgn.ru/health | | 📚 OpenAPI | https://gendsgn.ru/openapi.json · [Swagger UI](https://gendsgn.ru/docs) | +| 🗂 Knowledge vault | https://obsidian.gendsgn.ru (требуется Obsidian + Self-hosted LiveSync, см. vault `meta/01_connect_devices.md`) | | Backlog | [Issues](https://github.com/lekss361/-gendesign/issues) · [Milestones](https://github.com/lekss361/-gendesign/milestones) | | Деплой | [GitHub Actions](https://github.com/lekss361/-gendesign/actions) · [GHCR пакеты](https://github.com/lekss361?tab=packages) | | Мониторинг | [Sentry](https://qqq-5y.sentry.io/insights/projects/gendesign-backend/) | | Инфра | Beget VPS [`cp.beget.com/cloud/...`](https://cp.beget.com/cloud/servers/jolly-yakov-3) · [DNS](https://cp.beget.com/dns/14193206) | -**Стратегические документы (снимки):** [`docs/MVP_Goals_Python.md`](docs/MVP_Goals_Python.md), [`docs/Бизнес-план v2.1 - Site Finder + Roadmap 12 месяцев.md`](docs/). При расхождении с графом — доверяем графу. +**Стратегические документы (снимки):** [`docs/MVP_Goals_Python.md`](docs/MVP_Goals_Python.md), [`docs/Бизнес-план v2.1 - Site Finder + Roadmap 12 месяцев.md`](docs/), [`docs/obsidian-livesync.md`](docs/obsidian-livesync.md). При расхождении с vault'ом — доверяем vault'у.