441 lines
15 KiB
Markdown
441 lines
15 KiB
Markdown
# راهنمای پیاده‌سازی یکپارچه‌سازی 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ها و سناریوهای خطا (۴۰۱, ۴۰۳, ۴۲۹) نوشته شده است.
|