API Contracts

ثلاث endpoints: القائمة (paginated، filterable)، التفاصيل، و endpoint تحديث founder-led (مُسَوَّر بالملكية). إضافة إلى endpoint بلاغ الإشراف (أيّ مستخدم يَستطيع تَعليم ملف founder-led للمراجعة).

1 · GET /api/founders — القائمة

• Query params: q · country (csv) · sector (csv) · role (csv) · verified (bool) · flavor (all|editorial|founder-led) · sort (most-relevant|newest|alphabetical|most-mentioned) · page · pageSize · lang.
• الاستجابة: { items: FounderListItem[]، totalCount، page، pageSize، filters: { applied، available }، counts: { total، verified، founderLed، editorial } }.
• FounderListItem: { id، slug، displayName، headline، role، country {code,name}، avatarUrl، isVerified، flavor، startupThumbnails[<=3]، totalStartups، mentionCount }.
• Cache: public، max-age=180، s-maxage=300، stale-while-revalidate=900. أبطل عند نشر/تحديث Founder.

2 · GET /api/founders/{slug} — التفاصيل

• Path: slug. Query: lang.
• الاستجابة: { ...Founder كامل، bio، skills[]، languages[]، startups[] (مع الدور + التواريخ)، speakingHistory[]، coverageMentions[]، filesAuthored[]، editorialArticlesAuthored[]، relatedFounders[]، seo {metaTitle، metaDescription، jsonLd}، isOwnerView (محتسبة من auth) }.
• كل مصفوفة related-entity مَحدودة جانب-الخادم بـ 12؛ القوائم الكاملة متاحة عبر /api/founders/{slug}/speaking?offset=12 إلخ.
• Cache: 300s public + 900s s-maxage. أبطل عند تحديث Founder أو أيّ تغيير رابط cross-module يَلمس هذا Founder.

3 · PATCH /api/founders/{id} — تحديث founder-led

• Auth: مطلوب. التفويض: viewer.userId يجب أن يُساوي Founder.OwnerUserId و Founder.Flavor === 'founder-led'. 403 خلاف ذلك.
• الـ Body: حقول Founder جزئية (DisplayName، Headline، Bio، AvatarUrl، LinkedInUrl، TwitterUrl، PersonalSiteUrl، إلخ). متغيّر Lang مُحَدَّد بـ ?lang param.
• الخادم: يُنشئ لقطة نسخة في جدول FounderVersion. نافذة استرداد 90 يوم. الاستجابة: شكل Founder المُحَدَّث + versionId.
• حد المعدّل: 10 PATCH/مؤسّس/ساعة (مكافحة التخريب).

4 · POST /api/founders/{id}/report — علم إشراف

• Auth: اختياري (تَقارير مجهولة مسموحة لتقارير الانتحال).
• الـ Body: { reason: 'impersonation' | 'inaccurate' | 'offensive' | 'spam' | 'other'، notes?: string }.
• الخادم: يُدرج في طابور إشراف admin (§10.4). محدود-المعدّل لكل IP.