CRM_Montzar/docs/MONTACT_CRM_IMPLEMENTATION_GUIDE.md

# راهنمای پیاده‌سازی یکپارچه‌سازی MONTACT CRM برای زیرسیستم‌های فروشگاهی (Provider Guide) — نسخه v2

## ۱. مقدمه و هدف سند

این سند برای تیم توسعه زیرسیستم‌های فروشگاهی (مانند Montify) نوشته شده است. هدف، فراهم کردن APIای است که سامانه بیرونی **Montact CRM** بتواند داده‌های مشتری، سفارش و تعاملات را Pull کند (فاز ۱ و ۲) و در فاز ۳ رویدادها را به‌صورت Push (Webhook) دریافت نماید. این سند باید کاملاً هم‌راستا با سند سمت کلاینت (`MONTACT_CRM_INTEGRATION.md`) باشد.

## ۲. معماری کلی

```
   [Client: Montact CRM]
            │  HTTPS + Bearer Token
            ▼
   [Middleware احراز هویت] ── بررسی token_hash، expires_at، revoked_at
            │
            ▼
   [Provider: Montify API] ── Controller ها (Customers / Orders / Webhooks)
            │
            ▼
      [Database: PostgreSQL]
            │
            ▼
   [Webhook Dispatcher] ──► Queue (Redis/BullMQ) ──► POST به CRM
```

## ۳. مدل داده و Migration ها

### جدول `api_keys`

```sql
CREATE TABLE api_keys (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  store_id UUID NOT NULL REFERENCES stores(id),
  token_hash VARCHAR(255) NOT NULL,
  name VARCHAR(100),
  scopes JSONB DEFAULT '[]',
  last_used_at TIMESTAMP NULL,
  expires_at TIMESTAMP NULL,
  created_at TIMESTAMP NOT NULL DEFAULT now(),
  revoked_at TIMESTAMP NULL
);

CREATE INDEX idx_api_keys_store_id ON api_keys(store_id);
```

### جدول `webhook_endpoints`

```sql
CREATE TABLE webhook_endpoints (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  store_id UUID NOT NULL REFERENCES stores(id),
  url VARCHAR(500) NOT NULL,
  secret VARCHAR(255) NOT NULL,
  events JSONB NOT NULL DEFAULT '[]',
  is_active BOOLEAN NOT NULL DEFAULT true,
  created_at TIMESTAMP NOT NULL DEFAULT now(),
  updated_at TIMESTAMP NOT NULL DEFAULT now()
);
```

### جدول `webhook_deliveries`

```sql
CREATE TABLE webhook_deliveries (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  webhook_endpoint_id UUID NOT NULL REFERENCES webhook_endpoints(id),
  event VARCHAR(100) NOT NULL,
  payload JSONB NOT NULL,
  status VARCHAR(20) NOT NULL DEFAULT 'pending', -- pending|success|failed
  attempt_count INTEGER NOT NULL DEFAULT 0,
  last_attempted_at TIMESTAMP NULL,
  response_status INTEGER NULL,
  created_at TIMESTAMP NOT NULL DEFAULT now()
);

CREATE INDEX idx_webhook_deliveries_status ON webhook_deliveries(status);
```

## ۴. Middleware احراز هویت (NestJS Guard)

```typescript
import { Injectable, CanActivate, ExecutionContext, UnauthorizedException, ForbiddenException } from '@nestjs/common';
import * as crypto from 'crypto';

@Injectable()
export class MontactAuthGuard implements CanActivate {
  constructor(private readonly apiKeyRepository: any) {}

  async canActivate(context: ExecutionContext): Promise<boolean> {
    const request = context.switchToHttp().getRequest();
    const authHeader = request.headers['authorization'];

    if (!authHeader || !authHeader.startsWith('Bearer ')) {
      throw new UnauthorizedException('Token missing');
    }

    const token = authHeader.replace('Bearer ', '');
    const tokenHash = crypto.createHash('sha256').update(token).digest('hex');

    const apiKey = await this.apiKeyRepository.findOne({ where: { token_hash: tokenHash } });

    if (!apiKey || apiKey.revoked_at) {
      throw new UnauthorizedException('Invalid or revoked token');
    }

    if (apiKey.expires_at && new Date(apiKey.expires_at) < new Date()) {
      throw new UnauthorizedException('Token expired');
    }

    const storeIdParam = request.params.storeId;
    if (storeIdParam && storeIdParam !== apiKey.store_id) {
      throw new ForbiddenException('Store mismatch');
    }

    apiKey.last_used_at = new Date();
    await this.apiKeyRepository.save(apiKey);

    request.store_id = apiKey.store_id;
    return true;
  }
}
```

## ۵. تعریف کامل Endpointها

| Method | Path | توضیح |
|---|---|---|
| GET | `/montact/customers` | لیست مشتریان (`page`, `limit`, `updated_after`) |
| GET | `/montact/customers/:id` | جزئیات مشتری |
| GET | `/montact/customers/:id/orders` | سفارش‌های مشتری (`updated_after`) |
| GET | `/montact/customers/:id/addresses` | آدرس‌های مشتری |
| GET | `/montact/customers/:id/transactions` | تراکنش‌های مشتری |
| GET | `/montact/customers/:id/engagement` | داده‌های تعاملی |
| GET | `/montact/orders/:orderId` | جزئیات یک سفارش |
| POST | `/montact/webhooks/register` | ثبت Webhook جدید |
| GET | `/montact/webhooks/:id` | مشاهده جزئیات Webhook |
| DELETE | `/montact/webhooks/:id` | حذف Webhook |

### نمونه Query/ORM برای `GET /montact/customers`

```typescript
async getCustomers(storeId: string, page: number, limit: number, updatedAfter?: string) {
  const query = this.customerRepository
    .createQueryBuilder('c')
    .where('c.store_id = :storeId', { storeId });

  if (updatedAfter) {
    query.andWhere('c.updated_at > :updatedAfter', { updatedAfter });
  }

  const [data, total] = await query
    .skip((page - 1) * limit)
    .take(limit)
    .getManyAndCount();

  return {
    data: data.map(this.toCustomerDto),
    meta: { current_page: page, per_page: limit, total, last_page: Math.ceil(total / limit) }
  };
}
```

### ساختار JSON خروجی مشتری/سفارش

ساختار خروجی باید دقیقاً با فیلدهای تعریف‌شده در سند کلاینت (`MONTACT_CRM_INTEGRATION.md`, بخش ۵) یکسان باشد، شامل:

- **Customer:** `id, name, first_name, last_name, phone, email, username, avatar, birthday, gender, type, store_id, created_at, updated_at, description, bio, job, cash_balance, gold_balance, orders, summary, addresses, transactions, engagement`
- **Order:** `id, user_id, store_id, code, sts, payment_sts, payment_type, total_price, discount_total_price, total_discounts, total_tax, total_qty, profit, percent_profit, sum_gold, sum_silver, address, address_id, note, cancel_reason, cancelled_at, closed_at, transaction_id, code_discount, discount_code_id, created_at, updated_at, deleted_at, order_items, user, store`
- **Engagement:** `saved, likes, comments` (دقیقاً مطابق نمونه JSON سند کلاینت بخش ۵.۶)

## ۶. بهینه‌سازی

### Caching (Redis)

```typescript
async getCustomersCached(storeId: string, page: number, limit: number, updatedAfter?: string) {
  const cacheKey = `customers:${storeId}:${page}:${limit}:${updatedAfter || 'all'}`;
  const cached = await this.redis.get(cacheKey);
  if (cached) return JSON.parse(cached);

  const result = await this.getCustomers(storeId, page, limit, updatedAfter);
  await this.redis.set(cacheKey, JSON.stringify(result), 'EX', 45); // TTL 45s
  return result;
}

// Invalidation هنگام ایجاد/ویرایش سفارش
async invalidateCustomerCache(storeId: string) {
  const keys = await this.redis.keys(`customers:${storeId}:*`);
  if (keys.length) await this.redis.del(keys);
}
```

### Rate Limiting (Token Bucket)

```typescript
import { Injectable, NestMiddleware, HttpException } from '@nestjs/common';

@Injectable()
export class RateLimitMiddleware implements NestMiddleware {
  async use(req: any, res: any, next: () => void) {
    const apiKeyId = req.apiKeyId;
    const key = `ratelimit:${apiKeyId}`;
    const current = await this.redis.incr(key);

    if (current === 1) {
      await this.redis.expire(key, 60); // پنجره ۶۰ ثانیه‌ای
    }

    if (current > 100) { // 100 req/min
      res.setHeader('Retry-After', '60');
      throw new HttpException('Too Many Requests', 429);
    }

    next();
  }
}
```

## ۷. فاز ۲ — Incremental Sync سمت Provider

- فیلتر `updated_after` به شکل `WHERE updated_at > :updated_after` در تمام کوئری‌های لیست (customers, orders) اعمال می‌شود.
- برای پرفورمنس، باید ایندکس روی ستون `updated_at` ایجاد شود:

```sql
CREATE INDEX idx_customers_updated_at ON customers(updated_at);
CREATE INDEX idx_orders_updated_at ON orders(updated_at);
```

## ۸. فاز ۳ — Webhook (Push) سمت Provider

### ثبت Webhook

```http
POST /montact/webhooks/register
Authorization: Bearer {token}
Content-Type: application/json

{
  "url": "https://crm.montact.com/webhooks/montify",
  "events": ["order.created", "order.paid"]
}
```

```typescript
async registerWebhook(storeId: string, url: string, events: string[]) {
  if (!url.startsWith('https://')) {
    throw new BadRequestException('Webhook URL must use HTTPS');
  }
  // محافظت SSRF: منع IP های داخلی/لوکال
  const hostname = new URL(url).hostname;
  if (this.isPrivateOrLocalHost(hostname)) {
    throw new BadRequestException('Private/local URLs are not allowed');
  }

  const secret = crypto.randomBytes(32).toString('hex');

  const webhook = await this.webhookRepository.save({
    store_id: storeId,
    url,
    secret, // باید رمزنگاری‌شده در دیتابیس ذخیره شود (مثلاً با AES)
    events,
    is_active: true,
  });

  return { id: webhook.id, secret }; // secret فقط یک‌بار در پاسخ برگردانده می‌شود
}
```

### مدیریت Webhook

```http
GET /montact/webhooks/:id
DELETE /montact/webhooks/:id
```

### رویدادهای پشتیبانی‌شده

| رویداد | توضیح |
|---|---|
| customer.created | ایجاد مشتری جدید |
| customer.updated | بروزرسانی مشتری |
| order.created | ثبت سفارش جدید |
| order.updated | تغییر سفارش |
| order.paid | پرداخت سفارش |
| order.cancelled | لغو سفارش |

### Event Dispatcher

```javascript
const { Queue } = require('bullmq');
const webhookQueue = new Queue('webhook-deliveries', { connection: redisConnection });

async function dispatchEvent(storeId, eventName, data) {
  const endpoints = await WebhookEndpoint.findAll({
    where: { store_id: storeId, is_active: true }
  });

  for (const endpoint of endpoints) {
    if (!endpoint.events.includes(eventName)) continue;

    const delivery = await WebhookDelivery.create({
      webhook_endpoint_id: endpoint.id,
      event: eventName,
      payload: { event: eventName, delivery_id: null, store_id: storeId, data },
      status: 'pending',
    });

    const payload = {
      event: eventName,
      delivery_id: delivery.id,
      store_id: storeId,
      data,
    };

    await webhookQueue.add('deliver', {
      deliveryId: delivery.id,
      endpointId: endpoint.id,
      url: endpoint.url,
      secret: endpoint.secret,
      payload,
    });
  }
}

// مثال استفاده بعد از ثبت سفارش:
// await dispatchEvent(order.store_id, 'order.created', orderDto);
```

### امضای HMAC-SHA256

```javascript
const crypto = require('crypto');

function signPayload(payload, secret) {
  const rawBody = JSON.stringify(payload);
  return crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
}
```

### نمونه Payload ارسالی برای `order.created`

```json
{
  "event": "order.created",
  "delivery_id": "d2f1c9e0-84a3-4b7f-9c1e-3a2b1c0d9e8f",
  "store_id": "b2f1e4a0-...",
  "data": {
    "id": 4567,
    "user_id": 123,
    "code": "ORD-2026-4567",
    "sts": "pending",
    "payment_sts": "unpaid",
    "total_price": 12500000,
    "total_qty": 2,
    "created_at": "2026-07-10T12:05:00Z"
  }
}
```

### Retry Policy (Worker)

```javascript
const { Worker } = require('bullmq');
const axios = require('axios');

const RETRY_DELAYS = [1000, 5000, 15000, 60000, 300000]; // 1s,5s,15s,60s,300s

const worker = new Worker('webhook-deliveries', async (job) => {
  const { deliveryId, url, secret, payload } = job.data;
  const signature = signPayload(payload, secret);

  try {
    const response = await axios.post(url, payload, {
      headers: {
        'X-Montact-Signature': `sha256=${signature}`,
        'X-Montact-Event': payload.event,
        'X-Montact-Delivery-Id': payload.delivery_id,
        'Content-Type': 'application/json',
      },
      timeout: 10000, // 10s timeout
    });

    if (response.status >= 200 && response.status < 300) {
      await WebhookDelivery.update(
        { status: 'success', response_status: response.status, last_attempted_at: new Date() },
        { where: { id: deliveryId } }
      );
      return;
    }
    throw new Error(`Unexpected status ${response.status}`);
  } catch (err) {
    const attempt = job.attemptsMade;
    await WebhookDelivery.increment('attempt_count', { where: { id: deliveryId } });

    if (attempt >= RETRY_DELAYS.length) {
      await WebhookDelivery.update(
        { status: 'failed', last_attempted_at: new Date() },
        { where: { id: deliveryId } }
      );
    } else {
      throw err; // BullMQ طبق backoff تعریف‌شده در صف، تلاش مجدد می‌کند
    }
  }
}, {
  connection: redisConnection,
  settings: { backoffStrategy: (attempt) => RETRY_DELAYS[attempt - 1] },
});
```

### نکات امنیتی ثبت Webhook

- URL ثبت‌شده باید حتماً `https://` باشد.
- IPهای داخلی/لوکال (`127.0.0.1`, `10.x.x.x`, `192.168.x.x`, `169.254.x.x`) باید مسدود شوند (محافظت SSRF).
- `secret` باید در دیتابیس رمزنگاری‌شده ذخیره شود، نه به‌صورت plain-text.

## ۹. مانیتورینگ و لاگ

- تمام رکوردهای `webhook_deliveries` باید همراه با `attempt_count` و `response_status` لاگ شوند.
- در صورتی‌که نرخ `failed` برای یک Webhook Endpoint خاص از ۲۰٪ در بازه ۱ ساعته بیشتر شود، باید Alert ارسال شود (مثلاً از طریق Slack/Email) و در صورت ادامه، Endpoint به‌صورت موقت `is_active=false` شود.

## ۱۰. چک‌لیست پیاده‌سازی برای تیم Provider

- [ ] اجرای Migration جداول `api_keys`, `webhook_endpoints`, `webhook_deliveries`
- [ ] پیاده‌سازی Middleware احراز هویت (Guard)
- [ ] پیاده‌سازی تمام Endpointهای GET مطابق جدول بخش ۵
- [ ] اعمال فیلتر `updated_after` و ایندکس‌گذاری `updated_at`
- [ ] پیاده‌سازی Caching با Redis و Invalidation مناسب
- [ ] پیاده‌سازی Rate Limiting (۱۰۰ req/min)
- [ ] پیاده‌سازی ثبت/حذف/مشاهده Webhook
- [ ] پیاده‌سازی Event Dispatcher و اتصال به Queue
- [ ] پیاده‌سازی Worker با Retry Policy و Backoff
- [ ] تست کامل امضای HMAC-SHA256 در سمت Worker و نمونه CRM

## ۱۱. تست و چک‌لیست امنیتی

- [ ] Token هرگز به‌صورت plain-text ذخیره نمی‌شود؛ تنها `token_hash` ذخیره می‌شود.
- [ ] `secret` وبهوک رمزنگاری‌شده در دیتابیس ذخیره می‌شود.
- [ ] HTTPS برای تمام Webhook URLها اجباری است.
- [ ] محافظت SSRF در برابر IPهای داخلی/لوکال فعال است.
- [ ] محدودسازی اختیاری بر اساس IP Whitelist برای توکن‌های حساس در نظر گرفته شده است.
- [ ] تست‌های Integration برای تمام Endpointها و سناریوهای خطا (۴۰۱, ۴۰۳, ۴۲۹) نوشته شده است.