Barcode/QR Scanning UX

سبز شدن دوربین یعنی «خوانده شد»؛ نه اینکه «همان بسته‌ی درست تأیید شد»

فرض کن اپراتور دوربین را روی QR می‌گیرد و decoder در کمتر از یک ثانیه مقدار PKG-84219 را برمی‌گرداند. اگر UI فوراً تیک سبز بزند و مرحله‌ی بسته‌بندی را جلو ببرد، چند سؤال هنوز بی‌جواب مانده: آیا device اصلاً symbology مورد انتظار را پشتیبانی می‌کرد؟ آیا مقدار decoded از نظر ساختار معتبر است؟ آیا این شناسه متعلق به همین order و همین workflow step است؟ آیا همین code پنج ثانیه قبل scan نشده؟ اگر دوربین یا API در دسترس نبود، manual entry از چه مسیر و با چه provenance وارد شد؟

هدف این درس ساخت Scan Capability and Verification Contract v1 است. در این قرارداد capture فقط آغاز مسیر است؛ business confirmation بعد از capability، symbology، parse/structure، context match، dedupe و provenance انجام می‌شود.

مرز مالکیت COM-033

COM-033 مالک UX و evidence مربوط به capture و verification اسکن است. COM-032 درباره‌ی چاپ label، RTL و layout barcode است؛ COM-034 درباره‌ی carrier tracking event و normalization آن است. این درس label تولید نمی‌کند و carrier status را هم تفسیر نمی‌کند.

سه خط قرمز:

1. decoded != verified: decoder success فقط یعنی یک رشته از تصویر/اسکنر به‌دست آمده است.
2. supported != guaranteed: وجود format در getSupportedFormats() تضمین نمی‌کند هر سمبل فیزیکی خوانده شود.
3. valid syntax != valid context: یک GTIN/QR/identifier ساختاریِ صحیح ممکن است برای order دیگری باشد.

مدل ذهنی: Capture → Decode → Normalize → Validate → Bind → Dedupe → Confirm

مسیر درست را مثل یک pipeline ببین:

camera / USB scanner / manual entry → capability adapter → raw decode → format + normalization → structural validation → expected-context match → duplicate check → human-visible confirmation → bounded workflow transition

هر مرحله evidence خودش را دارد. اگر یک مرحله decisive نامعلوم باشد، مسیر به HOLD، UNKNOWN یا FALLBACK_REQUIRED می‌رود؛ UI نباید با یک انیمیشن سبز کمبود evidence را پنهان کند.

FACT، INFERENCE و DESIGN را جدا نگه دار

FACT: Draft فعلی WICG، BarcodeDetector را API مبتنی بر secure context معرفی می‌کند، getSupportedFormats() دارد و صریحاً می‌گوید formatهای پشتیبانی‌شده platform-dependent هستند. همان متن می‌گوید حتی اگر format در فهرست supported باشد، recognition یک تصویر مشخص تضمین‌شده نیست.

FACT: MDN در حال حاضر Barcode Detection API را Limited availability و Experimental علامت می‌زند و توصیه می‌کند compatibility قبل از production بررسی شود.

FACT: GS1 نشان می‌دهد QR Code، Data Matrix و GS1 DataMatrix رفتار و reach یکسانی در دوربین موبایل و POS ندارند. مثلاً QR Code با GS1 Digital Link برای دوربین پیش‌فرض موبایل دسترس‌پذیرتر است، ولی همه‌ی retail systemها همه‌ی 2D carrierها را هنوز یکسان پردازش نمی‌کنند.

INFERENCE: چون capture capability و business identity دو مسئله‌ی متفاوت‌اند، safe UX باید evidence آن‌ها را در stateهای جدا نگه دارد.

DESIGN: MAKNOW الزام می‌کند decoder success به‌تنهایی هیچ business transitionی ایجاد نکند؛ expected-context match، dedupe و fallback provenance باید صریح باشند.

قرارداد ۲۲بعدی Scan Verification

Gate 1 — Capture adapter را اول capability-check کن

برای camera path، فقط وجود window.BarcodeDetector کافی نیست؛ secure context و supported formatها را هم evidence کن. اگر format مورد انتظار پشتیبانی نمی‌شود، به fallback برو. در desktop ممکن است USB scanner مثل keyboard input عمل کند و اصلاً BarcodeDetector موضوع اصلی نباشد؛ پس capability باید متعلق به adapter جاری باشد، نه یک assumption سراسری.

Gate 2 — Expected symbology را قبل از scan اعلام کن

اگر workflow فقط qr_code و code_128 می‌پذیرد، decoded data_matrix را صرفاً به‌خاطر اینکه decoder توانسته بخواند قبول نکن. accepted set بخشی از contract است.

Gate 3 — Raw value و normalized identifier را جدا نگه دار

raw_scan_value evidence دقیق decoder/input است. normalized_identifier نتیجه‌ی parser/normalizer است. trimming، URI parsing، GS1 extraction یا حذف separator باید observable باشد تا audit بفهمد شناسه چگونه ساخته شده است.

Gate 4 — Parse و structure قبل از context

اول syntax/structure را بررسی کن: طول، prefix، check digit یا قواعد schema. فقط بعد از آن lookup یا context binding معنی دارد. مقدار malformed نباید به lookup مبهم فرستاده شود و بعد با نزدیک‌ترین نتیجه match شود.

Gate 5 — Context match مرحله‌ی business identity است

expected_context_id می‌تواند order، package، picking wave یا workflow step باشد. normalized identifier باید در همان context resolve شود. کد کاملاً معتبر متعلق به order دیگر = REJECTED_CONTEXT_MISMATCH.

Gate 6 — Duplicate suppression را با scan identity کنترل کن

دوربین ممکن است یک code را در چند frame پشت‌سرهم بخواند. duplicate_key باید از session + normalized ID + workflow context یا معادل پایدار ساخته شود. duplicate را برای audit ثبت کن، ولی side effect یا transition را تکرار نکن.

Gate 7 — Manual entry fallback است، bypass نیست

اگر camera permission، detector یا symbology fail شد، manual/USB fallback می‌تواند مجاز باشد؛ اما manual_entry_used و fallback_reason باید ثبت شوند. fallback همان parse/context/dedupe gateها را طی می‌کند.

Gate 8 — Confirmation state از evidence ساخته می‌شود

فقط وقتی decisive fields کامل‌اند، parse/structure PASS است، context match مثبت است و scan duplicate نیست، ACCEPTED_VERIFIED مجاز است. هر چیز ضعیف‌تر باید state ضعیف‌تری بگیرد.

Gate 9 — UX باید دلیل non-success را نشان دهد

«اسکن ناموفق» پیام کافی نیست. operator باید بفهمد مشکل capability است، format است، ساختار است، context mismatch است یا duplicate. این تفاوت repair path را تعیین می‌کند.

Gate 10 — Transfer یعنی adapter عوض شود، نه acceptance rule

وقتی از Android Chrome به iOS/Safari یا USB scanner می‌رویم، capture adapter ممکن است تغییر کند؛ اما symbology allow-list، parse، context، dedupe و confirmation contract ثابت می‌ماند. evidence capability باید دوباره اندازه‌گیری شود، نه اینکه baseline copy شود.

مثال‌های حل‌شده

1. Chrome + QR معتبر + context درست → ACCEPTED_VERIFIED

secure context برقرار است، detector qr_code را گزارش می‌کند، raw value parse می‌شود، package داخل order مورد انتظار resolve می‌شود و duplicate نیست. confirmation مجاز است.

2. Detector هست، اما data_matrix در supported formats نیست → FALLBACK_REQUIRED

UI نباید camera را «تقریباً سازگار» حساب کند. مسیر می‌تواند USB/manual fallback بدهد؛ همان verification gateها حفظ می‌شوند.

3. QR معتبر، order اشتباه → REJECTED_CONTEXT_MISMATCH

کد syntactically valid است و package واقعاً وجود دارد، ولی expected context با resolved context یکی نیست. سبزکردن UI در این نقطه false confirmation است.

4. همان package دوباره در همان session → DUPLICATE_SUPPRESSED

scan دوم evidence است، اما transition دوم انجام نمی‌شود. operator پیام مشخص duplicate می‌بیند.

5. Camera permission یا API unavailable → fallback با provenance

manual entry فقط وقتی قابل قبول است که fallback reason ثبت شود و value دوباره parse/context/dedupe شود.

6. Mixed fleet: iOS/Safari + desktop USB

برای هر device capture adapter جدا evidence می‌شود. یک device ممکن است camera library/polyfill داشته باشد و desktop از HID scanner استفاده کند. acceptance contract مشترک است؛ capability evidence مشترک فرض نمی‌شود.

Failure modeهای رایج

• Decoder-success promotion: هر decode موفق مستقیماً workflow را جلو می‌برد.
• Global capability assumption: چون روی یک Android کار کرد، روی همه browserها/deviceها ready فرض می‌شود.
• Symbology ambiguity: format decoded خارج از allow-list هم پذیرفته می‌شود.
• Raw/normalized collapse: فقط مقدار نهایی نگه داشته می‌شود و transformation قابل audit نیست.
• Cross-order acceptance: کد معتبر برای order دیگر چون «وجود دارد» قبول می‌شود.
• Frame duplicate side effect: چند frame یک code را چند transition حساب می‌کنند.
• Manual-entry bypass: fallback از parse/context/dedupe عبور نمی‌کند.
• Green-check UX: UI دلیل failure را پنهان می‌کند و operator repair اشتباه انجام می‌دهد.
• Transfer copy: capability baseline Android بدون recomputation برای iOS/USB reuse می‌شود.

Alternatives و trade-offها

Native/accelerated BarcodeDetector: ساده و سریع در platformهای پشتیبان، اما coverage یکسان نیست و experimental/limited availability باقی مانده است.

JavaScript/WASM decoder: portability بالقوه بیشتر، ولی bundle size، CPU، camera pipeline و quality tuning را خودت مدیریت می‌کنی. وجود library هم context correctness را حل نمی‌کند.

USB/HID scanner: برای desktop workflow بسیار عملی و کم‌اصطکاک است، ولی input focus، accidental keystroke و device configuration باید کنترل شود.

Manual entry: universal fallback است، اما typo risk دارد. بنابراین structure check و operator provenance مهم‌تر می‌شوند.

Single universal scan screen: UX ساده‌تر به‌نظر می‌رسد، ولی اگر capability differences را hide کند false confidence می‌سازد. adapter-based capture + shared verification contract کمی پیچیده‌تر اما قابل‌انتقال‌تر است.

Experienced bridge: یازده سؤال review

1. Capture adapter فعلی چیست و capability آن از کجا evidence شده؟
2. secure context برای camera path واقعاً برقرار است؟
3. expected symbology set کجا version شده؟
4. raw value و normalized ID هر دو قابل بازسازی‌اند؟
5. parser ambiguity چگونه fail می‌شود؟
6. structure/check-digit rule متعلق به کدام identifier type است؟
7. expected context قبل از scan مشخص است یا بعداً حدس زده می‌شود؟
8. duplicate key مرز session/workflow را درست می‌گیرد؟
9. fallback path همان verification gateها را طی می‌کند؟
10. UI بین capability failure و context mismatch فرق می‌گذارد؟
11. در mixed fleet، کدام evidence reuse می‌شود و کدام باید recompute شود؟

تمرین هدایت‌شده و مستقل

Lab آفلاین هشت fixture دارد. اول baseline را اجرا کن. بعد unsupported format، wrong-order code، duplicate، missing evidence، manual fallback و دو transfer case را بررسی کن. هدف حفظ label نیست؛ باید بتوانی بگویی کدام evidence dimension باعث تغییر تصمیم شده است.

سپس یک fixture جدید بساز که raw value معتبر است ولی expected_context_id عوض شده. نتیجه نباید accepted باقی بماند. بعد capture adapter را از camera به USB تغییر بده و acceptance rules را بدون تغییر نگه دار؛ فقط capability/fallback evidence باید دوباره ساخته شود.

Verification evidence

خروجی قابل‌قبول باید این‌ها را نشان دهد:

• هر ۲۲ dimension یا دلیل صریح nullable بودن آن؛
• capability و supported formats برای adapter جاری؛
• raw و normalized value جدا؛
• parse/structure gate قبل از business context؛
• expected-context binding قبل از confirmation؛
• duplicate suppression بدون side effect دوباره؛
• manual fallback با provenance و همان verification gates؛
• ACCEPTED_VERIFIED فقط با evidence کامل؛
• transfer به mixed fleet با adapter recomputation، نه copy baseline.

Lab package deterministic و offline است و هیچ camera واقعی، API key، customer data یا network access نمی‌خواهد.

Assessment و transfer

برای پایان درس باید بتوانی:

1. مرز COM-033 و یک non-goal مجاور را توضیح دهی؛
2. Scan Capability and Verification Contract v1 را از baseline fixture بسازی؛
3. unsupported capability، wrong-context و duplicate را با repair درست تشخیص دهی؛
4. workflow را به iOS/Safari و desktop USB منتقل کنی و فقط capture adapter evidence را recompute کنی؛
5. نشان دهی چرا decoder success هیچ‌وقت به‌تنهایی proof of business identity نیست.

اگر تصمیم baseline را به device جدید کپی کردی بدون اینکه capability/fallback را دوباره evidence کنی، transfer fail است.

منابع و freshness

• WICG Accelerated Shape Detection draft — BarcodeDetector، secure context، getSupportedFormats() و platform-dependent support؛ current draft checked 2026-09-14، review due 2026-10-18.
• MDN BarcodeDetector — Limited availability / Experimental و browser-compatibility warning؛ rechecked 2026-09-14، review due 2026-10-18.
• GS1 2D barcode guidance — تفاوت QR/Data Matrix/GS1 DataMatrix و وضعیت متفاوت mobile/POS scanning؛ rechecked 2026-09-14، practice review due 2026-12-31.

منابع بیرونی فقط FACT درباره‌ی platform/carrier capability می‌دهند. context binding، duplicate suppression، fallback provenance و confirmation policy طراحی MAKNOW هستند.