Native App Decision Gate

اولین سؤال: دقیقاً کدام journey با PWA حل نمی‌شود؟

تیم محصول می‌گوید: «دیگر وقتش رسیده اپ native داشته باشیم.» تیم فنی جواب می‌دهد: «PWA ارزان‌تر است، پس native لازم نیست.» هر دو جمله می‌توانند اشتباه باشند، چون از راه‌حل شروع می‌کنند نه از نیاز اثبات‌شده.

در این درس تصمیم را برعکس می‌سازیم. ابتدا یک required_journey مشخص می‌کنیم؛ سپس evidence فعلی COM-036 را برای install/offline/push/camera و هر capability مرتبط می‌آوریم؛ بعد residual gap، کیفیت fallback، native capability delta و هزینه‌ی lifecycle را جداگانه ثبت می‌کنیم. خروجی نه «طرفداری از native» است نه «طرفداری از web»؛ خروجی یک PWA-vs-Native Decision Gate & Evidence Record v1 است که باید توسط انسان قابل بازتولید باشد.

مرز این درس

COM-037 مالک تصمیم آیا، چرا و با چه محدوده‌ای native/hybrid لازم است است. این درس مالک پیاده‌سازی Service Worker، Push، Camera یا installability نیست؛ آن evidence از COM-036 می‌آید. همچنین exception مدیریتی را طراحی نمی‌کند؛ آن متعلق به AGN-001 است.

سه قاعده‌ی مرزی:

1. وجود API یا manifest مساوی capability parity نیست.
2. وجود App Store مساوی نیاز محصول به native نیست.
3. تصمیم قبلی authority دائمی نیست؛ با تغییر browser/OS، هزینه یا journey باید Gate دوباره اجرا شود.

مدل ذهنی: Requirement → Evidence → Gap → Option → Burden → Decision

فلو اصلی:

required journeys → current PWA evidence → residual gap/fallback → compare PWA repair | narrow hybrid | full native → distribution/privacy/security/lifecycle gate → REJECT | HOLD | HYBRID_APPROVED | NATIVE_APPROVED → review/retirement trigger

اگر evidence تعیین‌کننده UNKNOWN، DISPUTED یا STALE باشد، تصمیم باید در HOLD بماند. NATIVE_APPROVED یک احساس یا preference نیست؛ یک state با پیش‌شرط‌های قابل ممیزی است.

چهار نوع ادعا را قاطی نکن

FACT — Web platform. Web App Manifest، Service Workers، Push API و Media Capture مکانیزم‌های جدا هستند و lifecycle/permission/implementation constraintهای متفاوت دارند. بنابراین «PWA داریم» یک evidence کافی برای همه‌ی journeyها نیست.

FACT — Distribution. Guideline 4.2 اپل برای App Store حداقل functionality و utility می‌خواهد و صرفاً repackaged website را کافی نمی‌داند. این constraint کانال توزیع است، نه حکم اینکه «پس native بساز».

INFERENCE. اگر یک requirement مهم با web/PWA و fallback قابل‌قبول حل نمی‌شود و یک native delta مشخص آن را می‌بندد، native/hybrid قابل دفاع‌تر می‌شود. اگر gap باقی نمانده، codebase و release/support lifecycle اضافه ممکن است فقط هزینه باشد.

DESIGN — MAKNOW. stateها، fieldها، thresholdهای local و review triggerهای این درس طراحی MAKNOW هستند؛ از W3C یا Apple استخراج نشده‌اند.

قرارداد ۲۶بعدی Decision Gate

رکورد کاری ۲۶ field دارد:

decision_id, required_journey, capability_requirement, pwa_evidence_ref, web_support_state, fallback_quality, native_capability_delta, background_requirement, offline_requirement, hardware_integration_requirement, performance_target, distribution_channel, store_policy_dependency, release_review_dependency, privacy_permission_surface, security_boundary, team_skill_constraint, build_cost_class, ongoing_maintenance_class, release_cadence, observability_requirement, support_burden, decision_state, exception_authority, review_trigger, evidence_ref.

Gate 1 — Required journey را قبل از platform بنویس

مثلاً «کاربر انباردار باید در محیط با اتصال ناپایدار، اسکن سخت‌افزاری را ادامه دهد و پس از reconnect sync قابل ردیابی داشته باشد.» این بسیار دقیق‌تر از «اپ موبایل می‌خواهیم» است.

Gate 2 — PWA evidence را capability-by-capability ثبت کن

pwa_evidence_ref باید بگوید روی target browser/OS چه چیزی واقعاً آزمایش/اثبات شده است. API presence، browser marketing page یا تجربه‌ی desktop به‌تنهایی evidence کافی برای target mobile mix نیست.

Gate 3 — Support state و fallback را جدا نگه دار

web_support_state می‌تواند SUPPORTED, PARTIAL, UNSUPPORTED, UNKNOWN, DISPUTED, STALE باشد. حتی اگر state PARTIAL است، fallback_quality ممکن است ACCEPTABLE باشد و native را غیرضروری کند؛ یا UNACCEPTABLE باشد و gap را material کند.

Gate 4 — Native capability delta را دقیق بنویس

بگو native دقیقاً چه چیز اضافه می‌کند: persistent background execution؟ hardware integration؟ latency budget؟ deeper OS integration؟ اگر delta مبهم است، approval مبهم است.

Gate 5 — Background/offline/hardware/performance را جدا کن

این چهار نیاز را در یک «mobile capability» ادغام نکن. ممکن است offline با PWA خوب باشد اما یک hardware path مشکل داشته باشد. آن‌وقت hybrid محدود شاید از full native بهتر باشد.

Gate 6 — Distribution و review dependency مستقل‌اند

اگر مسیر توزیع App Store است، store policy و release review یک dependency هستند. اگر enterprise/direct distribution است، constraint متفاوت است. هیچ‌کدام به‌تنهایی product fit را اثبات نمی‌کنند.

Gate 7 — Privacy و security surface را مقایسه کن

Permission surface، local storage/secrets، device identifiers، deep links، background services و attack surface را برای گزینه‌ی جدید ثبت کن. capability بیشتر معمولاً surface بیشتری هم می‌آورد.

Gate 8 — Build cost را از recurring burden جدا کن

یک بار ساختن native تنها هزینه نیست. ongoing_maintenance_class, release_cadence, observability_requirement, support_burden باید دیده شوند. هزینه‌ی دو codebase، store releases و device/OS matrix می‌تواند تصمیم را عوض کند.

Gate 9 — کوچک‌ترین option که gap را می‌بندد انتخاب کن

سه گزینه‌ی baseline: PWA repair/fallback improvement، narrow hybrid/native companion، full native. اگر companion محدود یک hardware/background gap را می‌بندد، full native برای همه‌ی journeyها نیاز به دلیل اضافه دارد.

Gate 10 — review trigger و retirement path

هر approval باید trigger بازبینی داشته باشد: browser support change، OS policy change، support burden threshold، usage below target، permission failure rate، store-policy change یا native delta دیگر material نباشد.

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

1. Gap محدود → HYBRID_APPROVED

Checkout، catalog و account management در PWA خوب کار می‌کنند. یک journey انبار نیاز به background scan + hardware integration دارد و fallback دستی باعث خطای عملیاتی می‌شود. native companion فقط همان journey را می‌بندد؛ build/maintenance متوسط و success metric روشن است. نتیجه: HYBRID_APPROVED، نه full native.

2. Gap حذف شده → REJECT

نسخه‌ی جدید target browser محدودیت قبلی را رفع می‌کند و fallback نیز acceptable شده است. اگر فقط به approval قبلی نگاه کنیم native ادامه پیدا می‌کند؛ اما Gate جدید باید residual gap را صفر ببیند و REJECT/retire path را بررسی کند.

3. Evidence ناقص → HOLD

تیم می‌گوید «push روی دستگاه‌های مشتری کار نمی‌کند»، ولی target OS mix و permission state evidence ندارد. تصمیم صحیح HOLD است، نه حدس NATIVE_APPROVED.

4. Full native فقط با gapهای متعدد و پایدار

چند journey حیاتی به background execution، tight latency و hardware integration نیاز دارند؛ fallbackها unacceptable هستند، native delta مستند است، privacy/security review انجام شده و maintenance/support در tolerance است. NATIVE_APPROVED قابل دفاع است—تا زمانی که review trigger نقض نشود.

Failure modeهای متداول

• Preference-first: «من native را دوست دارم» یا «web همیشه بهتر است» قبل از evidence.
• API-presence parity: وجود یک API به‌عنوان proof کامل target support.
• Single-gap overreach: یک gap محدود باعث full native شدن کل محصول می‌شود.
• Store mystique: حضور در App Store به‌عنوان justification خودکار.
• Fallback blindness: PARTIAL support بدون سنجش اینکه fallback واقعاً قابل قبول است یا نه.
• One-time cost bias: فقط build cost دیده می‌شود و release/support/observability فراموش می‌شود.
• Privacy/security omission: capability اضافه می‌شود ولی permission/security surface ثبت نمی‌شود.
• Weighted-score theater: چند عدد arbitrary جمع می‌شوند و hard constraint پنهان می‌شود.
• Permanent approval: تصمیم سال قبل بدون revalidation ادامه می‌یابد.
• Forced success: evidence ناقص به decision مثبت تبدیل می‌شود.

Alternatives و trade-offها

PWA repair کمترین fragmentation را دارد و deployment سریع است، اما اگر target OS/browser یک gap بنیادی داشته باشد ممکن است requirement را نبندد.

Narrow hybrid/native companion برای یک capability محدود می‌تواند بهترین نسبت outcome به burden باشد. در عوض integration boundary، handoff بین web/native و support complexity اضافه می‌شود.

Full native کنترل بیشتری روی OS/device integration می‌دهد اما codebase، release process، store review، testing matrix و support burden را بزرگ می‌کند. این گزینه وقتی قوی است که gapهای متعدد و پایدار به آن نیاز داشته باشند—not because “serious apps are native”.

نکته‌ی مهم: trade-offها را به یک score مبهم تبدیل نکن. بعضی evidenceها blocking هستند، بعضی decisive و بعضی فقط advisory.

Experienced bridge: در review چه می‌پرسی؟

1. کدام required journey الان fail/degrade می‌شود؟
2. evidence دقیق target browser/OS چیست؟
3. آیا fallback acceptable است؟ با چه metric؟
4. native دقیقاً چه delta قابل‌اندازه‌گیری می‌دهد؟
5. آیا یک companion محدود کافی است؟
6. distribution/review dependency چیست؟
7. privacy/security surface چه تغییری می‌کند؟
8. build، maintenance، release و support burden چیست؟
9. success metric چیست؟
10. چه triggerی باعث narrow/retire/review می‌شود؟

اگر سؤال 1 یا 4 جواب مشخص ندارد، تیم هنوز architecture decision ندارد؛ فقط preference دارد.

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

Lab آفلاین را اجرا کن:

python -B lab/COM-037-LAB1/learner/run_checks.py

ابتدا baseline را بررسی کن. سپس mutationها را اجرا کن: gap اصلی را حذف کن؛ maintenance/support burden را دو برابر کن؛ یک OS-level requirement اضافه کن؛ store review dependency را material کن؛ و evidence تعیین‌کننده را UNKNOWN کن.

در مرحله‌ی transfer، فرض کن browser release جدید gap قبلی را بسته ولی native client گران‌تر شده است. decision قبلی را کپی نکن؛ از required_journey و evidence فعلی دوباره شروع کن.

Verification evidence

قبولی نیاز دارد که evaluator حداقل این خطاها را بگیرد:

• NATIVE_APPROVED یا HYBRID_APPROVED بدون residual gap واقعی؛
• approval وقتی decisive evidence UNKNOWN/DISPUTED/STALE است؛
• approval بدون native capability delta روشن؛
• full native وقتی narrow companion gap را با burden کمتر می‌بندد؛
• App Store label به‌عنوان justification بدون utility/distribution evidence؛
• maintenance/support burden جهش کرده ولی decision recompute نشده؛
• transfer که approval قبلی را oracle فرض می‌کند.

Oracle فقط fixture و ruleهای visible است؛ hidden AI reasoning، live store یا production telemetry لازم نیست.

Assessment و transfer

برای summative باید چهار کار انجام شود: مرز COM-037 را توضیح بده؛ artifact baseline را کامل کن؛ mutation حذف capability gap را diagnose کن؛ و در scenario انتقالی تصمیم را از evidence جدید بازسازی کن.

پاسخ قوی صرفاً state نهایی را نمی‌گوید. نشان می‌دهد کدام field تصمیم را تعیین کرد، چه evidenceی blocking بود، چه چیزی advisory بود، و review trigger بعدی چیست.

منابع و تازگی

• W3C-APPMANIFEST — Web Application Manifest؛ rechecked 2026-09-14.
• W3C-SERVICE-WORKERS — Service Workers؛ rechecked 2026-09-14.
• W3C-PUSH — Push API؛ rechecked 2026-09-14.
• W3C-MEDIA-CAPTURE — Media Capture and Streams؛ rechecked 2026-09-14.
• APPLE-APP-REVIEW — App Review Guidelines، خصوصاً 4.2؛ rechecked 2026-09-14.
• LOCAL_DESIGN_AUTHORITY — Frozen COM-037 Bible برای fieldها و stateها.

Apple policy باید حداکثر تا 2026-11-02 و W3C/platform assumptions تا 2026-12-31 دوباره بررسی شوند یا زودتر اگر semantics materially تغییر کرد. این lesson هیچ vendor documentی را به MAKNOW decision authority تبدیل نمی‌کند.