git flow, infra descriptions, cast flow changes (mobile side)

docs/OPEN_API.md

@@ -0,0 +1,76 @@
+# Crash console — open ingest API (design)
+
+Triage **real device crashes** vs **synthetic / bulk test traffic** when exposing upload or query APIs beyond the Android app. Builds on RBAC ([`examples/crash_reporter/backend/README.md`](../examples/crash_reporter/backend/README.md)).
+
+## Problems
+
+- Load tests and CI may POST many similar JSON blobs → drown signal in the reports list.
+- Third-party integrations need stable auth and filters without console login cookies.
+- Similarity grouping already uses payload fingerprints; need **provenance** to exclude known harness traffic.
+
+## Payload extension (ingest)
+
+Add optional top-level fields on upload (backward compatible):
+
+| Field | Type | Meaning |
+|-------|------|---------|
+| `ingest.source` | string | `device` (default), `open_api`, `ci`, `manual` |
+| `ingest.client_id` | string | Stable id per API key or CI job |
+| `ingest.run_id` | string | Correlates a burst of reports from one test run |
+
+Android app omits these (defaults to `device`). Harness sets `open_api` + `run_id`.
+
+Store in DB:
+
+- Column `reports.ingest_source` (indexed) **or** JSON path in `payload_json` with generated column later.
+- Prefer column for list filters and MariaDB permissions story.
+
+## Upload API (`POST …/api/upload.php`)
+
+Phases:
+
+1. **Phase A (now):** Accept extra JSON fields; persist inside `payload_json`; console search includes `ingest.source` in blob.
+2. **Phase B:** API key header `X-Crash-Api-Key` → maps to `company_id` (RBAC); rate limit per key.
+3. **Phase C:** Reject or quarantine when `ingest.source=open_api` and fingerprint matches org blocklist.
+
+## Console / query API (read)
+
+Thin JSON endpoints (session or API key):
+
+| Endpoint | Purpose |
+|----------|---------|
+| `GET /api/reports?ingest_source=device` | Default triage view |
+| `GET /api/reports?ingest_source_ne=open_api` | Hide harness |
+| `GET /api/reports?group=fingerprint&min_count=N` | Bulk duplicate detector |
+| `GET /api/reports/{id}` | Detail (existing shape) |
+
+UI: filter chips on reports toolbar — **Devices only** / **Include API traffic** / tag `synthetic`.
+
+## Classifying synthetic traffic (heuristics)
+
+Mark report or tag `synthetic` when any:
+
+- `ingest.source` in (`open_api`, `ci`) **and** user has not promoted it.
+- Same `ingest.run_id` + fingerprint count > threshold in 10 minutes.
+- Identical `report_id` prefix pattern from known test fixture.
+
+Manual: console **Clear synthetic tag** / **Promote to real** on detail page.
+
+## Security
+
+- API keys scoped to `company_id`; no cross-tenant list.
+- Separate write-only keys for CI upload vs read keys for dashboards.
+- Log upload failures to existing crash event log; no stack traces in response body.
+
+## Android
+
+No change required for v1. Optional later: dev setting to set `ingest.source=manual` for dogfood builds.
+
+## Implementation order
+
+1. Document fields; parse and store in payload (Phase A).
+2. List filter `ingest_source` in `ReportRepository` + UI chip.
+3. API keys table + `X-Crash-Api-Key` on upload.
+4. Grouped bulk endpoint for duplicate review.
+
+See also [CRASH_REPORTER.md](CRASH_REPORTER.md) and `examples/crash_reporter/ROADMAP.md`.