# ثبت معامله از متن — نسخه قالب ۱

این راهنمای روت‌های سازگار نسخه ۴.۱ است که حفظ شده‌اند. قابلیت‌های نسخه ۴.۲ در TEXT_IMPORT_V2_FA.md و روت‌های /api/text-imports هستند؛ محدودیت‌ها و رفتار این دو قرارداد را با هم ترکیب نکنید.

POST /api/trade-text یک معامله را از متن ثابت ثبت می‌کند. بدنه JSON فقط فیلد text دارد؛ فایل، OCR، متن آزاد و چند معامله در یک درخواست پذیرفته نمی‌شوند. API از هوش مصنوعی برای حدس‌زدن داده استفاده نمی‌کند.

## قالب قابل کپی

```text
مشتری: C001
دریافتی: 1000 USD
پرداختی: 910 EUR
کارمزد: 0.5
نرخ یورویی دریافتی: 0.92
هزینه یورویی: 910
توضیحات: معامله نمونه
```

سه خط مشتری، دریافتی و پرداختی الزامی‌اند. مشتری **کد یکتای مشتری موجود** است؛ نام تنها پذیرفته نمی‌شود و مشتری خودکار ساخته نمی‌شود. خط اختیاری «نام مشتری: احمد» برای کنترل تطابق دقیق نام قابل افزودن است. کد را از پاسخ ایجاد/فهرست مشتری‌ها بگیرید. C001 نمونه است.

عناوین باید دقیقاً مانند قالب و با دو نقطه انگلیسی باشند. ترتیب خطوط آزاد است و خطوط خالی نادیده گرفته می‌شوند. هر عنوان فقط یک‌بار مجاز است. ارقام فارسی/عربی و ممیز ٫ در مقادیر عددی پشتیبانی می‌شوند؛ جداکننده هزارگان، علامت درصد و نماد ارز پذیرفته نمی‌شوند. ارز کد سه‌حرفی مانند USD، EUR یا AFN است. ارقام موجود در کد مشتری تغییر داده نمی‌شوند.

خطوط اختیاری: نام مشتری، کارمزد، نرخ یورویی دریافتی، نرخ یورویی پرداختی، هزینه یورویی و توضیحات. کارمزد درصد است؛ صفر معتبر است. در صورت حذف، تنظیم فعلی استفاده می‌شود. نرخ‌های یورویی حذف‌شده از نرخ ذخیره‌شده ارز خوانده می‌شوند؛ نبود نرخ لازم خطاست و EUR همیشه ۱ است. توضیحات یک خط و حداکثر ۲۰۰۰ کاراکتر است؛ کل متن حداکثر ۵۰۰۰ کاراکتر.

## اثر حسابداری

دریافتی **اصل تعهد مشتری، قبل از کارمزد** است؛ پرداختی تعهد صرافی است. نرخ توافقی از تقسیم پرداختی بر دریافتی، با حداکثر ۱۲ رقم اعشار ساخته می‌شود. مبلغ پرداختی باید با دقت ارز و نرخ پشتیبانی‌شده دقیقاً بازتولید شود؛ اگر نشود درخواست رد می‌شود، مبلغ بی‌صدا تغییر نمی‌کند.

در مثال، کارمزد ۵ دلار است و سند، بدهی مشتری ۱۰۰۵ دلار و طلب او ۹۱۰ یورو ایجاد می‌کند. همان سرویس ثبت اتمیک، Ledger، شماره سند، هشدارها، snapshot مانده و Audit معامله معمولی اجرا می‌شود. هیچ Payment یا گردش صندوقی خودکار ایجاد نمی‌شود. دریافت/پرداخت واقعی از /api/payments ثبت می‌شود و tradeId پاسخ قابل استفاده است. سود بدون هزینه یورویی null می‌ماند.

## روت‌ها و دسترسی

| روش | مسیر | رفتار |
|---|---|---|
| GET | /api/trade-text/template | قالب، نسخه و عنوان‌های الزامی/اختیاری؛ همه نقش‌های واردشده |
| POST | /api/trade-text/preview | بررسی متن و نمایش محاسبات؛ ADMIN و CASHIER؛ بدون گردش مالی |
| POST | /api/trade-text | ثبت واقعی؛ ADMIN و CASHIER؛ پاسخ 201 با data |

پیش‌نمایش اختیاری و اطلاع‌رسانی است؛ هنگام ثبت مستقیم، تنظیمات و نرخ‌های فعلی دوباره خوانده می‌شوند. previewId برگشتی پیش‌نمایش در بدنه این روت متنی پذیرفته نمی‌شود؛ برای تثبیت ورودی، نرخ‌ها و کارمزد را صریح بنویسید. مسیر پیش‌نمایش معمولی /api/trades/preview قرارداد جداگانه خودش را دارد.

## نمونه درخواست

```bash
curl -X POST http://localhost:3000/api/trade-text \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: text-trade-000001' \
  --data '{"text":"مشتری: C001\nدریافتی: 1000 USD\nپرداختی: 910 EUR\nکارمزد: 0.5\nنرخ یورویی دریافتی: 0.92"}'
```

برای preview همان بدنه را به /api/trade-text/preview بفرستید؛ کلید تکرار لازم نیست. ارسال text/plain پشتیبانی نمی‌شود؛ فقط JSON حاوی text ارسال کنید.

در تکرار پس از timeout، **همان Idempotency-Key** را نگه دارید. همان ورودی تبدیل‌شده سند قبلی را برمی‌گرداند؛ بدنه متفاوت با همان کلید 409 دارد. ترتیب خطوط و ارقام فارسی مبلغ‌ها استانداردسازی می‌شوند. تغییر توضیحات یا سایر فیلدهای ذخیره‌شده می‌تواند تعارض ایجاد کند. تغییر نام یا کد مشتری بین درخواست‌ها می‌تواند اعتبارسنجی مشتری را ناموفق کند؛ قبل از ساخت کلید جدید سند قبلی را بررسی کنید. کلید بین روت معمولی و متنی در جدول Trade مشترک است؛ برای عملیات مستقل کلید یکتا استفاده کنید.

## خطاها

INVALID_TRADE_TEXT برای عنوان ناشناخته/تکراری، خط ناقص یا مقدار نامعتبر است؛ error.field در خطاهای خطی مثل text.line.2 محل را مشخص می‌کند. CUSTOMER_NOT_FOUND یعنی کد وجود ندارد؛ CUSTOMER_NAME_MISMATCH یعنی نام اختیاری تطابق ندارد. TEXT_AMOUNT_MISMATCH یعنی نرخ محدود به ۱۲ رقم نمی‌تواند مبلغ خواسته‌شده را بازتولید کند. اعتبارسنجی دقت ارز، نرخ موجود، مشتری فعال و مجوزها مانند معامله معمولی است. هیچ سند ناقصی از درخواست ناموفق ثبت نمی‌شود.

## فایل‌ها و ارتقا

src/text-trades.js: قالب، parser، تطبیق مشتری و سه روت. src/accounting.js: کنترل مبلغ پرداختی و سرویس مشترک ثبت. test/text-trades.test.js: آزمون قالب و خطاها. این قابلیت جدول و migration جدید ندارد؛ نصب و ارتقا همان راهنمای نسخه ۴ است. OpenAPI، Swagger و Postman از registry واقعی بازتولید شده‌اند.