# دليل المساهمة — Contributing Guide

---

## إعداد بيئة التطوير

```bash
# 1. Clone
git clone https://github.com/sudanna/ai-os.git
cd sudanna

# 2. Install PHP 8.1
apt install php8.1-fpm php8.1-mysql php8.1-mbstring php8.1-curl

# 3. Database (local)
mysql -u root -p -e "CREATE DATABASE sudanna_dev CHARACTER SET utf8mb4;"
mysql -u root -p sudanna_dev < sudanna_v22_schema_complete.sql
mysql -u root -p sudanna_dev < migration_fix.sql
mysql -u root -p sudanna_dev < seed.sql

# 4. Config
cp config.example.php config.php
# عدِّل DB credentials + API keys

# 5. Validate
for f in $(find . -name '*.php'); do php8.1 -l $f; done | grep error
# → 0 errors
```

---

## قواعد الكود

### PHP
```php
<?php
/**
 * وصف الملف
 * @package Sudanna\Engine
 */
class MyEngine {

    /**
     * وصف الدالة
     * @param int $userId
     * @param string $type
     * @return array
     */
    public static function myMethod(int $userId, string $type): array {
        // استخدم prepared statements دائماً
        $st = db()->prepare("SELECT * FROM table WHERE id=?");
        $st->execute([$userId]);
        return $st->fetchAll();
    }
}
```

### القواعد الإجبارية
```
1. كل SQL = prepared statement (لا exceptions)
2. كل input = validated + sanitized
3. كل PHP = يجب أن يمر php -l بدون errors
4. لا تُعدِّل BillingEngine أو FinancialAgent (SEALED)
5. engine/ لا يُوصَل مباشرة من الويب (محجوب)
```

---

## إضافة Domain جديد (AssistantEngine)

```php
// في engine/AssistantEngine.php → const DOMAINS
'new_domain' => [
    'sectors'   => ['new_sector'],
    'name_ar'   => 'اسم المساعد',
    'name_en'   => 'Assistant Name',
    'guard'     => 'You handle ONLY: ...',
    'guard_ar'  => 'أنا مساعد ...',
    'safety_rules' => ['لا تُجيب على ...'],
],
```

```php
// في sectorToDomain() — إضافة mapping
'new_sector' => 'new_domain',
```

---

## إضافة IE Rule

```php
// في engine/InferenceEngine.php
$R[] = [
    'id'   => 'rule_unique_id',
    'sector' => 'new_sector',
    'conf'   => 0.85,
    'p'      => ['/كلمة.*مفتاحية/ui', '/keyword/i'],
    'x'      => ['/استثناء/ui'],  // اختياري
];
```

---

## إضافة PolicyEngine Case

```php
// في engine/PolicyEngine.php → switch($action)
case 'new.action':
    return self::ALLOW; // or self::BLOCK
```

---

## إضافة API Endpoint

```php
<?php
/**
 * METHOD /api/category/endpoint.php
 * الوصف
 */
require_once '../../config.php';
header('Content-Type: application/json; charset=utf-8');

// Auth check (إذا مطلوب)
$u = require_auth();

if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
    http_response_code(405);
    die(json_encode(['error' => 'method_not_allowed']));
}

$b = json_decode(file_get_contents('php://input'), true) ?? [];

// Validate inputs
$key = mb_substr(trim($b['key'] ?? ''), 0, 100);
if (!$key) {
    http_response_code(400);
    die(json_encode(['error' => 'key_required']));
}

try {
    // Logic هنا
    echo json_encode(['ok' => true], JSON_UNESCAPED_UNICODE);
} catch (Throwable $e) {
    error_log("[api/category/endpoint] " . $e->getMessage());
    http_response_code(500);
    echo json_encode(['error' => $e->getMessage()]);
}
```

---

## Testing

```bash
# PHP syntax check
php8.1 -l engine/MyEngine.php

# Quick API test
curl -X POST https://dev.sudanna.ai/api/my/endpoint.php \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}'

# Full validation
php go_live_proof.php
```

---

## Commit Message Format

```
type: short description

Types:
  feat:     ميزة جديدة
  fix:      إصلاح خطأ
  engine:   تعديل محرك
  api:      endpoint جديد/معدَّل
  schema:   تغيير DB
  docs:     توثيق
  security: إصلاح أمني
  style:    CSS/UI

مثال:
  feat: إضافة SuggestionsAgent مع Jaccard duplicate detection
  fix: إصلاح BillingEngine → subscription_credits priority
  security: إضافة HMAC check في webhook
```

---

## SEALED Files — لا تُعدِّلها

```
engine/FinancialAgent.php  → double-entry ledger
engine/BillingEngine.php   → hold model (فقط إضافة methods جديدة)
sudanna_v22_schema_complete.sql → الجداول الأصلية
```

---

## الاتصال

```
المشاكل:    GitHub Issues
الأمان:     security@sudanna.ai (private)
الاستفسار: dev@sudanna.ai
```
