Ճարտարապետություն և API պայմանագիր Փուլ 1

Մոդուլային մոնոլիտ՝ ըստ ՏՏ-ի խորհուրդի․ մեկ ծրագր, հստակ սահմանված մոդուլներ, որոնցից յուրաքանչյուրը հետագայում կարելի է անջատել ծառայության։

1․ Ճարտարապետություն

SPA (React/Vue) + Admin SPA→ Nginx / LB→ REST API + WebSocket→ PostgreSQLRedisS3 (MinIO)

API-ի մոդուլները՝ auth · companies · listings · search · offers · orders · documents · messaging · notifications · billing · admin · audit։ Առանձին worker-ներ՝ email/push ծանուցումներ, ժամկետանց հայտերի արխիվացում, (Փ4) ավտոմատ համապատասխանեցում։

Բաղադրիչ	Ընտրություն (առաջարկ)	Հիմնավորում
Backend	NestJS (Node) կամ Django REST	հասուն RBAC/ORM էկոհամակարգ, մոդուլային կառուցվածք
Բազա	PostgreSQL 16	ACID, jsonb, լիատեքստային որոնում, enum-ներ
Հերթ/քեշ	Redis	worker առաջադրանքներ, rate-limit, WebSocket presence
Ֆայլեր	S3-համատեղելի (MinIO)	փակ bucket + ստորագրված ժամանակավոր URL-ներ
Frontend	React/Vue SPA + առանձին admin bundle	նույն API-ն, տարբեր դերեր
Deployment	Docker Compose → VPS/cloud	app, worker, db, redis, minio, nginx

2․ API սկզբունքներ

Բազային ուղի՝ /api/v1, JSON only, camelCase դաշտեր։
Նույնականացում՝ Authorization: Bearer <access>, access 15 ր, refresh 7 օր ռոտացիայով, ընտրովի 2FA։
Էջավորում՝ ?page=1&limit=20 → { "data": [...], "meta": { "page", "limit", "total" } }։
Ֆիլտրեր/տեսակավորում՝ ?from=AM&to=RU&date_from=…&sort=-published_at։
RBAC middleware ամեն endpoint-ի համար․ դեր + company_id պատկանելություն, այլապես 403 COMPANY_MISMATCH։
Idempotency՝ Idempotency-Key հեդեր՝ վճարումների POST-երի համար։
Rate limit՝ 100 հարց/ր/օգտատեր, login՝ 10/ր/IP։
WebSocket՝ /ws՝ իրադարձություններ offer.new, order.updated, message.new, notification.new։

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "weight_kg must be a positive integer",
    "details": [ { "field": "weight_kg", "rule": "positive" } ]
  }
}

3․ Endpoint-ների պայմանագիր

Auth և պրոֆիլ

Մեթոդ	Ուղի	Դեր	Նկարագրություն
POST	`/auth/register`	հյուր	գրանցում + email հաստատում
POST	`/auth/login`	հյուր	JWT զույգ, audit LOGIN
POST	`/auth/refresh`	հյուր	refresh ռոտացիա
POST	`/auth/logout`	օգտատեր	refresh-ի չեղարկում
POST	`/auth/password-reset`	հյուր	վերականգնման հղում
GET / PATCH	`/me`	օգտատեր	սեփական պրոֆիլ, լեզու

Ընկերություններ

Մեթոդ	Ուղի	Դեր	Նկարագրություն
POST	`/companies`	օգտատեր	ստեղծում → status pending
GET / PATCH	`/companies/{id}`	անդամ / company_admin	դիտում / խմբագրում
POST	`/companies/{id}/documents`	company_admin	հիմնադիր փաստաթղթեր
POST / GET	`/companies/{id}/members`	company_admin	հրավեր, դերերի կառավարում
GET	`/companies/{id}/ratings`	բոլոր	վարկանիշների ցանկ
POST	`/admin/companies/{id}/verify`	platform_admin	verify / reject պատճառով

Բորսա և որոնում

Մեթոդ	Ուղի	Դեր	Նկարագրություն
POST	`/cargo`	shipper/both	բեռի հայտ → active
GET	`/cargo`	բոլոր	ֆիլտրեր, էջավորում, sort
GET / PATCH / DELETE	`/cargo/{id}`	տիրոջ ընկերություն	քարտ / խմբագրում / հեռացում
POST	`/cargo/{id}/pause \| activate`	տիրոջ ընկերություն	կարգավիճակի կառավարում
POST / GET / …	`/vehicles…`	carrier/both	նույն հավաքածուն՝ մեքենաների համար
GET	`/search/cargo · /search/vehicles`	բոլոր	օպտիմիզացված որոնում՝ <300ms p95

Առաջարկներ և բանակցություններ

Մեթոդ	Ուղի	Դեր	Նկարագրություն
POST	`/cargo/{id}/offers`	carrier/both	գնային առաջարկ, notification.new
GET	`/cargo/{id}/offers`	տիրոջ ընկերություն	ստացված առաջարկներ
POST	`/offers/{id}/messages`	կողմեր	բանակցություն, status→negotiating
POST	`/offers/{id}/accept`	տիրոջ ընկերություն	→ order ստեղծում, listing→booked
POST	`/offers/{id}/reject \| withdraw`	կողմեր	մերժում / հետկանչ

Պատվերներ

Մեթոդ	Ուղի	Դեր	Նկարագրություն
GET	`/orders`	կողմեր	միայն իր պատվերները
GET	`/orders/{id}`	կողմեր / admin	ամբողջական քարտ
POST	`/orders/{id}/status`	ըստ անցման աղյուսակի	վալիդ անցում → history + ծանուցում
GET	`/orders/{id}/history`	կողմեր / admin	կարգավիճակների պատմություն
POST / GET	`/orders/{id}/documents`	կողմեր / admin	վերբեռնում, ներբեռնում՝ ժամանակավոր URL
POST	`/orders/{id}/rating`	կողմեր, completed-ից հետո	1–5 + comment, unique(order, from)
POST	`/orders/{id}/dispute`	կողմեր	վիճարկում → admin հերթ

Հաղորդագրություններ, ծանուցումներ, վճարումներ

Մեթոդ	Ուղի	Դեր	Նկարագրություն
GET	`/conversations · /conversations/{id}/messages`	մասնակիցներ	զրույցներ, չատ
GET / POST	`/notifications · /notifications/{id}/read`	օգտատեր	in-app ծանուցումներ
GET	`/plans`	բոլոր	պլանների ցանկ
POST	`/subscriptions`	company_admin	բաժանորդագրություն
POST	`/payments/intents`	company_admin	Idempotency-Key պարտադիր
POST	`/webhooks/payments/{provider}`	provider (ստորագրությամբ)	կրկնակի մշակման պաշտպանություն

Admin Panel

Մեթոդ	Ուղի	Դեր	Նկարագրություն
GET	`/admin/stats`	platform_admin	dashboard ցուցանիշներ
GET / PATCH	`/admin/users`	platform_admin	ցանկ, block/unblock
GET	`/admin/companies?status=pending`	platform_admin	ստուգման հերթ
GET / PATCH	`/admin/listings`	platform_admin	մոդերացիա
GET	`/admin/orders`	platform_admin	բոլոր պատվերները, disputes
GET / PUT	`/admin/settings`	platform_admin	համակարգային կարգավորումներ
GET	`/admin/audit`	platform_admin	աուդիտի մատյան, ֆիլտրերով
GET	`/admin/reports/export?type=…&format=csv`	platform_admin	արտահանում (Փ4)

4․ Կարգավիճակների enum-ներ

Enum	Արժեքներ և թույլատրելի անցումներ
`order_status`	created→confirmed→in_transit→delivered→completed․ cancelled՝ created/confirmed-ից․ disputed՝ ցանկացածից (admin որոշմամբ վերադարձ)
`offer_status`	new→negotiating→accepted\|rejected\|withdrawn
`listing_status`	active↔paused→booked→(completed)→archived․ expired՝ job-ով․ removed՝ admin
`company_status`	pending→verified\|rejected (rejected-ից վերաստուգում հնարավոր է)
`payment_status`	pending→succeeded\|failed, succeeded→refunded

5․ Deployment և .env.example (ուրվագիծ)

DATABASE_URL=postgres://…        REDIS_URL=redis://…
JWT_SECRET=…                     ACCESS_TTL=15m
S3_ENDPOINT=…  S3_BUCKET=…       S3_KEY=…  S3_SECRET=…
SMTP_HOST=…  SMTP_USER=…         SMS_API_KEY=…
PAYMENT_PROVIDER=stripe          PAYMENT_API_KEY=…
APP_URL=https://serversource.us  WS_URL=wss://…

Փուլ 2-ի սկզբում այս պայմանագրից կգեներացվի OpenAPI 3.1 spec (Swagger UI-ով), իսկ frontend-ը կկապվի իրական API-ին՝ նախատիպի էկրանները մնալով անփոփոխ։