MahdiandCursor
4b47b753c3
Encrypt tokens server-side, sync customers both ways, show balances/documents on the person Assets tab, and push sanads with idempotent Factor_Code logging. Co-authored-by: Cursor <cursoragent@cursor.com>
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 اسناد، ویرایش سند در ته‌حساب.
|