tehran_taj/docs/PRESENTATION-GUIDE.md

# راهنمای ارائه — گلدبانک

> تاریخ: ۲۰۲۶-۱۰-۱۴ (۱۴۰۵/۰۷/۲۲) · بر اساس کد فعلی مخزن. اعداد آزمون‌ها از تاریخ خودشان نقل شده‌اند.
> این سند برای ارائه است: اول منطق کار را توضیح می‌دهد، بعد جزئیات فنی. نام فایل‌ها فقط در پیوست آمده است.

---

## ۱. نگاه کلی

گلدبانک از سه برنامه و یک سرور تشکیل شده:

| بخش | کاربر | کار |
|---|---|---|
| **سرور (API)** | — | تمام قانون‌های کسب‌وکار: مشتری، محصول، سفارش، بدهی، اتصال به حسابداری |
| **پنل ادمین** | مدیر، کارشناس فروش، حسابدار، سرپرست کارگاه | مدیریت مشتریان، محصولات، سفارش‌ها، تنظیمات |
| **اپ مشتری** (دو نسخه) | مشتری و مغازه‌دار | ثبت‌نام، ورود با پیامک، کاتالوگ، سفارش، مانده و گزارش حساب |

سه موضوع اصلی که باید در ارائه روشن شود:

1. **اشخاص** — چه کسی مشتری است، چطور تأیید می‌شود و چه سقفی دارد.
2. **محصولات** — کالا، واریانت، عکس، موجودی و اجرت.
3. **اتصال به حسابداری** — مهم‌ترین بخش؛ اپ با ته‌حساب یا زرین همگام می‌شود.

**اصل طراحی که همه‌ی بخش‌ها روی آن ساخته شده:** دفتر داخلی (`LedgerEntry`) فقط افزودنی است. هیچ ردیفی ویرایش یا حذف نمی‌شود؛ بدهی هر مشتری از جمع این ردیف‌ها به دست می‌آید و ستون‌های مانده در مشتری فقط کش آن‌ها هستند.

---

## ۲. اشخاص

### ۲.۱ انواع «شخص» در سامانه

- **مشتری (Customer):** کلید شناسایی او **شماره موبایل** است و یکتاست. کد ملی اختیاری است (از ۲۰۲۶-۱۰-۰۷ به بعد). نوع مشتری یکی از این‌هاست:
  - مغازه‌دار اپ، مغازه‌دار حضوری، بنکدار، سرپرست کارگاه، تک‌فروشی.
- **کاربر ادمین (AdminUser):** نقش‌ها: مدیر کل، تأییدکننده‌ی سیستم، **کارشناس فروش**، سرپرست کارگاه، حسابدار.
  - کارشناس فروش هم یک حساب معاملاتی مشتری دارد و با همان پیامک وارد اپ می‌شود.

### ۲.۲ چرخه‌ی زندگی یک مشتری

1. **ثبت‌نام در اپ:** مشتری فرم را پر می‌کند (نام، فروشگاه، تلفن، آدرس، شهر). حساب **غیرفعال** ساخته می‌شود و وضعیت آن «مرحله‌ی اول ارسال شد» است. با شماره‌ای که قبلاً ثبت شده، ثبت‌نام تازه پذیرفته نمی‌شود. تعداد ثبت‌نام از هر IP محدود است.
2. **بررسی ادمین در دو مرحله:**
   - تأیید مرحله‌ی اول: حساب فعال می‌شود و وضعیت «مرحله‌ی دوم» می‌گیرد.
   - تأیید مرحله‌ی دوم: وضعیت **تأییدشده (VERIFIED)**. همین لحظه حساب در حسابداری ساخته یا لینک می‌شود (بخش ۵).
   - رد: وضعیت **ردشده** با دلیلی که ادمین می‌نویسد. دلیل برای مشتری‌های قدیمی که دلیل نداشتند، متن ثابت «فاقد شرح علت» است.
3. **ورود با کد پیامکی (OTP):** کد هش می‌شود، انقضا دارد، تعداد تلاش‌های غلط محدود است و ارسال برای هر شماره و هر IP محدود است. فقط حساب فعال و غیرآرشیو وارد می‌شود.
4. **سه کلید جدا برای کنترل:**
   - `isActive`: حساب روشن یا خاموش.
   - `canPlaceOrders`: «معلق کردن سفارش» — مشتری از اپ سفارش نمی‌دهد. ادمین می‌تواند از پنل برایش سفارش ثبت کند.
   - `isArchived`: آرشیو.

### ۲.۳ سقف اعتبار و بدهی

- هر مشتری یک **سقف گرمی** دارد (`goldCreditLimitGrams`) و یک **بدهی طلای داخلی** (`goldDebtGrams`).
- وقتی سفارش ثبت می‌شود: اگر `وزن سفارش + بدهی فعلی` از سقف بیشتر شود، سفارش در وضعیت **معلق** ثبت می‌شود و مشتری پیامک می‌گیرد.
- **این چک فقط با دفتر داخلی انجام می‌شود، نه با حسابداری.** مانده‌ی حسابداری به مشتری نشان داده می‌شود، اما سقف اعتبار دست نمی‌خورد (تصمیم مالک، D27).

### ۲.۴ کارشناس فروش (معرف)

- هر مشتری می‌تواند یک کارشناس فروش معرف داشته باشد.
- **سفارش، کارشناسِ همان لحظه‌ی ثبت را می‌گیرد.** اگر بعداً معرف مشتری عوض شود، فروش‌های گذشته جابه‌جا نمی‌شوند (حکم مالک).
- کارشناس می‌تواند با «ورود به حساب مشتری» به جای او سفارش ثبت کند. سفارش کاملاً مال مشتری است، ولی در لاگ ثبت می‌شود که چه کسی واقعاً آن را ثبت کرده است.

### ۲.۵ صفحات ادمین برای مشتریان

- **لیست‌ها:** عمده (همه)، بنکدار، مغازه‌دار، تأییدنشده، آرشیو، تک‌فروشی، کارشناسان فروش.
- **عملیات:** تأیید یا رد مرحله‌ها، فعال و غیرفعال، معلق سفارش، آرشیو، شارژ کیف پول، ثبت بازپرداخت، داشبورد مشتری، سفارش‌ها و اسناد او.
- **بازپرداخت** (طلای آب‌شده، حواله، چک، نقد): ثبت آن **در انتظار تأیید** است. تا ادمین تأیید نکند روی بدهی اثر نمی‌گذارد. این تفاوت عمدی با سیستم قدیم است.

---

## ۳. محصولات

### ۳.۱ ساختار

- **محصول (Product):** عنوان، کد محصول (یکتا)، دسته‌بندی، برند، نوع نمایش (سایت، موبایل یا هر دو)، فعال یا غیرفعال، مجموعه‌ها.
- **واریانت (ProductVariant):** گزینه‌ای که مشتری می‌خرد؛ مثلاً یک وزن مشخص. دارای وزن راش، درصد اجرت پیش‌فرض، موجودی، پیش‌سفارش و تصویر نمایشی.
- **عکس (ProductImage):** چهار نقش دارد: شاخص سایت، شاخص موبایل، گالری سایت، گالری موبایل.

### ۳.۲ قانون‌های مهم

- **بدون عکس، نه نمایش داده می‌شود و نه قابل سفارش است.** این برای همه‌ی محصولات است، نه فقط محصولات حسابداری.
- **موجودی صفر** یعنی قابل سفارش نیست، مگر واریانت پیش‌سفارش باشد.
- **فهرست کاتالوگ صفحه‌بندی شده است** چون تعداد محصولات به حدود ۱۶ هزار می‌رسد.
- **محصول متصل به حسابداری:** عنوان و کد آن در پنل ادمین قفل است و فقط در حسابداری تغییر می‌کند. عکس، توضیح، واریانت، دسته‌بندی و درصد اجرت آزاد است و در اپ تعیین می‌شود.
- **موجودی حسابداری** (اگر محصول متصل باشد): صفر یا کمتر یعنی ناموجود در اپ. موجودی هنگام سفارش **همان لحظه** از حسابداری خوانده می‌شود. اگر حسابداری در ۲٫۵ ثانیه جواب نداد، آخرین موجودی ذخیره‌شده ملاک است.

### ۳.۳ محاسبه‌ی وزن سفارش و اجرت

برای هر قلم سفارش:

> **وزن کل = وزن راش × (۱ + (اجرت − تخفیف) ÷ ۱۰۰) × تعداد**

- **اجرت** = درصد اجرت واریانت + درصد اختصاصی مشتری − **بزرگ‌ترین** تخفیف فعال (روی محصول، دسته یا برند).
- این فرمول همان فرمول قدیمی است. مدیر می‌تواند ضرایب، کف و سقف و گرد کردن آن را در پنل تغییر دهد.
- **سرور خودش اجرت را حساب می‌کند.** اعدادی که اپ مشتری می‌فرستد نادیده گرفته می‌شود، پس دستکاری درخواست در قیمت اثری ندارد. اگر اختلاف باشد، در لاگ ثبت می‌شود.
- بخش ریالی ثابت (مثلاً سنگ) از اپ مشتری صفر است و فقط ادمین می‌تواند آن را وارد کند.

---

## ۴. سفارش و بدهی

### ۴.۱ وضعیت‌های سفارش

| وضعیت | معنی |
|---|---|
| معلق | از سقف گرمی گذشته؛ منتظر تصمیم |
| ثبت‌شده | سفارش آمده |
| تأیید مدیر | مدیر تأیید کرده |
| تأمین | در حال تأمین کالا |
| آماده‌سازی | در حال آماده‌سازی |
| تحویل به مسئول فروش | **نقطه‌ی شناسایی بدهی** (پیش‌فرض) |
| تحویل به مشتری | تحویل نهایی؛ بدهی هم شناخته می‌شود |
| لغو | سفارش کنسل شده |

### ۴.۲ منطق بدهی

- بدهی طلا و ریال سفارش **فقط در دو وضعیت تحویل** (به مسئول فروش یا به مشتری) ثبت می‌شود.
- هر بار که وضعیت عوض می‌شود، سیستم بدهی را با وضعیت سفارش **هم‌تراز** می‌کند: فقط اختلاف را به دفتر اضافه می‌کند. پس:
  - تغییر وضعیت دوباره به «تحویل» بدهی را دوبار ثبت نمی‌کند (این مشکل قبلاً بود و برطرف شده است؛ ACC-03).
  - برگشت به زیر «تحویل» یا لغو، بدهی را برمی‌دارد.
- ثبت بدهی در همان تراکنش تغییر وضعیت انجام می‌شود، پس یا هر دو ثبت می‌شوند یا هیچ‌کدام.

### ۴.۳ سفارش‌های ساختنی (طراحی سفارشی)

**تعریف:** درخواست طراحی و ساخت یک قطعه‌ی سفارشی است (رنگ، سایز، رنگ مینا، رنگ سنگ، عکس طرح). **این کار با «پیش‌سفارش» فرق دارد:** پیش‌سفارش یک گزینه‌ی واریانت است که با موجودی صفر هم قابل خرید است (بخش ۳). سفارش ساختنی یک رکورد جدا (`PreOrder`) است.

**چیزی که هر رکورد دارد:**
- مشتری، شهر، کارگاه، عکس طرح، رنگ‌ها و سایز، وزن و قیمت تخمینی، توضیح.
- وضعیت‌ها: ثبت شده ← تأیید مدیر ← تأیید کارگاه ← آماده ارسال ← تحویل شده. یا لغو.
- تاریخچه‌ی تغییرات (`PreOrderStatusEvent`).

**منطق پنل ادمین** (صفحه «سفارش‌های ساختنی»، مجوز `order.makeOrder`):
- فهرست با جستجو بر اساس نام و موبایل مشتری.
- مشاهده‌ی جزئیات و ویرایش **رنگ محصول، رنگ مینا و رنگ سنگ** (فقط همین سه فیلد ذخیره می‌شوند).
- حذف فقط وقتی ممکن است که سفارش هنوز به سفارش قطعی تبدیل نشده باشد.

**وضعیت واقعی آن در سامانه (برای ارائه‌ی صادقانه):**
- **ثبت جدید وجود ندارد.** نه سرور راهی برای ساختن سفارش ساختنی دارد، نه پنل ادمین و نه اپ‌های مشتری. رکوردها فقط از داده‌ی سیستم قدیم منتقل شده‌اند.
- **تبدیل به سفارش قطعی وجود ندارد.** فیلد `convertedOrderId` در مدل هست، ولی راهی برای پر کردن آن نوشته نشده است. مدل می‌گوید «مدیر تبدیل می‌کند»، اما این کار در کد فعلی امکان‌پذیر نیست.
- **تخصیص کارگاه ذخیره نمی‌شود:** پنل گزینه‌ی انتخاب کارگاه نشان می‌دهد، ولی هنگام ذخیره فقط سه فیلد رنگ فرستاده می‌شود.
- **تعداد ثابت است:** هر سفارش ساختنی تعداد ۱ حساب می‌شود؛ فیلد تعداد در پنل ذخیره نمی‌شود.
- **تغییر وضعیت:** سرور این کار را می‌پذیرد، ولی پنل آن را نشان نمی‌دهد.

### ۴.۴ لیست تامین

**تعریف:** فهرست سفارش‌هایی که به مرحله‌ی **«در حال تأمین»** رسیده‌اند؛ یعنی مرحله‌ای که کالا یا مواد لازم برای ساخت تهیه می‌شود. مجوز `order.tamin` (صفحه‌ی «لیست تامین»).

**منطق نمایش:**
- فهرست شامل **سفارش‌هایی است که حداقل یک‌بار** به وضعیت «در حال تأمین» رسیده‌اند، حتی اگر حالا جلوتر رفته باشند (تأمین شده یا آماده‌سازی). این یعنی فهرست «تاریخچه‌ی تأمین» است، نه فقط «الان در تأمین».
- ستون‌ها: شماره، مشتری، موبایل، وزن ورودی، اجرت، تعداد آیتم، تاریخ ثبت و تاریخ ویرایش.
- با کلیک روی یک سفارش، جزئیات آیتم‌ها باز می‌شود: نام محصول، عنوان واریانت، وزن نهایی، تعداد.

**تغییر وضعیت از این فهرست:**
- با مجوز `order.tamin.state` می‌توان وضعیت را ثبت کرد. هر ثبت یک یادداشت دارد و در تاریخچه‌ی سفارش می‌نشیند.
- وضعیت آخر را می‌توان حذف کرد (با مجوز `order.tamin.state.remove`)؛ سفارش به وضعیت قبلی برمی‌گردد.
- هر تغییر وضعیت **همان منطق بدهی و سند حسابداری** سفارش (بخش ۴.۲ و ۵.۸) را اجرا می‌کند. یعنی ثبت یا حذف وضعیت می‌تواند بدهی و سند حسابداری را جابه‌جا کند.

**نقص‌های شناخته‌شده (باید گفته شود):**
- **ستون «وضعیت تأیید مشتری» خالی است.** پنل این ستون و فیلتر آن را دارد، ولی سرور این فیلد را برنمی‌گرداند. پس این فیلتر عملاً کاری نمی‌کند.
- **نام صفحه با عنوان آن یکی نیست:** عنوان کارت «لیست سفارش‌های عمده» است، همان عنوان فهرست عمده. این عمداً در نسخه‌ی قدیم هم همین بود و تغییر داده نشده است.

---

## ۵. اتصال به حسابداری (بخش مهم)

### ۵.۱ خلاصه

اپ به **یکی** از دو نرم‌افزار حسابداری که روی سرور شرکت نصب است وصل می‌شود:

- **ته‌حساب** (Tahesab)
- **زرین** (Zarrin)

انتخاب با یک سوییچ در پنل ادمین انجام می‌شود: `بدون اتصال / ته‌حساب / زرین`. هر بخش هم جداگانه روشن یا خاموش می‌شود. تا وقتی ادمین روشن نکند، سیستم هیچ ارتباطی برقرار نمی‌کند.

### ۵.۲ آنچه همگام می‌شود

| بخش | جهت | کار |
|---|---|---|
| **مشتریان** | حسابداری ← اپ | حساب‌های گروه‌های انتخاب‌شده وارد اپ یا به مشتری موجود لینک می‌شوند |
| **مشتریان** | اپ ← حسابداری | مشتری تأییدشده در حسابداری ساخته می‌شود؛ ویرایش مشخصات هم فرستاده می‌شود |
| **مانده** | حسابداری ← اپ | مانده‌ی طلا و ریال مشتری، نمایش در پروفایل |
| **گزارش حساب** | حسابداری ← اپ | صورت‌حساب مشتری از حسابداری خوانده می‌شود تا با مانده یکی باشد |
| **کارساخته / محصول** | دو طرفه | عنوان، کد و موجودی همگام؛ محصول تازه‌ی حسابداری در اپ ساخته می‌شود |
| **سند سفارش** | اپ ← حسابداری | سند موقت (پیش‌فاکتور) در وضعیتی که مدیر تعیین کرده ثبت می‌شود |

**عمداً همگام نمی‌شود:** اسناد دریافت و بازپرداخت (طلای آب‌شده، نقد، چک)، کیف پول. این‌ها در اپ می‌مانند.

### ۵.۳ لحظه‌ای بودن — چطور کار می‌کند

سه لایه، چون هیچ‌کدام از دو نرم‌افزار وب‌هوک ندارند:

1. **صف خروجی (Outbox):** هر رویداد لازم برای حسابداری (مثلاً ثبت سفارش) **در همان تراکنش** دیتابیس یک ردیف در صف می‌نویسد. پس اگر حسابداری خاموش باشد، هیچ رویدادی گم نمی‌شود و ثبت سفارش در اپ متوقف نمی‌شود.
2. **کارگر (worker) داخل سرور:**
   - هر **۲ ثانیه** صف را می‌فرستد.
   - هر **۵ ثانیه** فید تغییرات حسابداری را می‌خواند؛ فقط حساب‌ها و کارساخته‌های تغییرکرده دوباره خوانده می‌شوند.
3. **شبکه‌ی اطمینان:** هر **۳۰ ثانیه** کارهای کامل اجرا می‌شود تا چیزی که فید نمی‌بیند (حذف، مشتری جدید بدون سند) گم نشود.

قوانین تکمیلی:

- **قفل:** اگر چند نمونه‌ی سرور در حال اجرا باشند، فقط یکی کارها را اجرا می‌کند.
- **شکست:** تلاش دوباره با فاصله‌ی نمایی، حداکثر ۸ بار؛ بعد وضعیت «ناموفق» و نمایش در پنل.
- **تکرار خطرناک:** اگر نتیجه‌ی یک درخواست نامشخص باشد و تکرار آن سند را دو بار ثبت کند، کار به وضعیت **«نیاز به بررسی»** می‌رود و خودکار دوباره فرستاده نمی‌شود.
  - ته‌حساب: قبل از تلاش دوباره، سیستم استعلام می‌کند که سند قبلاً ثبت نشده باشد.
  - زرین: کلید ضد تکرار ندارد، پس در صورت timeout فقط بررسی دستی.
- **مانده در پروفایل مشتری:** اگر قدیمی‌تر از ۵ ثانیه باشد، همان لحظه از حسابداری خوانده می‌شود (مهلت ۳ ثانیه). اگر جواب نداد، آخرین مقدار نشان داده می‌شود.

### ۵.۴ مشتری — ورود، لینک و ساخت

**منبع:** فقط گروه‌هایی که در تنظیمات انتخاب شده‌اند. اگر هیچ گروهی انتخاب نشده باشد، ورود متوقف می‌شود (چون «همه» یعنی صندوق‌ها و کارمندان هم مشتری اپ شوند).

**کلید تطبیق:** شماره موبایل نرمال‌شده (ارقام فارسی به انگلیسی، `912…` به `0912…`).

- موبایل در اپ هست ← **لینک** می‌شود و کد حسابداری ذخیره می‌شود.
- موبایل در اپ نیست ← **مشتری تازه در اپ** ساخته می‌شود:
  - وضعیت «تأییدنشده»، سقف اعتبار صفر، ورود فقط با پیامک.
  - کد ملی از حسابداری گرفته می‌شود اگر معتبر و آزاد باشد؛ وگرنه **خود شماره موبایل** به‌عنوان کد ملی ذخیره می‌شود. این یک راه‌حل موقت است و باید بعداً پاک شود (بخش ۸).
- موبایل خالی، یا دو حساب با یک موبایل ← به **فهرست مغایرت** می‌رود و خودکار اقدامی نمی‌شود.

**ارسال به حسابداری (push):**

- وقتی مشتری **تأیید نهایی** شد، ابتدا با موبایل جستجو می‌شود. اگر پیدا شد لینک می‌شود؛ اگر نه، حساب تازه در گروه مشخص‌شده ساخته می‌شود.
- این کار فقط یک‌بار برای مشتری بدون لینک انجام می‌شود.
- تغییر نام، تلفن یا آدرس مشتری لینک‌شده هم فرستاده می‌شود.

### ۵.۵ مانده

- **علامت:** در اپ، **مثبت یعنی بدهکار**. ته‌حساب مانده‌ی منفی را بدهکار نشان می‌دهد و در درایور برعکس می‌شود. در زرین پیش‌فرض «منفی = بدهکار» است و قابل تنظیم است.
- **نمایش:** در پروفایل مشتری دو مانده کنار هم: طلا (گرم) و ریال، به همراه زمان آخرین به‌روزرسانی.
- **اعتبار:** سقف اعتبار با مانده‌ی حسابداری حساب نمی‌شود؛ همان دفتر داخلی است.

### ۵.۶ گزارش حساب

- وقتی اتصال روشن باشد، گزارش از حسابداری خوانده می‌شود تا با مانده یکی باشد.
- اگر حسابداری جواب ندهد، گزارش **از دفتر داخلی** نشان داده می‌شود و در صفحه برچسب منبع می‌خورد. صفحه باز می‌ماند.
- **امنیت:** جزئیات هر سند فقط وقتی نشان داده می‌شود که کد حساب سند با کد لینک‌شده‌ی همان مشتری یکی باشد.
- **تفاوت دو حسابداری:** در ته‌حساب، سند موقت روی مانده اثر ندارد تا حسابدار آن را نهایی کند. در زرین، سند موقت همان لحظه روی مانده اثر دارد.

### ۵.۷ کارساخته و محصول

- **از حسابداری به اپ:** کارساخته‌ی جدید ← محصول جدید در اپ، **بدون عکس و بدون واریانت**. تا ادمین عکس و واریانت نگذارد، در اپ دیده نمی‌شود.
- **از اپ به حسابداری:**
  - **زرین:** محصول جدید در پنل ← کارساخته‌ی جدید در زرین ساخته می‌شود. (ساخت کارساخته روی نصب واقعی هنوز آزمایش نشده است.)
  - **ته‌حساب:** API ساخت کارساخته ندارد. نام کار با **اولین سند** آن در ته‌حساب ساخته می‌شود و از آن به بعد لینک می‌شود. این محدودیت از خود API است.
- **موجودی:** در پنل ادمین نشان داده می‌شود. صفر یا کمتر ← ناموجود در اپ.

### ۵.۸ سند سفارش

- **زمان ثبت:** هر وضعیتی که مدیر در تنظیمات مشخص کرده باشد (پیش‌فرض: تحویل به مسئول فروش) یا بعد از آن. سند **موقت** (پیش‌فاکتور) ثبت می‌شود و **یک‌بار** فرستاده می‌شود.
- **برگشت:** اگر سفارش به وضعیت زیر آن برگردد یا لغو شود، سند پس گرفته می‌شود. اگر سند هنوز موقت باشد، حذف می‌شود؛ اگر در حسابداری نهایی شده باشد، کار به «بررسی» می‌رود.
- **ته‌حساب:** هر قلم یک ردیف سند است. کد سند از شناسه‌ی سفارش ساخته می‌شود تا دوبار ثبت نشود.
- **زرین:** سند چندردیفی است و پیشرفت هر ردیف ذخیره می‌شود. اگر وسط کار قطع شود، از همان‌جا ادامه می‌دهد.
- **پذیرش:** بعد از ثبت، تغییر مانده‌ی وزنی حسابداری باید دقیقاً برابر وزن سفارش باشد. این معیار روی سرور تست ته‌حساب آزمایش شده است.
- **اجرت در ته‌حساب:** اجرت به صورت **افزایش عیار** فرستاده می‌شود (مثلاً ۷۵۰ با ۱۰٪ اجرت ← ۸۲۵). وزن فیزیکی کالا ثابت می‌ماند.

### ۵.۹ پنل مدیریت اتصال

صفحه‌ی **«اتصال حسابداری»** با مجوز `config.accounting`:

1. **اتصال:** سوییچ درایور، آدرس، توکن (فقط نوشتنی؛ هرگز نمایش داده نمی‌شود)، گواهی CA برای نصب‌های self-signed، دکمه‌ی «تست اتصال».
2. **نگاشت:** گروه‌های مشتری برای ورود، گروه مشتری تازه، گروه کارساخته به دسته‌بندی، نوع کارساخته، عیار پیش‌فرض، بازه‌ی گزارش.
3. **قابلیت‌ها و زمان‌بندی:** روشن یا خاموش کردن هر بخش، قانون ثبت سند، دکمه‌های «سینک الان».
4. **لاگ:** صف کارها با فیلتر وضعیت، تلاش دوباره، «حل‌شده»، و درخواست و پاسخ هر کار (بدون توکن).
5. **مغایرت‌ها:** موبایل تکراری یا خالی، کارساخته بی‌دسته، سندهای «نیاز به بررسی».

دکمه‌های **«سینک با …»** در لیست مشتریان عمده و لیست محصولات هم هست. این دکمه‌ها مستقل از سوییچ قابلیت‌ها کار می‌کنند و فقط اتصال برقرار بودن لازم است.

**پیش‌فرض:** اتصال خاموش است و همه‌ی قابلیت‌ها غیرفعال. تا ادمین تنظیم نکند، اپ هیچ کاری با حسابداری نمی‌کند.

### ۵.۱۰ امنیت اتصال

- **توکن:** با AES-256-GCM رمز می‌شود. کلید آن از متغیر `ACCOUNTING_SECRET_KEY` می‌آید.
  - اگر این متغیر تنظیم نشده باشد، از `JWT_SECRET` استفاده می‌شود و هشدار داده می‌شود.
  - **تغییر `JWT_SECRET` توکن ذخیره‌شده را غیرقابل خواندن می‌کند** و ادمین باید دوباره وارد کند.
- **هیچ پاسخی توکن را برنمی‌گرداند.** مسیرهای عمومی تنظیمات (`const`) کلیدهای `accounting.*` را نمی‌دهند و نمی‌پذیرند.
- **TLS هرگز خاموش نمی‌شود.** برای نصب‌های با گواهی شخصی، می‌توان گواهی CA را به‌صورت PEM داد.
- **هشدار برای ارائه:** نصب زرین مالک روی **http بدون رمزنگاری** و در دسترس اینترنت است. توصیه: https یا VPN و توکن قوی. این موضوع باید صریح گفته شود.

### ۵.۱۱ وضعیت آزمون (با تاریخ)

| مورد | نتیجه | تاریخ و منبع |
|---|---|---|
| ته‌حساب روی سرور تست عمومی | ۲۹ از ۲۹ بررسی؛ شامل لینک دوباره‌ی همان حساب و سند با وزن دقیق | ۲۰۲۶-۱۰-۰۵ (طرح، بخش ۱۰) |
| زرین روی نصب مالک (v228) — خواندن | همه‌ی بررسی‌ها؛ مانده، صفحه‌بندی کارساخته، گردش | ۲۰۲۶-۱۰-۱۲ (ACC-01) |
| زرین روی نصب مالک — نوشتن | ۲۰ از ۲۰ روی حساب آزمایشی ۹۵۳ | ۲۰۲۶-۱۰-۱۲ (ACC-01) |
| تست‌های واحد درایورها | ۴۳ تست؛ کل سرور ۱۸۰ تست | ۲۰۲۶-۱۰-۰۵ (طرح، بخش ۱۰) |

**آزمون‌نشده:** ساخت کارساخته در زرین روی نصب واقعی؛ سنگ در سند زرین؛ فید تغییرات زرین روی نصب واقعی (زرین با بازه‌ی کارساخته و خواندن لحظه‌ی سفارش جایگزین را پوشش می‌دهد).

### ۵.۱۲ آنچه باید صادقانه گفته شود

- **سند موقت ته‌حساب روی مانده اثر ندارد** تا حسابدار نهایی کند (ACC-02). پس مانده‌ای که مشتری می‌بیند تا نهایی شدن سند، سفارش‌های تازه را شامل نمی‌شود.
- **لحظه‌ای بودن یعنی «چند ثانیه بعد از ثبت در حسابداری»** و نه «در همان لحظه‌ی ثبت». هیچ‌کدام از دو نرم‌افزار وب‌هوک ندارند.
- **قابلیت‌های ناتمام:** ساخت کارساخته در زرین، سنگ در زرین.
- **حساب آزمایشی روی نصب مالک:** برای آزمون نوشتن در زرین، حساب آزمایشی ۹۵۳ («تست اپ گلدبانک») با تأیید مالک ساخته شد. زرین API حذف حساب ندارد، پس این حساب در نصب مالک باقی می‌ماند.

---

## ۶. ترتیب پیشنهادی ارائه (حدود ۲۰ دقیقه)

1. **نگاه کلی** (۲ دقیقه): سه برنامه، اصل دفتر افزودنی.
2. **اشخاص** (۴ دقیقه): ثبت‌نام ← تأیید دو مرحله‌ای ← ورود پیامکی ← سقف اعتبار ← معرف.
3. **محصولات** (۳ دقیقه): واریانت و عکس، قانون بدون عکس، موجودی، فرمول اجرت.
4. **سفارش و بدهی** (۳ دقیقه): وضعیت‌ها، نقطه‌ی شناسایی بدهی، سفارش ساختنی و لیست تامین (بخش ۴.۳ و ۴.۴). بخش ساختنی را با صراحت درباره‌ی نقص‌هایش ارائه کنید.
5. **حسابداری** (۷ دقیقه): سوییچ ← مشتری تأییدشده ← ساخت در حسابداری؛ سفارش ← سند موقت؛ مانده در پروفایل؛ لاگ.
6. **باز و تصمیم‌ها** (۲ دقیقه): بخش ۸.

**هشدار برای نمایش زنده:** برای نشان دادن نوشتن در حسابداری فقط از **سرور تست** استفاده کنید. نوشتن روی نصب مالک بدون تأیید جداگانه‌ی او انجام نشود.

---

## ۷. واژه‌نامه

| واژه | معنی |
|---|---|
| **کارساخته** | کار/محصول ساخته‌شده‌ی طلا؛ در حسابداری یک «کالا» است و در اپ یک «محصول» |
| **ته‌حساب / زرین** | دو نرم‌افزار حسابداری که اپ با آن‌ها همگام می‌شود |
| **مانده** | بدهی یا بستانکاری مشتری؛ در اپ مثبت = بدهکار |
| **سند موقت (پیش‌فاکتور)** | سندی که برای حسابدار ثبت می‌شود و هنوز نهایی نیست |
| **راش (وزن راش)** | وزن خام کالا قبل از اجرت |
| **اجرت** | درصدی که به وزن راش اضافه می‌شود تا وزن کل سفارش به دست آید |
| **عیار** | خلوص طلا بر حسب هزارم؛ ۷۵۰ = ۱۸ عیار |
| **صف خروجی (Outbox)** | فهرست کارهایی که باید به حسابداری فرستاده شود |
| **لینک** | وصل شدن یک مشتری یا کارساخته‌ی اپ به رکورد متناظر در حسابداری |
| **مغایرت** | موردی که سیستم خودکار تصمیم نمی‌گیرد و باید ادمین بررسی کند |
| **معلق** | سفارشی که از سقف گرمی گذشته و منتظر تصمیم است |
| **پیش‌سفارش** | گزینه‌ی واریانت که با موجودی صفر هم قابل خرید است |
| **سفارش ساختنی** | درخواست طراحی و ساخت سفارشی (رنگ، سایز، طرح)؛ رکورد جدا از سفارش خرید |
| **تأمین** | مرحله‌ای که کالا یا مواد لازم برای ساخت سفارش تهیه می‌شود (وضعیت «در حال تأمین») |
| **لیست تامین** | فهرست سفارش‌هایی که حداقل یک‌بار به مرحله‌ی تأمین رسیده‌اند |

---

## ۸. باز و تصمیم‌های لازم قبل از راه‌اندازی

| # | موضوع | وضعیت |
|---|---|---|
| ۱ | **رمز مدیریتی OTP** (`OTP_MASTER_CODE`) در نسخه‌ی تست است و باید قبل از نسخه‌ی واقعی حذف شود. | باز |
| ۲ | **کد ملی = موبایل** برای مشتری‌هایی که از حسابداری ساخته شده‌اند. بدهی داده است و باید پاک شود. | باز (DATA-MIGRATION-MAP §10.4) |
| ۳ | **نصب زرین روی http بدون رمز** — رمزنگاری یا VPN. | باز، تصمیم مالک |
| ۴ | **سند موقت ته‌حساب** روی مانده اثر ندارد تا نهایی شود. | باز، به‌عنوان قانون کار قبول شده (ACC-02) |
| ۵ | **مهاجرت دیتابیس خالی** در ACC-04 گزارش شده. یادداشت‌ها می‌گویند برطرف شده؛ قبل از نصب تازه بررسی شود. | بررسی لازم |
| ۶ | **ساخت کارساخته در زرین** و **فید تغییرات زرین** روی نصب واقعی تأیید نشده‌اند. | آزمون‌نشده |
| ۷ | **ACC-03** (بدهی تکراری) برطرف شده است؛ طرح ۱۰/۰۵ هنوز آن را باز نشان می‌دهد، ولی ملاک فعلی `ISSUES.md` است. | برطرف (۲۰۲۶-۱۰-۰۸) |
| ۸ | **سفارش ساختنی:** ثبت جدید، تبدیل به سفارش قطعی، ذخیره‌ی کارگاه و تعداد در پنل. تصمیم لازم: آیا این بخش در نسخه‌ی اول لازم است؟ | باز، نیاز به تصمیم مالک |
| ۹ | **لیست تامین:** ستون و فیلتر «تأیید مشتری» داده ندارد. | باز (کم‌اهمیت) |

---

## پیوست فنی — نقشه‌ی فایل‌ها

برای پاسخ به سؤال‌های فنی:

**داده و قوانین کلی**
- [apps/api/prisma/schema.prisma](../apps/api/prisma/schema.prisma) — مدل‌ها: `Customer`, `AdminUser`, `Product`, `ProductVariant`, `Order`, `LedgerEntry`, `AccountingLink`, `AccountingOutbox`
- [apps/api/src/modules/accounting/ledger.service.ts](../apps/api/src/modules/accounting/ledger.service.ts) — دفتر داخلی و `syncOrderDebt`

**اشخاص**
- [customer-auth.service.ts](../apps/api/src/modules/customer-auth/customer-auth.service.ts) — OTP، ثبت‌نام، سقف ارسال
- [admin-customers.service.ts](../apps/api/src/modules/admin-customers/admin-customers.service.ts) — تأیید دو مرحله‌ای، سقف اعتبار، فهرست‌ها

**محصولات و سفارش**
- [catalog.service.ts](../apps/api/src/modules/catalog/catalog.service.ts) — قانون عکس و موجودی
- [admin-products.service.ts](../apps/api/src/modules/admin-products/admin-products.service.ts) — قفل عنوان و کد محصول متصل
- [wage-formula.ts](../apps/api/src/modules/pricing/wage-formula.ts) — فرمول اجرت
- [orders.service.ts](../apps/api/src/modules/orders/orders.service.ts) — ثبت سفارش و تغییر وضعیت
- [admin-orders.service.ts](../apps/api/src/modules/admin-orders/admin-orders.service.ts) — `listTamin` (لیست تامین) و `removeStatusEvent`
- [admin-preorders.service.ts](../apps/api/src/modules/admin-preorders/admin-preorders.service.ts) — سفارش‌های ساختنی (فهرست، ویرایش، حذف)
- [MakeOrder.vue](../apps/admin-panel/src/views/order/MakeOrder.vue) و [TaminList.vue](../apps/admin-panel/src/views/order/TaminList.vue) — صفحه‌های پنل این دو فهرست
- [docs/PRODUCT-MODULE.md](PRODUCT-MODULE.md) — جزئیات فرم محصول در پنل

**اتصال به حسابداری**
- [accounting-sync.service.ts](../apps/api/src/modules/accounting-sync/accounting-sync.service.ts) — منطق همگام‌سازی (مشتری، مانده، کارساخته، سند)
- [accounting-hooks.service.ts](../apps/api/src/modules/accounting-sync/accounting-hooks.service.ts) — نقاط ورود از بقیه‌ی برنامه (سفارش، مشتری، محصول)
- [accounting-worker.service.ts](../apps/api/src/modules/accounting-sync/accounting-worker.service.ts) — صف، زمان‌بند، فید تغییرات، قفل، تلاش دوباره
- [accounting-config.ts](../apps/api/src/modules/accounting-sync/accounting-config.ts) — ساختار تنظیمات و پیش‌فرض‌ها
- [providers/tahesab.provider.ts](../apps/api/src/modules/accounting-sync/providers/tahesab.provider.ts) و [providers/zarrin.provider.ts](../apps/api/src/modules/accounting-sync/providers/zarrin.provider.ts) — درایورها
- [accounting-http.ts](../apps/api/src/modules/accounting-sync/accounting-http.ts) — کلاینت HTTP و TLS
- [secret-box.ts](../apps/api/src/modules/accounting-sync/secret-box.ts) — رمزنگاری توکن
- [accounting-admin.controller.ts](../apps/api/src/modules/accounting-sync/accounting-admin.controller.ts) — مسیرهای پنل ادمین
- [customer-report.service.ts](../apps/api/src/modules/customer-report/customer-report.service.ts) — گزارش و مانده برای مشتری

**مستندات مرتبط**
- [ACCOUNTING-INTEGRATION-PLAN.md](ACCOUNTING-INTEGRATION-PLAN.md) — طرح کامل، از جمله بخش‌های ۱۰ تا ۱۳ (وضعیت اجرا، فید لحظه‌ای، زرین)
- [parity/DECISIONS.md](parity/DECISIONS.md) — تصمیم‌های مالک؛ **D27** اتصال به حسابداری
- [parity/ISSUES.md](parity/ISSUES.md) — **ACC-01 تا ACC-09**؛ ملاک وضعیت فعلی