CRM_Montzar/docs/integrations/tahesab.md

# اتصال ته‌حساب (فاز ۱)

مرجع API: [Tahesab API Reference](https://tahesab.ir/APiDoc/) · OpenAPI: `docs/integrations/tahesab-openapi.json`

## اصول

- هر سازمان می‌تواند **چند اتصال** داشته باشد (`baseUrl` + `token` + `dbName`).
- توکن با **AES-256-GCM** و کلید محیطی `INTEGRATIONS_ENCRYPTION_KEY` رمز می‌شود و هرگز کامل به فرانت برنمی‌گردد.
- مانده و اسناد: **منبع حقیقت ته‌حساب** است؛ CRM فقط cache و لینک نگه می‌دارد.
- ثبت سند فقط از فرم اختصاصی تب **دارایی** با `Factor_Code` یکتا (≥۲۰ کاراکتر) و جدول `AccountingDocumentLog` (idempotent).

## مدل‌ها

| مدل | نقش |
|-----|-----|
| `AccountingConnection` | اتصال چند-DB |
| `PersonAccountingLink` | لینک شخص ↔ `moshtariCode` روی یک اتصال |
| `AccountingDocumentLog` | لاگ push سند |
| `AccountingBalanceCache` | cache مانده |
| `AccountingSyncJob` | لاگ جستجو/وارد کردن |

## APIهای CRM

پیشوند: `/api/integrations/tahesab`

- اتصالات (owner/admin): `GET/POST/PATCH/DELETE /connections` · `POST /connections/:id/test`
- لیست عمومی اتصالات: `GET /connections/public`
- لینک شخص: `GET/POST .../people/:id/links` · `DELETE .../links/:connectionId`
- تطبیق: `POST .../people/:id/match` · ثبت: `POST .../create-in-tahesab`
- دارایی: `GET .../people/:id/assets` · اسناد: `GET .../people/:id/asnad`
- ثبت سند: `POST .../people/:id/sanad`
- sync دوطرفه: `POST /sync/search` · `POST /sync/import` · `POST /sync/import-bulk` (بازه کد یا لیست کدها)

## تطبیق مشتری

1. نرمال‌سازی موبایل → `DoListMoshtari-ByPhone`
2. اگر خالی → `DoListMoshtari-ByName`
3. اگر بیش از یک نتیجه → انتخاب دستی (لینک خودکار روی ابهام ممنوع)
4. لینک دستی با کد · یا `DoNewMoshtari`

## انواع سند فاز ۱

| کلید CRM | متد ته‌حساب |
|----------|-------------|
| `buy_sale_gold` | `DoNewSanadBuySaleGOLD` |
| `buy_sale_sekeh` | `DoNewSanadBuySaleSEKEH` |
| `talab_bedehi` | `DoNewSanadTalabBedehi` |
| `vkh_gold` | `DoNewSanadVKHGOLD` |
| `vkh_bank` | `DoNewSanadVKHBank` |

مانده: مسیر `GetMandeHesabByCode` با کلید body `getmandehesabbycode` (مثل همکار).

## استقرار

1. `INTEGRATIONS_ENCRYPTION_KEY` را روی سرور بگذارید (۶۴ کاراکتر hex).
2. `npx prisma migrate deploy` در `apps/api`
3. rebuild API/web و restart PM2

## وارد کردن مشتریان

افزودن اتصال به‌تنهایی مشتری را به CRM کپی نمی‌کند. از **تنظیمات → ته‌حساب → وارد کردن مشتریان**:

1. بازهٔ کد (مثلاً ۱ تا ۵۰۰) را بزنید و «وارد کردن کل بازه»، یا  
2. با موبایل/نام/کد جستجو کنید و تکی/دسته‌ای وارد کنید.

مانده و اسناد بعد از لینک، در پروفایل شخص → تب **دارایی** دیده می‌شود.

## چک‌لیست تست دستی

- [ ] افزودن اتصال + تست health
- [ ] افزودن اتصال دوم با DB دیگر؛ انتخاب پیش‌فرض
- [ ] وارد کردن بازه کد مشتریان + دیدن در اشخاص
- [ ] تطبیق شخص با موبایل / لینک دستی / ثبت جدید
- [ ] نمایش مانده و جزئیات در تب دارایی
- [ ] لیست اسناد با بازه شمسی
- [ ] ثبت سند؛ retry با همان Factor_Code نباید سند تکراری بسازد

## خارج از فاز ۱

push خودکار از معامله/فاکتور، RFID/اتیکت، PDF/Excel اسناد، ویرایش سند در ته‌حساب.