95 lines
5.0 KiB
Markdown
95 lines
5.0 KiB
Markdown
# اتصال ته‌حساب (فاز ۱)
|
||
|
||
مرجع 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` | لاگ جستجو/وارد کردن |
|
||
| `ProductAccountingLink` | لینک محصول ↔ نام کارساخته روی یک اتصال |
|
||
|
||
## 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` (بازه کد یا لیست کدها)
|
||
- sync محصولات/کارساخته: `POST /sync/products/search` · `POST /sync/products/import` · `POST /sync/products/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. با موبایل/نام/کد جستجو کنید و تکی/دسته‌ای وارد کنید.
|
||
|
||
مانده و اسناد بعد از لینک، در پروفایل شخص → تب **دارایی** دیده می‌شود.
|
||
|
||
## وارد کردن کارساخته (محصولات)
|
||
|
||
از **تنظیمات → ته‌حساب → وارد کردن کارساخته**:
|
||
|
||
1. اتصال را انتخاب و «دریافت لیست» بزنید (`DoListNameKarsakhte`).
|
||
2. تکی، نتایج فیلترشده، یا همه را وارد کنید.
|
||
|
||
هر نام به‌عنوان `Product` با دستهٔ **کارساخته** ساخته و در `ProductAccountingLink` لینک می‌شود (عیار در تگ/توضیح). موجودی همچنان منبع حقیقت ته‌حساب است؛ این فقط کاتالوگ CRM برای معامله/فاکتور است.
|
||
|
||
در کسب‌وکارهای غیرطلا ممکن است همان لیست API با عنوان دیگری شناخته شود؛ فعلاً برچسب CRM «کارساخته» است.
|
||
|
||
## چک‌لیست تست دستی
|
||
|
||
- [ ] افزودن اتصال + تست health
|
||
- [ ] افزودن اتصال دوم با DB دیگر؛ انتخاب پیش‌فرض
|
||
- [ ] وارد کردن بازه کد مشتریان + دیدن در اشخاص
|
||
- [ ] دریافت لیست کارساخته + وارد کردن تکی/دسته‌ای به محصولات
|
||
- [ ] تطبیق شخص با موبایل / لینک دستی / ثبت جدید
|
||
- [ ] نمایش مانده و جزئیات در تب دارایی
|
||
- [ ] لیست اسناد با بازه شمسی
|
||
- [ ] ثبت سند؛ retry با همان Factor_Code نباید سند تکراری بسازد
|
||
|
||
## خارج از فاز ۱
|
||
|
||
push خودکار از معامله/فاکتور، RFID/اتیکت، PDF/Excel اسناد، ویرایش سند در ته‌حساب.
|