# User Flows — دوازده فرآیند عملیاتی MVP VNOS
نسخه 0.2.0 | وضعیت: Draft for UAT validation | مرجع [دامنه MVP](README.md)

## قرارداد مشترک تمام Flowها
هر جریان شامل Actor/Trigger/Precondition/Happy Path/Alternative/Failure/Postcondition/Acceptance و API transaction است. UI فقط client است؛ همان command باید با API قابل اجرا باشد. همه commands دارای actor, orgScope, correlationId, idempotencyKey (برای mutations حساس)، policyVersion و audit هستند. نام endpointها نمونه طراحی‌اند، **API پیاده‌شده نیستند**.

## F01 — ثبت شبکه، سازمان و قرارداد
**Actor:** God Admin، مدیر سازمان، Network Operator. **Trigger:** تأسیس شبکه نمونه. **Pre:** حساب مدیر معتبر و policy مجاز.
1. مدیر یک network/industry configuration ایجاد می‌کند؛ واحدها، ارزها و timezone ثبت می‌شوند.
2. Template مدل‌های Organization/Facility/Product/Lot/Order/Shipment/Journal به نسخه انتشارنیافته کپی می‌شود.
3. فیلدها، relationship و validations از Studio مشخص و schema impact preview می‌شود.
4. Config publish با approval در Schema Engine به نسخه منتشرشده تبدیل می‌شود؛ هر خطای migration بدون فعال‌شدن runtime برمی‌گردد.
5. دعوت‌نامه به مدیر ورامین، سمیرا و افق ارسال می‌شود؛ identity با membership و tenant context مستقل ایجاد می‌گردد.
6. سازمان‌ها محل‌ها، انبارها، کدهای کالا و دسترسی عوامل خود را ثبت می‌کنند.
7. مدیر روابط تجاری را ایجاد، contract type، effectiveFrom/to، مسئولان تأیید و workflow مجاز را تعیین می‌کند.
8. هر طرف نسخه قرارداد را تأیید می‌کند؛ پس از تأیید همه طرف‌های الزامی وضعیت Active می‌گیرد.
**Alt:** دعوت expire/revoke؛ قرارداد نسخه اصلاحی؛ یک کاربر عضو چند سازمان با switch context. **Failure:** duplicate org identifier، scope نامجاز، unpublished metadata، conflicting contract. **Post:** network با اعضا و قواعد معتبر؛ تاریخچه نسخه‌ها باقی بماند.
**Acceptance:** tenant isolation، ایجاد قرارداد با API، تغییر فیلد بدون patch، عدم لو رفتن شروط قرارداد به شرکت فاقد مجوز.

## F02 — ورود محموله و اعلام موجودی گندم
**Actor:** اپراتور ورامین و کارشناس QC. **Trigger:** ورود واقعی یا موجودی اولیه.
1. نقش انتخاب شرکت/محل، منبع ثبت (manual/API/CSV) را مشخص می‌کند.
2. lot با externalRef، origin، country، shipment/receipt، quantity+unit، تاریخ، silo و attachments ثبت می‌شود.
3. runtime unit conversion، validation، duplicate externalRef و اعتبار اسناد را کنترل می‌کند.
4. Create lot → Declared؛ منشأ داده و زمان دریافت ذخیره می‌شود.
5. نقش QC وزن واقعی، درجه کیفی و اسناد را تأیید/رد/نیازمند بررسی می‌کند.
6. پس از Accepted و release، inventory position ایجاد یا به‌روزرسانی و Available qty محاسبه می‌شود.
**Alt:** بچ چند منبع/چند سیلو یا split با linking events. **Failure:** سند ناقص → PendingEvidence؛ خطای وزن → Disputed؛ QC نامقبول → Quarantined؛ duplicated request → همان result اول. **Post:** lot پذیرش‌شده با موجودی قابل رزرو یا مغایرت قابل پیگیری.
**Acceptance:** هیچ lot در حالت Declared قابل مصرف/رزرو نیست مگر policy مصوب مشخص؛ quantity و source قابل ممیزی باشند.

## F03 — سفارش افق کوروش
**Actor:** خریدار مجاز افق، تأییدکننده سمیرا. **Trigger:** برنامه تأمین SKU.
1. Buyer SKU، specification، quantity، store/warehouse مقصد و date window انتخاب می‌کند.
2. runtime قرارداد فعال، قیمت مؤثر (اگر approved)، حداقل سفارش و مجوز را بررسی می‌کند.
3. Draft قابل ذخیره/ویرایش، سپس Submit با شماره و revision ایجاد می‌شود.
4. سمیرا سفارش را به Accepted, PartiallyAccepted, CounterProposed یا Rejected هدایت می‌کند.
5. در counter، افق مقدار/شرایط را می‌بیند و تأیید/رد می‌کند؛ نسخه قبلی برای ممیزی حفظ می‌شود.
6. Confirm نهایی در دامنه تأمین، برنامه یا رزرو بعدی را ایجاد می‌کند.
**Alt:** ثبت تقاضا از طرف سمیرا (supply-led) از همین engine، نه flow کدنویسی جدا. **Failure:** contract expired، SKU unauthorized، duplicate external order، negotiation timeout. **Post:** سفارش نسخه‌دار با commitments مصوب.
**Acceptance:** تغییر مقدار بعد از Confirm نیازمند amendment و تأثیر روی رزروهاست؛ direct DB edit ممنوع.

## F04 — تبدیل سفارش به برنامه تولید و درخواست آرد
**Actor:** برنامه‌ریز سمیرا. **Trigger:** Accepted customer order یا forecast قابل استفاده.
1. سفارش باز و available finished goods بررسی می‌شود.
2. effective BOM version برای SKU و تاریخ مشخص می‌شود.
3. نیاز gross ingredients و net shortage از inventory available محاسبه می‌شود؛ output برنامه شامل expected yield و waste است.
4. capacity calendar و schedule line تست می‌شود؛ plan تا آن زمان Draft است.
5. موجودی مصرفی reserve می‌شود؛ کسری با material requisition به ورامین ارسال می‌شود.
6. پاسخ قیمت/تاریخ/مقدار ورامین با قراردادی سازگار بررسی و تأیید می‌شود.
7. Release production plan فقط وقتی reservations و dependencyها معتبرند.
**Alt:** ظرفیت ناکافی → تقسیم به چند run یا درخواست اصلاح تحویل. **Failure:** BOM missing، cross-org unit mismatch، stale inventory version، overbooking. **Post:** order → plan → material need → supplier request رابطه یکتا/چندگانه.
**Acceptance:** دو planner هم‌زمان نمی‌توانند بیش از Available رزرو کنند.

## F05 — پذیرش درخواست آرد و تخصیص گندم
**Actor:** فروش/عملیات ورامین. **Trigger:** material request سمیرا.
1. Request بررسی و grade flour، volume، delivery window و شروط قرارداد مقایسه می‌شود.
2. ظرفیت آسیاب و stock با توجه به reserved، quarantine و کیفیت سنجیده می‌شود.
3. Allocation plan مجموعه lotهای گندم با نسبت/مقدار پیشنهاد می‌دهد.
4. Confirm allocation به صورت atomic مقدار قابل استفاده را reserve می‌کند.
5. پذیرش کامل/جزئی/رد/CounterOffer به سمیرا ارسال می‌شود.
6. در لغو یا انقضا، reservation با event جبرانی آزاد می‌شود.
**Failure:** موجودی کافی اما QC pending → cannot reserve؛ mismatch در grade → Reject/Alternate ؛ expiry → state transition. **Post:** توافق تأمین و رزرو قابل ردیابی.
**Acceptance:** reservation invariant و audit actor/decision برقرار باشد.

## F06 — عملیات آسیاب و ایجاد بچ آرد
**Actor:** اپراتور تولید و QC ورامین. **Trigger:** Released manufacturing order.
1. Create run با recipe version، machine، plan و input lot candidates.
2. Start run پس از تضمین reservation/QC و ثبت actual input consumption per lot.
3. مصرف ثبت و inventory movement با transaction id مرتبط می‌شود.
4. Actual output flour lot(s)، byproducts و waste با qty/unit ثبت می‌شود.
5. mass balance: total normalized input = output + byproduct + registered losses ± approved tolerance؛ اختلاف پرونده Discrepancy ایجاد می‌کند.
6. QC نتیجه flour lot را Released/Held/Rejected می‌کند.
7. Run Complete فقط بعد از کنترل؛ lineage edges ورودی→خروجی ثبت می‌شوند.
**Alt:** یک run از چند lot و چند output؛ partial run/stop/rework با consumption و correction واضح. **Failure:** negative stock، output بدون input، unbalanced mass، recipe unpublished. **Post:** بچ آرد با genealogy و balance.
**Acceptance:** input 1000kg نمی‌تواند خروجی 1000kg را بدون balance واقعی/فرمول/شواهد خودکار تولید کند.

## F07 — حواله، حمل و رسید آرد
**Actor:** انبار ورامین، حمل، انبار سمیرا. **Trigger:** released flour ready.
1. shipment را به material request/lot تخصیص و manifest با qty و vehicle/driver (طبق privacy policy) ثبت می‌کند.
2. Dispatch مقدار را از محل مبدأ خارج یا به inTransit منتقل می‌کند؛ ownership change فقط اگر قرارداد صریح باشد.
3. receiver بر اساس reference shipment رسید جزئی/کامل یا رد ثبت می‌کند.
4. وزن خروج/ورود و QC، shortage/damage را مقایسه می‌کند؛ discrepancy case باز می‌شود.
5. فقط acceptedQty به موجودی قابل مصرف سمیرا افزوده می‌شود.
6. invoice/acceptance milestone به financial domain event می‌فرستد، نه پرداخت خودکار.
**Alt:** چند محموله برای یک سفارش، تأخیر حمل، receipt بعدی، partial return. **Failure:** invalid lot، duplicate receipt، unauthorized destination، اختلاف خارج tolerance. **Post:** received/partial/disputed و inventory transaction مستند.
**Acceptance:** custody, ownership, invoice and payment states independently testable.

## F08 — تولید ماکارونی و QC محصول
**Actor:** برنامه‌ریز/تولید/QC سمیرا. **Trigger:** مواد اولیه پذیرفته‌شده و برنامه آزاد.
1. تولید با BOM version و plan راه‌اندازی می‌شود.
2. actual flour lot/other ingredient lot و مقدار مصرف هر ورودی ثبت می‌شود.
3. quantity product package, net weight, loss, scrap, rework و output SKU/lot ثبت می‌شود.
4. unit conversion و yield با tolerance پیکربندی‌شده کنترل می‌شود.
5. QC خروجی را approve/hold/reject می‌کند.
6. بر اساس accepted output، finishedGoods inventory ساخته می‌شود؛ genealogy ذخیره می‌ماند.
**Alt:** چند بچ آرد به یک batch محصول؛ تغییر recipe بین batchها فقط با version جدا. **Failure:** material not accepted، lot expired، expired BOM، fail QC. **Post:** product batch traceable.
**Acceptance:** every produced batch has actual inputs and no phantom consumption.

## F09 — تحویل محصول به افق و انتقال شعب
**Actor:** ارسال سمیرا، انبار افق، مسئول انتقال داخلی افق. **Trigger:** fulfilled retail purchase order.
1. سفارش مقدار باز و available product lots را نمایش می‌دهد.
2. pick-pack per lot و shipment manifest ایجاد می‌شود.
3. dispatch، transport و proof-of-delivery ثبت؛ partial delivery قابل پیگیری.
4. افق در warehouse receipt مقدار/QC واقعی را تأیید یا dispute می‌کند.
5. انتقال warehouse→store با event/lot association ثبت می‌شود اگر WMS data موجود باشد.
6. stock on hand فروشگاه از همان ledger مشتق می‌شود.
**Alt:** partial shipment، damaged returns، rejected batches، missing receipt. **Failure:** barcode SKU/lot mismatch؛ reference missing. **Post:** inventory visibility با evidence.
**Acceptance:** محصول نامعلوم به‌صورت قطعی به lot قابل ادعا لینک نشود.

## F10 — ورود فروش POS و مرجوعی
**Actor:** integration account، کارشناس افق. **Trigger:** POS batch/API/webhook یا فایل.
1. source config و schema version انتخاب می‌شود؛ mapping fields (sourceSaleId, store, SKU, time, qty, price, tax/discount, currency, optional lot) اعمال می‌شود.
2. validate auth, sourceScope, timestamp, units, duplicate key و event signatures (اگر فراهم) انجام می‌شود.
3. Event Received → Validated/Quarantined → Accepted؛ duplicate request «هیچ اثر دوم» ندارد.
4. ثبت sale inventory consumption طبق evidence؛ اگر batch در POS نیست confidence SKU-only و inferred allocation جدا نشان داده می‌شود.
5. refund/return با original sale reference و reversal/change ثبت می‌شود.
6. کارشناس فروش accepted records را با store inventory و فروش گزارش‌شده reconcile می‌کند.
**Alt:** POS دیررس، offline store، فایل ناقص، اصلاح بعدی. **Failure:** unknown SKU، missing store، negative count، duplicate source key. **Post:** فروش دارای منبع و تطبیق.
**Acceptance:** دو بار import یک فایل باعث دو برابر شدن فروش/طلب نمی‌شود؛ inferred lot به‌عنوان exact نمایش نمی‌یابد.

## F11 — محاسبه سهم و سندهای مالی
**Actor:** Financial analyst، domain service. **Trigger:** مجاز شدن event مالی طبق rule version.
1. engine بر اساس contract version، eligible events و currency، computation draft می‌سازد.
2. base price, taxes, discounts, returns, fee, distribution share و dueDate با شرح و formulaVersion محاسبه می‌شوند.
3. draft با evidence تحویل/فروش reconcile و برای تأیید افراد مجاز فرستاده می‌شود.
4. بعد از approval، balanced double-entry journal ساخته می‌شود؛ debit sum == credit sum (per currency/book).
5. receivables/payables و maturity schedule به‌روزرسانی می‌شوند.
6. adjustment/reversal با link به سند قبلی ثبت؛ ثبت مالی گذشته silently تغییر نمی‌کند.
**Alt:** سهم مبتنی بر تحویل یا فروش طبق config مصوب؛ multi-party allocation. **Failure:** rule inactive, mismatch in currency, unbalanced journal, dispute unresolved. **Post:** سند posted و audit.
**Acceptance:** همۀ درصدها configuration/versioned؛ هیچ self-transfer و پرداخت بانکی ادعا نشود.

## F12 — تطبیق، مدرک پرداخت و بستن دوره
**Actor:** مالی طرفین، اپراتور حل اختلاف. **Trigger:** پایان دوره و ارائه داده طرف‌ها.
1. close preview: فروش، برگشت، تحویل، journal، outstanding invoices، variance و late data.
2. مسئولان مجاز اختلاف‌های open را تعیین‌تکلیف و correction لازم را ثبت می‌کنند.
3. اگر مدرک پرداخت بیرونی آمد، record به وضعیت ClaimedProof می‌رود؛ verification توسط مسئول/بانک سپس Reconciled.
4. partial settle باقی‌مانده open را حفظ می‌کند و dueDate/aging می‌ماند.
5. نتیجه period review برای طرف‌های مصوب می‌رود، approvalها با timestamp ثبت می‌شوند.
6. close locks period؛ late event فقط طبق correction policy به دوره باز/adjustment می‌رود.
7. traceability report و statement قابل export و audit ایجاد می‌شود.
**Alt:** payment failed; disputed receipt; refused approval; re-open controlled by exceptional permissions. **Failure:** outstanding dispute، journal out-of-balance، missing required approval، overmatch amount. **Post:** Closed period، مانده و مدارک قابل بررسی.
**Acceptance:** سند رسید به معنی انتقال وجه تاییدشده نیست؛ close ممنوع در صورت بازبودن blockerهای سیاست.

## 13. جریان خطای مشترک
**E01 retry/duplicate:** same idempotency key + same payload returns same result; different payload with same key → conflict.  
**E02 authorization:** access denied produces stable error and security audit; never exposes other org data.  
**E03 malformed integration:** preserve raw source metadata securely, quarantine, map fix, controlled replay.  
**E04 late/out-of-order event:** version/timestamp compare, event ordering policy, no silent overwrite.  
**E05 concurrency:** optimistic version / transactional locks protect allocation and balances.  
**E06 manual correction:** reason and actor required; create correction/compensating event, not direct history rewrite.  
**E07 workflow timeout:** overdue escalation/expiry according to configurable SLA.  
**E08 infrastructure:** transactional outbox, idempotent consumers, retry/dead-letter with operator visibility.