TikTok Intelligence Platform

منصة SaaS لتحليل حسابات TikTok بالذكاء الاصطناعي، موجهة للمبدعين والستريمرز والوكالات وشركات التسويق. المنصة تخدم منتجين في نفس الموقع:

1. TikTok Profile Analyzer — أي زائر يدخل يوزر TikTok ويحصل على تقرير احترافي شامل (إحصائيات، تحليل AI، قوة الحساب، نقاط قوة/ضعف، فرصة الوصول لـ For You، تحليل جمهور ومنافسين).
2. Agency CRM & Recruitment — بعد التحليل، الحسابات المؤهلة تتلقى عرض انضمام لوكالة TikTok LIVE. الطلبات تدخل مباشرة إلى CRM داخلي لإدارة المتقدمين والتوظيف.

النظام مصمم كمنصة قابلة للتوسع (Multi-Provider) بحيث يمكن لاحقًا إضافة Instagram وYouTube وKick وTwitch كمصادر بيانات إضافية دون تغيير المعمارية.

لغة المنصة

العربية (RTL) هي اللغة الافتراضية والأساسية للمنصة بالكامل — ليست لغة مضافة أو ثانوية. الإنجليزية متاحة كلغة ثانوية عبر مبدّل لغة. التفاصيل الكاملة في docs/16_UI_UX.md.

لماذا هذا المشروع مختلف عن "بيع API"

المشروع لا يبيع بيانات لمطورين. هو منتج نهائي (End-user Product) يقدّم قيمة مباشرة للمبدع (تقرير عن حسابه) وفي نفس الوقت يعمل كقناة توظيف واكتساب مبدعين لوكالة البث المباشر. الـ API الداخلي أداة تنفيذية فقط، وليس منتجًا يُباع.

هيكل الوثائق

TikTok Intelligence Platform
│
├── docs/                           ← حزمة التصميم الكاملة (Software Design Specification)
│   ├── 01_PROJECT_OVERVIEW.md
│   ├── 02_BUSINESS_REQUIREMENTS.md
│   ├── 03_FUNCTIONAL_REQUIREMENTS.md
│   ├── 04_NON_FUNCTIONAL_REQUIREMENTS.md
│   ├── 05_SYSTEM_ARCHITECTURE.md
│   ├── 06_TECH_STACK.md
│   ├── 07_DATABASE_DESIGN.md
│   ├── 08_API_SPECIFICATION.md
│   ├── 09_AI_ANALYSIS_ENGINE.md
│   ├── 10_TIKTOK_DATA_ENGINE.md
│   ├── 11_ANALYTICS_ENGINE.md
│   ├── 12_AGENCY_CRM.md
│   ├── 13_AUTH_SYSTEM.md
│   ├── 14_ADMIN_PANEL.md
│   ├── 15_USER_DASHBOARD.md
│   ├── 16_UI_UX.md                 ← يتضمن معيار العربية الافتراضية + التصميم العالمي
│   ├── assets/
│   │   └── ui-design-reference.png ← مرجع بصري (موودبورد 9 شاشات: ثيم داكن + Gradient وردي-بنفسجي)
│   ├── 17_SECURITY.md
│   ├── 18_DEPLOYMENT.md
│   ├── 19_TESTING.md
│   └── 20_PROJECT_ROADMAP.md
│
├── prompts/                        ← برومبتات جاهزة للتنفيذ عبر Opencode
│   ├── master_prompt.md            ← البرومبت الرئيسي (يُعطى أولًا، دائمًا)
│   ├── phase_01.md … phase_08.md   ← برومبت لكل مرحلة تنفيذ
│
├── run-opencode-pipeline.sh        ← سكربت يشغّل كل المراحل بالترتيب عبر opencode CLI
└── README.md                       ← هذا الملف

طريقة التشغيل مع Opencode

هذا المشروع مُعد للتشغيل على سيرفر (Ubuntu) عبر opencode CLI. الخطوات:

1. انقل مجلد المشروع كاملاً (بما فيه docs/ وprompts/ وrun-opencode-pipeline.sh) إلى السيرفر.
2. تأكد أن opencode مثبت ومسجّل دخول (opencode auth login) على السيرفر.
3. من داخل مجلد المشروع على السيرفر:

   chmod +x run-opencode-pipeline.sh
   ./run-opencode-pipeline.sh
   

4. السكربت يعطي master_prompt.md أولًا (يوجّه Opencode لقراءة كل docs/ قبل أي كود)، ثم يمرّ على phase_01.md حتى phase_08.md بالترتيب، ويتوقف بعد كل مرحلة لمراجعتك قبل المتابعة (Phase Gate).
5. أي تعديل على المعمارية أو قاعدة البيانات يجب أن يُحدَّث أولًا في ملفات docs/ ذات الصلة، ثم يُطلب من Opencode تنفيذه — وليس العكس.

مبدأ أساسي بخصوص البيانات

النظام لا يعتمد على بيانات مسربة أو غير مصرح بها. مصادر البيانات المعتمدة:

• بيانات عامة يمكن الوصول إليها بشكل مشروع (Public data ضمن حدود الاستخدام المسموح).
• بيانات يُدخلها المستخدم بنفسه.
• تحليلات وخوارزميات داخلية (AI/Heuristics) لتوليد مؤشرات وتوصيات تقديرية.

حقول مثل بلد المنشأ، تاريخ إنشاء الحساب، نسبة الوصول للـ Explore/For You، قوة الحساب، ونقاط الضعف هي مؤشرات تقديرية محسوبة، وليست بيانات رسمية من TikTok، ويجب أن تُعرض للمستخدم دائمًا مع توضيح "تقديري" (Estimated). التفاصيل الكاملة في docs/09_AI_ANALYSIS_ENGINE.md وdocs/10_TIKTOK_DATA_ENGINE.md.

استثناء ذلك هو دولة تسجيل الحساب عندما تكون بيانات اعتماد TikTok Research API المصرح بها مضبوطة عبر TIKTOK_RESEARCH_CLIENT_KEY وTIKTOK_RESEARCH_CLIENT_SECRET. عندها يستخدم النظام حقل الفيديو الرسمي region_code، ويحفظ مصدر النتيجة كي لا يعرضها كتخمين. من دون هذه الصلاحية يقرأ النظام locationCreated من صفحات الفيديو العامة ويعتمد الدولة الأكثر تكرارًا كدولة تسجيل الحساب. وإذا لم يتوفر الحقل أيضًا، يستخدم الاستنتاج التقديري من النص والهاشتاغات.

تصنيف الحساب في بث TikTok LIVE مثل C1 وA3 وS يُقرأ من حقل Creator League الحقيقي في بيانات LIVE (ClassInfo.classType أو Gift Gallery class_type) ولا يُحسب من عدد المتابعين أو التفاعل. يدعم النظام الحمولة العامة عندما يعرضها TikTok، ويمكن ضبط مفتاح TIKTOOL_API_KEY على الخادم للحصول على Gift Gallery الحقيقية حتى عندما يكون الحساب غير متصل. يجب أن تدعم خطة المفتاح البيانات الحقيقية؛ يرفض النظام تلقائيًا استجابات Sandbox التجريبية ذات is_sample: true حتى لا يعرض تصنيفًا وهميًا.

أما رقم الحساب الذي يظهر داخل LIVE مثل level: 23 فهو مستوى المستخدم/الهدايا pay_grade.level (وقد يظهر مستوى المنشئ في بعض الحمولات باسم webcast_anchor_level.level). يعرضه التقرير تحت "معلومات حساب LIVE" ولا يخلطه مع Creator League. يستخرج النظام رقم غرفة LIVE من SIGI_STATE، ثم يستخدم مسار TikTok المباشر /api-live/user/room إذا لم تعرض صفحة HTML معلومات الغرفة، ثم يقرأ pay_grade.level من حمولة الغرفة العامة. TikTok يعيد pay_grade.level: 0 للطلبات العامة في كثير من الحالات؛ عندها يلزم مصدر موقّع أو جلسة TikTok مصرح بها لإظهار الرقم الحقيقي، ولا يقوم النظام بتخمينه. مفاتيح TIKTOOL_API_KEY وTIKHUB_API_KEY اختيارية لمسارات إثراء إضافية وليست مطلوبة للمسار المباشر.

الاسم المؤقت للمشروع

TikTok Intelligence Platform

تشغيل Vercel مع جهاز دائم للـ Workers

إذا كانت الحسابات وقاعدة البيانات على جهاز الشركة، مع الاحتفاظ برابط Vercel للزوار، اتبع إعداد الربط المشفّر بين Vercel والسيرفر المحلي. هذا الوضع يستخدم اتصالًا صادرًا من الجهاز ولا يحتاج فتح منافذ الراوتر. أما الإعداد التالي فهو للتركيب الذي تكون فيه قاعدة البيانات وRedis مستضافين خارجيًا.

يمكن نشر واجهة Next.js وواجهات /api على Vercel، وتشغيل عمال BullMQ على جهاز الشركة المتصل بالإنترنت طوال الوقت. يجب أن يشترك الطرفان في نفس PostgreSQL وRedis؛ لا تستخدم localhost في متغيرات Vercel، ولا تفتح المنفذين 5432 أو 6379 على الراوتر.

التركيب الموصى به هو PostgreSQL مُدار (مثل Neon أو Supabase) وRedis مُدار (مثل Upstash) من Vercel Marketplace، ثم ضبط DATABASE_URL وREDIS_URL نفسيهما في Vercel وفي ملف .env.worker على جهاز الشركة. بهذه الطريقة يتصل الـ worker باتصال صادر فقط، ولا يحتاج Vercel إلى الوصول إلى شبكة الشركة الخاصة.

على جهاز الشركة:

cp .env.worker.example .env.worker
# عدّل DATABASE_URL وREDIS_URL وNEXT_PUBLIC_APP_URL
# غيّر ALLOW_LOCAL_SERVICES إلى false عند استخدام الخدمات المُدارة
docker compose -f docker-compose.worker.yml run --rm --entrypoint sh worker -lc \
  "./node_modules/.bin/prisma migrate deploy"
docker compose -f docker-compose.worker.yml up -d --build
docker compose -f docker-compose.worker.yml logs -f worker

يجب أن يكون REDIS_URL رابط Redis مباشرًا يبدأ بـ redis:// أو rediss://، وليس رابط Upstash REST. استخدم TLS (rediss://) عندما يقدمه مزود الخدمة. اختر منطقة PostgreSQL وRedis قريبة من منطقة Vercel ومن موقع جهاز الشركة، واسمح بعنوان IP الخاص بالشركة في إعدادات المزود إذا كانت لديه قائمة سماح. ينفّذ الـworker فحص صحة دوريًا ويعيد التشغيل تلقائيًا عند التعطل، ويتوقف بشكل منظّم عند تحديث الحاوية حتى لا يقطع مهمة جارية.

بعد ضبط متغيرات Vercel، نفّذ migrations مرة واحدة من جهاز الشركة ثم اختبر:

curl -fsS https://YOUR-DOMAIN/api/health
curl -fsS -X POST https://YOUR-DOMAIN/api/analyze \
  -H 'content-type: application/json' \
  --data '{"provider":"tiktok","username":"tiktok"}'

بعد تشغيل الـ worker، يضيف /api/analyze المهمة إلى Redis من Vercel، يلتقطها جهاز الشركة، ويحفظ النتيجة في PostgreSQL؛ مسار الحالة والتقرير يعملان من Vercel كالمعتاد. لا تضع أسرار قاعدة البيانات أو Redis في GitHub أو داخل NEXT_PUBLIC_*.

الـ instrumentation يعطّل تشغيل workers تلقائيًا عندما تكون البيئة Vercel (VERCEL=1)، لذلك لا ينشأ worker مؤقت داخل Function ولا تتكرر معالجة المهمة.