# ارتقای نسخه ۲ یا ۳ به نسخه ۴

۱. از دیتابیس بکاپ بگیرید و بازیابی آن را روی دیتابیس آزمایشی بررسی کنید. ابتدا ارتقا را روی کپی داده تمرین کنید.

۲. برنامه قبلی را متوقف کنید. فایل‌های نسخه ۴ را جایگزین و .env واقعی خود را حفظ کنید. SQL کامل را روی دیتابیس دارای داده import نکنید.

۳. در مسیر پروژه اجرا کنید:

```bash
npm ci
npm run setup
npm start
```

setup، Prisma Client را تولید می‌کند، migrationهای اجرا‌نشده را به ترتیب اعمال و seed را اجرا می‌کند. دو migration منتشرشده قبلی تغییر نکرده‌اند. migration سوم افزایشی است: جدول‌های پیش‌نمایش، شمارنده، تخصیص و تنظیم گزارش و ستون‌های جدید را اضافه می‌کند. seed شمارنده‌های ناموجود را ایجاد می‌کند و رمز مدیر، نرخ یا شمارنده موجود را ریست نمی‌کند.

اگر نسخه قدیمی با SQL دستی نصب شده و سابقه migration ندارد، ابتدا baseline متناسب با ساختار واقعی همان نسخه را طبق راهنمای SQL نسخه خودش ثبت کنید؛ migration سوم را قبل از اجرای واقعی روی دیتابیس قدیمی resolve نکنید. نصب دستی خالی نسخه ۴ هر سه migration را پس از import resolve می‌کند.

۴. ورود، /ready، ثبت آزمایشی معامله/پرداخت و گزارش را بررسی کنید. بعد از اطمینان، سرویس را در دسترس کاربران قرار دهید. برگشت به کد نسخه قبلی پس از ثبت عملیات جدید روش rollback تأییدشده نیست؛ برای بازگشت، طرح بازیابی بکاپ و داده‌های پس از آن لازم است.

## رفتار داده‌های قبلی

اسناد قدیمی شماره و snapshot ساختگی نمی‌گیرند؛ documentNumber و resultSnapshot می‌توانند null باشند. هیچ پرداخت یا گردش قدیمی بازنویسی و هیچ تخصیص تاریخی حدس زده نمی‌شود. پرداخت قدیمی تخصیص‌نیافته می‌تواند وضعیت تسویه معامله را REVIEW_REQUIRED کند؛ مانده کل مشتری همچنان از Ledger محاسبه می‌شود. تطبیق دستی تخصیص‌ها مانده حساب را عوض نمی‌کند.

بدنه ثبت معمولی فیلد الزامی تازه ندارد. پرداخت جدید به‌صورت پیش‌فرض AUTO است؛ برای رفتار مستقل NONE بفرستید. کنترل ارزِ سمت درست معامله اکنون صریح است و ارجاع نامعتبر رد می‌شود. پیش‌نمایش اختیاری است. گزارش‌های پیش‌فرض ستون‌های بیشتری دارند؛ fields صریح قدیمی معتبر می‌ماند.

بازپخش کلیدهای Idempotency قدیمی ممکن است به دلیل قرارداد ورودی پیش‌فرض نسخه جدید تعارض بدهد. برای رفع تعارض، کلید جدید نسازید مگر مطمئن باشید سند قبلی ثبت نشده است؛ ابتدا سند قبلی را پیدا و تطبیق کنید.

## آزمون MySQL مستقل

```bash
docker compose -f compose.test.yaml up --build --abort-on-container-exit --exit-code-from test
```

این فایل دیتابیس آزمایشی مستقل می‌سازد. بدون Docker، TEST_DATABASE_URL را به دیتابیس جدا با پسوند _test بدهید و npm run test:integration اجرا کنید. آزمون migration، ثبت، پیش‌نمایش، بازپخش، گزارش، CSV، تنظیم گزارش، تخصیص، رسید و ابطال را پوشش می‌دهد. نبود متغیر تست به SKIP می‌انجامد و تأیید اتصال دیتابیس نیست.