Refactor code structure and optimize performance across multiple modules

2026-08-14 16:42:12 +05:00
parent 503eccfb87
commit 8288f9eeb7
2308 changed files with 1185 additions and 180079 deletions
@@ -0,0 +1,67 @@
+# API reference
+
+The **authoritative, always-current** reference is the generated OpenAPI spec:
+
+- Swagger UI — `http://localhost:8080/swagger-ui.html`
+- Raw spec — `http://localhost:8080/v3/api-docs`
+
+The documents here add what a generated spec cannot: payload semantics, field meanings,
+worked examples and frontend integration notes. Where a document and the running
+service disagree, **the service is correct** — please fix the document.
+
+## Authentication
+
+Every endpoint except health and public assets expects a JWT issued by the KonturAI
+auth service:
+
+```
+Authorization: Bearer <token>
+```
+
+This service validates the signature and reads the user id, email and roles from the
+claims; it does not issue tokens. See [authentication.md](authentication.md).
+
+## Documents
+
+| Document | Endpoints | Covers |
+| --- | --- | --- |
+| [authentication.md](authentication.md) | — | Extracting user identity from the JWT |
+| [marketing-analysis.md](marketing-analysis.md) | `/api/marketing/analysis`, `/api/marketing/v3` | Analysis generation and the full field reference |
+| [marketing-strategy.md](marketing-strategy.md) | `/api/marketing/analysis` | Promotion strategy generation |
+| [strategy-execution.md](strategy-execution.md) | `/api/marketing/analysis` | Launching and tracking a strategy |
+| [posting-tasks.md](posting-tasks.md) | `/api/marketing/analysis` | Scheduling and managing social posts |
+| [social-media-credentials.md](social-media-credentials.md) | `/api/social-media/credentials` | Storing per-user network credentials |
+| [image-generation.md](image-generation.md) | `/api/marketing` | Generating post imagery |
+| [research-reports.md](research-reports.md) | `/api/parser/report` | Research report generation and history |
+| [chart-rendering.md](chart-rendering.md) | — | Rendering chart JSON embedded in reports |
+
+## Endpoints without a dedicated document
+
+Use Swagger UI for these:
+
+| Base path | Controller | Purpose |
+| --- | --- | --- |
+| `/api/parser/health` | `HealthCheckController` | Liveness |
+| `/api/parser/items` | `MarketItemController` | Ingested news corpus |
+| `/api/parser/admin/parsers` | `ParserAdminController` | Trigger/inspect RSS parsers |
+| `/api/targeting` | `AiTargetingSystemController` | AI targeting recommendations |
+| `/api/marketing/targeting` | `TargetingCampaignController` | Campaign targeting |
+| `/api/facebook/config` | `FacebookConfigController` | Facebook app/page config |
+| `/api/facebook/leads` | `FacebookLeadsController` | Collected hot leads |
+| `/api/facebook/webhook` | `FacebookWebhookController` | Facebook webhook receiver |
+| `/api/openai` | `OpenAITestController` | OpenAI connectivity diagnostics |
+
+## Versioning
+
+Marketing analysis exists in three generations — v1/v2 under `/api/marketing/analysis`
+and v3 under `/api/marketing/v3` — kept side by side so older frontend builds keep
+working. **v3 is the current path for new integrations.**
+
+Superseded revisions of these documents are preserved in
+[../archive/api-history/](../archive/api-history/).
+
+## Errors
+
+All errors are rendered by `GlobalExceptionHandler`, so the payload shape is consistent
+across endpoints. Validation failures return `400` with per-field detail; a missing or
+invalid token returns `401`.