PWA: Install, Offline, Push, Camera Limits

اولین سؤال: «PWA-ready» دقیقاً برای کدام capability؟

یک manifest داریم، service worker هم register شده، پس تیم می‌گوید «PWA آماده است». بعد روی دستگاه واقعی push اجازه نمی‌گیرد، cache بعد از تغییر schema داده‌ی قدیمی نشان می‌دهد، یا camera API وجود دارد ولی permission/device state اجازه‌ی capture نمی‌دهد. مشکل از اینجا شروع می‌شود که چند capability مستقل را به یک برچسب تبدیل کرده‌ایم.

در این درس یک PWA Capability & Offline Readiness Matrix v1 می‌سازیم. install، offline، push و camera چهار قرارداد جدا هستند. برای هرکدام platform، runtime detection، permission/lifecycle، failure state، fallback و evidence را ثبت می‌کنیم. فقط وقتی evidence کافی است READY می‌دهیم؛ در غیر این صورت PARTIAL، FALLBACK، UNSUPPORTED یا HOLD را حفظ می‌کنیم.

مرز این درس

COM-036 مالک اثبات capability و readiness PWA است. این درس تصمیم «آیا native بسازیم؟» را نمی‌گیرد؛ آن متعلق به COM-037 است. همچنین notification policy و minimal PII متعلق به COM-035 است.

سه مرز سخت:

1. وجود API مساوی usable capability نیست.
2. وجود manifest یا service worker مساوی readiness کل PWA نیست.
3. نتیجه‌ی یک browser/OS را نمی‌توان به platform دوم کپی کرد.

مدل ذهنی: Need → Probe → State → Contract → Fallback → Decision

فلو اصلی:

workflow need → per-capability probe → permission/lifecycle state → offline/cache contract → positive + negative fixture → READY | PARTIAL | FALLBACK | UNSUPPORTED | HOLD

هر capability یک سؤال مستقل دارد: آیا surface نصب/launch موردنیاز وجود دارد؟ آیا offline data واقعاً مجاز و نسخه‌دار است؟ آیا push permission و subscription فعال‌اند؟ آیا camera permission و device state واقعاً capture را ممکن می‌کنند؟

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

FACT — Manifest. W3C manifest یک سند JSON برای metadata اپ وب است و خود spec هم می‌گوید user agent ممکن است برای استفاده از capabilityها شرایط خودش را داشته باشد. پس manifest_present=true به‌تنهایی parity ایجاد نمی‌کند.

FACT — Service Worker. Service Worker می‌تواند event بگیرد، fetch را مدیریت کند و به ساخت تجربه‌ی offline کمک کند. اما خودش تضمین نمی‌کند داده‌ی business شما با schema جدید، policy retention یا conflict rule درست بماند.

FACT — Push. Push permission و subscription state مستقل‌اند و subscription می‌تواند refresh/deactivate شود. PushManager موجود بودن به معنی active subscription نیست.

FACT — Camera. getUserMedia() تحت permission و constraint اجرا می‌شود. API presence به‌تنهایی selected device، permission یا capture موفق را ثابت نمی‌کند.

INFERENCE. چون این capabilityها مکانیزم و state متفاوت دارند، readiness بهتر است capability-by-capability سنجیده شود.

DESIGN — MAKNOW. stateها، fieldهای matrix، ruleهای fallback و fail-closed این درس طراحی MAKNOW هستند.

قرارداد ۲۴بعدی Readiness Matrix

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

surface_id, capability_id, platform_family, user_agent_context, secure_context, manifest_present, manifest_scope, install_surface, service_worker_registration, service_worker_state, offline_data_class, cache_strategy, cache_version, network_state, push_api_available, push_permission_state, push_subscription_state, camera_api_available, camera_permission_state, camera_device_state, fallback_path, unsupported_reason, test_fixture, evidence_ref.

Gate 1 — Surface و platform را قبل از capability بنویس

mobile-web، home-screen-web-app و desktop-browser یک context نیستند. platform_family و user_agent_context باید در evidence دیده شوند.

Gate 2 — Secure context را explicit کن

capabilityهای قدرتمند را در محیط ناامن فرض نکن. اگر prerequisite امنیتی برقرار نیست، نتیجه را با حدس READY نکن.

Gate 3 — Install را از manifest جدا کن

manifest_present، manifest_scope و install_surface سه چیز متفاوت‌اند. حتی رفتار install/home-screen در user agentها می‌تواند تغییر کند. evidence باید target platform را توصیف کند، نه یک تعریف بازاری از PWA.

Gate 4 — Offline فقط «cache داریم» نیست

سه سؤال: چه offline_data_class مجاز است؟ چه cache_strategy داریم؟ cache_version با schema/data contract فعلی هم‌راستاست؟ اگر بعد از schema migration نسخه‌ی cache قدیمی است، offline ممکن است خطرناک‌تر از online failure باشد.

Gate 5 — Service Worker lifecycle را ببین

REGISTERED, INSTALLING, ACTIVATING, ACTIVE, REDUNDANT وضعیت یکسان نیستند. اگر workflow به offline وابسته است، state انتقالی را success کامل اعلام نکن.

Gate 6 — Push = API + Permission + Subscription

سه field را جدا کن. push_api_available=true با push_permission_state=DENIED یا push_subscription_state=NONE هنوز push آماده نیست.

Gate 7 — Camera = API + Permission + Device

camera_api_available=true کافی نیست. permission ممکن است denied باشد یا device مناسب در دسترس نباشد. fallback مثل upload فایل یا manual entry باید از قبل تعریف شود.

Gate 8 — Fallback را business-level بنویس

fallback فقط «یک پیام خطا نشان بده» نیست. باید workflow را حفظ کند: مثلاً push→in-app inbox/email؛ camera→manual code entry؛ offline→read-only snapshot با badge واضح و sync بعد از reconnect.

Gate 9 — Unsupported reason و evidence_ref اجباری‌اند

اگر capability fail می‌شود، علت را typed ثبت کن: PERMISSION_DENIED, NO_DEVICE, NO_INSTALL_SURFACE, STALE_CACHE, UNSUPPORTED_API. بدون provenance، debugging تبدیل به حدس می‌شود.

Gate 10 — READY کوچک‌ترین state است، نه پیش‌فرض

اگر evidence تعیین‌کننده UNKNOWN, DISPUTED یا STALE است، HOLD. اگر support transition است، PARTIAL. اگر مسیر اصلی fail ولی fallback قابل‌قبول است، FALLBACK. اگر capability لازم است و هیچ مسیر قابل‌قبول نداریم، UNSUPPORTED.

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

1. همه‌ی چهار capability با evidence → READY

سطح هدف secure است؛ install surface روی target platform دیده شده؛ service worker ACTIVE است؛ cache version با schema فعلی match است؛ push permission GRANTED و subscription ACTIVE است؛ camera permission و device هر دو حاضرند. نتیجه READY.

2. Push denied، ولی fallback عملیاتی → FALLBACK

Order status باید به کاربر برسد. Push API وجود دارد اما user permission را رد کرده است. چون in-app inbox + email تاییدشده workflow را حفظ می‌کند، کل surface شکست نمی‌خورد؛ state این capability FALLBACK است، نه READY و نه دروغ «push works».

3. Cache قدیمی بعد از schema change → HOLD

Service worker active است اما cache_version=v7 در حالی که data contract v8 است. چون correctness داده‌ی offline اثبات نشده، HOLD تا migration/invalidating policy روشن شود.

4. Camera API حاضر، device نیست → UNSUPPORTED

permission قبلاً granted بوده ولی در kiosk هدف camera device قابل استفاده وجود ندارد و fallback مجاز هم نداریم. capability UNSUPPORTED است.

Failure modeهای متداول

• Manifest theater: فایل manifest را completion badge می‌دانیم.
• Service-worker magic: فرض می‌کنیم register شدن SW همه‌ی state را offline-safe می‌کند.
• Cache forever: schema عوض شده ولی cache version و invalidation policy تغییر نکرده‌اند.
• Push optimism: API support را با permission/subscription فعال یکی می‌کنیم.
• Camera optimism: getUserMedia را با permission/device/capture موفق یکی می‌کنیم.
• Browser-name detection: به‌جای feature/runtime probe فقط اسم browser را می‌خوانیم.
• Silent fallback: fallback وجود دارد ولی کاربر نمی‌فهمد داده stale یا notification degraded است.
• Copied verdict: نتیجه‌ی platform A به platform B منتقل می‌شود.
• Forced green: UNKNOWN/STALE را برای release pressure به READY تبدیل می‌کنیم.

Alternatives و trade-offها

Network-first برای داده‌ی حساس به تازگی مناسب‌تر است اما offline resilience کمتر می‌شود.

Cache-first برای assetهای immutable عالی است اما برای business data بدون version/expiry می‌تواند stale-data risk بسازد.

Stale-while-revalidate latency را کم می‌کند ولی باید UI freshness و data class اجازه‌ی stale read را پشتیبانی کنند.

Push fallback مثل inbox/email continuity می‌دهد، اما latency و attention semantics متفاوت است؛ آن را «همان push» اعلام نکن.

Camera fallback مثل upload/manual entry availability را بالا می‌برد ولی UX و error rate متفاوت است.

اصل تصمیم: strategy را از data class و business requirement انتخاب کن، نه از snippet محبوب.

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

1. target surface و platform دقیقاً چیست؟
2. کدام capability واقعاً required است؟
3. probe در runtime چه چیزی نشان می‌دهد؟
4. permission و lifecycle state چیست؟
5. offline data class چیست و stale read مجاز است؟
6. cache version چگونه با schema version قفل می‌شود؟
7. fallback دقیقاً کدام business outcome را حفظ می‌کند؟
8. کاربر degraded mode را می‌بیند یا نه؟
9. negative fixture چه failureی را ثابت می‌کند؟
10. چه تغییر platform/browser باعث recheck می‌شود؟

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

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

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

baseline را ببین، سپس mutationها را بررسی کن: push permission را deny کن؛ cache version را عقب بینداز؛ service worker را در ACTIVATING بگذار؛ camera device را حذف کن؛ secure context را false کن؛ و در transfer یک platform جدید بده که install behavior و push state متفاوت دارد.

قانون transfer: verdict قبلی oracle نیست. matrix جدید باید از evidence همان platform ساخته شود.

Verification evidence

Evaluator باید حداقل این خطاها را بگیرد:

• READY با evidence UNKNOWN/STALE/DISPUTED؛
• offline READY با cache version ناسازگار؛
• push READY بدون permission یا subscription؛
• camera READY بدون permission یا device؛
• capability required و unsupported بدون fallback ولی verdict مثبت؛
• install verdict فقط از manifest_present بدون install-surface evidence؛
• transfer که baseline verdict را کپی می‌کند.

Oracle فقط fixture و ruleهای deterministic است؛ نه browser زنده، نه production push، نه hidden model reasoning.

Assessment و transfer

تکلیف نهایی چهار حرکت دارد: مرز COM-036 را توضیح بده؛ matrix baseline را کامل کن؛ mutation stale-cache یا denied-permission را تشخیص بده؛ سپس همان workflow را روی browser/OS دوم از صفر recompute کن.

پاسخ قوی فقط state نهایی را نمی‌گوید. نشان می‌دهد کدام field تعیین‌کننده بود، کدام evidence missing/stale بود، fallback چگونه business outcome را حفظ کرد، و چه چیزی recheck بعدی را trigger می‌کند.

منابع و freshness

• W3C-APPMANIFEST — Web Application Manifest؛ بازبینی 2026-09-14.
• W3C-SERVICE-WORKERS — Service Workers؛ بازبینی 2026-09-14.
• W3C-PUSH — Push API؛ بازبینی 2026-09-14.
• W3C-MEDIA-CAPTURE — Media Capture and Streams؛ بازبینی 2026-09-14.
• WEBKIT-SAFARI26-WEBAPPS — رفتار Home Screen web app در Safari/iOS 26؛ منبع vendor و فقط برای مثال تفاوت implementation.
• LOCAL_DESIGN_AUTHORITY — Bible فریز‌شده‌ی COM-036 برای stateها و gateها.

این lesson عمداً از support table ثابت به‌عنوان truth نهایی استفاده نمی‌کند. implementation behavior ممکن است تغییر کند؛ claimهای platform-sensitive باید تا 2026-12-31 یا زودتر پس از تغییر مهم browser/OS دوباره بررسی شوند.