72 lines
3.2 KiB
Markdown
72 lines
3.2 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` | لاگ جستجو/وارد کردن |
|
|||
|
|
|
|||
|
|
## 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`
|
|||
|
|
|
|||
|
|
## تطبیق مشتری
|
|||
|
|
|
|||
|
|
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
|
|||
|
|
|
|||
|
|
## چک‌لیست تست دستی
|
|||
|
|
|
|||
|
|
- [ ] افزودن اتصال + تست health
|
|||
|
|
- [ ] افزودن اتصال دوم با DB دیگر؛ انتخاب پیش‌فرض
|
|||
|
|
- [ ] تطبیق شخص با موبایل / لینک دستی / ثبت جدید
|
|||
|
|
- [ ] نمایش مانده و جزئیات در تب دارایی
|
|||
|
|
- [ ] لیست اسناد با بازه شمسی
|
|||
|
|
- [ ] ثبت سند؛ retry با همان Factor_Code نباید سند تکراری بسازد
|
|||
|
|
- [ ] وارد کردن مشتری از تنظیمات ته‌حساب
|
|||
|
|
|
|||
|
|
## خارج از فاز ۱
|
|||
|
|
|
|||
|
|
push خودکار از معامله/فاکتور، RFID/اتیکت، PDF/Excel اسناد، ویرایش سند در ته‌حساب.
|