# مرجع API

پایه: `/api` — همه‌ی پاسخ‌ها JSON و همه‌ی پیام‌های خطا فارسی‌اند.

## قالب خطا

```json
{ "error": "CONTENT_LOCKED", "message": "مهلت ۱۰ روزه ویرایش این خبر پایان یافته است.", "details": null }
```

| کد HTTP | معنا در این سامانه |
|---|---|
| `401` | احراز هویت نشده |
| `403` | مجوز یا دامنه‌ی دسترسی کافی نیست (شامل خطای CSRF) |
| `404` | یافت نشد |
| `422` | داده‌ی نامعتبر یا گذار غیرمجاز یا دلیل اصلاح غایب |
| `423` | محتوا قفل شده است (قانون ۱۰ روزه) |
| `429` | عبور از سقف نرخ درخواست |

## احراز هویت — `/api/auth`

| متد | مسیر | توضیح |
|---|---|---|
| `POST` | `/register` | ثبت‌نام شهروند؛ نقش `citizen` خودکار |
| `POST` | `/login` | ورود؛ کوکی نشست + کوکی CSRF |
| `POST` | `/logout` | ابطال نشست در سرور |
| `POST` | `/refresh` | تمدید نشست |
| `GET` | `/me` | وضعیت نشست، نقش‌ها و مجوزهای مؤثر |

## عمومی — `/api`

| متد | مسیر | توضیح |
|---|---|---|
| `GET` | `/home` | بسته‌ی کامل صفحه اصلی در یک درخواست |
| `GET` | `/news` | فهرست اخبار؛ `page, pageSize, category, contentType, organizationId` |
| `GET` | `/news/:slug` | خبر + نسخه‌ها + اصلاحیه‌ها + مرتبط‌ها + وضعیت قفل |
| `GET` | `/organizations` | `type, regionId, verified` |
| `GET` | `/organizations/:slug` | سازمان + ادارات + خدمات + کانال‌ها + کارنامه |
| `GET` | `/businesses`, `/businesses/:slug` | کسب‌وکارها + شعب + شاخص‌های قابل اثبات |
| `GET` | `/guilds`, `/guilds/:slug` | اصناف |
| `GET` | `/statistics`, `/statistics/:slug` | مجموعه‌داده و نقاط آن |
| `GET` | `/statistics/:slug/compare?a=&b=` | مقایسه دو سری با روش‌شناسی |
| `GET` | `/reports` | پرونده‌های عمومی؛ `status, organizationId` |
| `GET` | `/reports/:caseCode` | پرونده با اعمال کامل قواعد حریم خصوصی |
| `GET` | `/map?layers=` | `organizations, departments, businesses, cases` |
| `GET` | `/timeline` | `organizationId` یا `caseId` یا `topic` |
| `GET` | `/explore/city/:slug`, `/explore/organization/:slug` | داده‌ی صحنه‌ی کاوش |
| `GET` | `/taxonomies?kind=`, `/regions` | داده‌های مرجع |

## جست‌وجو — `/api/search`

| متد | مسیر | توضیح |
|---|---|---|
| `GET` | `/` | ساده و پیشرفته (پارامترها در `docs/06-search.md`) |
| `GET` | `/autocomplete?q=` | تکمیل خودکار |
| `GET` | `/trending` | عبارت‌های پرجست‌وجو (داده‌ی واقعی) |
| `GET` `POST` `DELETE` | `/saved`, `/saved/:id` | جست‌وجوهای ذخیره‌شده |

## تحریریه — `/api/editorial/articles`

| متد | مسیر | توضیح |
|---|---|---|
| `GET` | `/` | میز کار؛ خبرنگار فقط خبر خودش را می‌بیند |
| `GET` | `/:id` | خبر + نسخه‌ها + رویدادها + `canEditNow` |
| `POST` | `/` | ایجاد پیش‌نویس |
| `PATCH` | `/:id` | ویرایش — **`423` اگر قفل باشد** |
| `POST` | `/:id/corrections` | اصلاحیه رسمی (`reason` و `note` الزامی) |
| `POST` | `/:id/transition` | گذار گردش کار |
| `DELETE` | `/:id` | حذف نرم — خبر منتشرشده مسدود |
| `GET` `POST` | `/moderation/comments`, `/moderation/comments/:id` | بررسی دیدگاه |

## گزارش مردمی — `/api/civic`

| متد | مسیر | توضیح |
|---|---|---|
| `POST` | `/reports` | ثبت گزارش (سقف ۱۲ در ساعت) |
| `GET` | `/reports/mine` | پیگیری گزارش‌های خود کاربر |
| `GET` `POST` | `/moderation/reports`, `/moderation/reports/:id` | صف بررسی |
| `POST` | `/moderation/routing/preview` | پیش‌نمایش مسیریابی بدون اعمال |
| `GET` | `/org/:organizationId/dashboard` | فضای کاری سازمان |
| `GET` | `/org/:organizationId/cases` | پرونده‌های سازمان |
| `POST` | `/cases/:id/assign` | ارجاع به کارشناس/اداره |
| `POST` | `/cases/:id/status` | گذار وضعیت |
| `POST` | `/cases/:id/responses` | ثبت پاسخ رسمی |
| `POST` | `/cases/:id/reopen` | بازگشایی (دلیل الزامی) |
| `POST` | `/cases/:id/tasks`, `PATCH /tasks/:id` | وظایف داخلی |
| `POST` | `/org/:organizationId/messages` | پیام رسمی بین‌سازمانی |
| `POST` | `/org/:organizationId/channels` | افزودن کانال ارتباطی |
| `POST` | `/channels/:channelId/send` | ارسال با **وضعیت واقعی تحویل** |
| `GET` `PATCH` | `/business/:businessId/dashboard`, `/business/:businessId` | فضای کاری کسب‌وکار |

## کاربر — `/api/me`

| متد | مسیر |
|---|---|
| `PATCH` | `/profile` |
| `GET` `POST` `DELETE` | `/bookmarks`, `/bookmarks/:articleId` |
| `GET` `POST` `DELETE` | `/follows` |
| `GET` `POST` | `/notifications`, `/notifications/:id/read` |
| `GET` `POST` | `/reading-history` |
| `POST` | `/comments` (نیازمند تأیید ناظر پیش از انتشار) |

## مدیریت — `/api/admin`

| متد | مسیر | مجوز لازم |
|---|---|---|
| `GET` | `/overview` | `analytics.view` |
| `GET` `POST` `DELETE` | `/users`, `/users/:id/roles`, `/users/:id/roles/:userRoleId` | `user.manage` |
| `GET` | `/roles` | `role.manage` |
| `POST` | `/organizations/:id/verify`, `/businesses/:id/verify` | `organization.verify` / `business.verify` |
| `GET` `POST` `PATCH` | `/routing-rules`, `/routing-rules/:id` | `routing.manage` |
| `POST` | `/taxonomies` | `taxonomy.manage` |
| `GET` | `/audit` | `audit.view` |
| `GET` | `/analytics` | `analytics.view` |
| `POST` | `/maintenance/reindex` | `search.manage` |
| `POST` | `/maintenance/sla-sweep`, `/maintenance/editorial-lock` | `settings.manage` |
| `GET` | `/system/health` | `analytics.view` |
| `GET` `PUT` | `/settings`, `/settings/:key` | `settings.manage` |

## رسانه — `/api/media`

| متد | مسیر | توضیح |
|---|---|---|
| `POST` | `/upload` | اعتبارسنجی با Magic Number؛ `422` در صورت عدم تطابق |
| `GET` | `/file/*` | سرو امن با محافظت Path Traversal |