Add Cursor agent guidance for MapMil platform development.

Introduce AGENTS.md, platform rule, and add-parser-adapter skill for contracts-first adapter workflow. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-14 12:44:06 +03:00
parent 8fbabd3c11
commit 0543694c1e
3 changed files with 291 additions and 0 deletions
@@ -0,0 +1,49 @@
+---
+description: MapMil platform architecture, boundaries, and agent workflow
+alwaysApply: true
+---
+
+# MapMil Platform
+
+Monorepo: **ЦА** (analytics) + **ЦП** (parsing) + **contracts** + **ПИ** (distribution API).
+
+## Data flow
+
+```
+CA admin → Redis cp:jobs:{family} → CP adapter → POST /internal/ingest → CA DB → map / ПИ
+```
+
+| Center | Path | Role |
+|--------|------|------|
+| ЦА API | `centers/analytics/api/` | FastAPI, ingest, scheduler, admin |
+| ЦА UI | `centers/analytics/frontend/` | Vue + Leaflet admin |
+| ЦП | `centers/parsing/workers/` | Adapter registry, batch + Telegram listener |
+| Contracts | `contracts/` | Shared schemas — change first |
+
+## Hard boundaries
+
+- ЦП **never** touches CA database — only `POST /internal/ingest` and `PATCH /internal/jobs/{id}`
+- `source_type` events must match adapter type; stable `source_url` required (CA dedup)
+- `source_config` validated via `contracts/sources.py` on admin CRUD
+- Telegram session: `data/telegram.session` — local only, **never commit**
+- `.env` and secrets — **never commit**
+
+## CP adapter model
+
+Each `source_type` implements `SourceAdapter.run(job_id, source_config, *, ctx) -> tuple[list[dict], str | None]`.
+
+Output dicts are `IngestEventItem`-shaped. Routing: `contracts/queues.py` (`SOURCE_FAMILY` → `cp:jobs:{telegram|web|nlp}`).
+
+Worker images: `cp-workers` (telegram), `cp-workers-web` (crawl4ai), `cp-workers-nlp` (viina).
+
+## Agent workflow
+
+1. **Contracts first** if data shape or routing changes
+2. **One zone per task** — do not mix contracts + UI + infra in one unfocused change
+3. **Follow existing adapters** — copy `viina.py` or `telegram.py`, not greenfield
+4. **Do not touch** Telegram listener unless explicitly asked
+5. **Verify**: `docker compose config`, then targeted service rebuild
+
+Docs: `README.md`, `centers/parsing/ARCHITECTURE.md`, `AGENTS.md`.
+
+For new `source_type`: use skill `add-parser-adapter`.