ساخت و انتشار یک App#

App محصول کاربرمحوری با تألیف مستقل و تحویل باندلی است که AppHost دسکتاپ از Home یا هنگام فعال بودن Environment باز می‌کند. App از session مخصوص خودش استفاده می‌کند و نباید AlAmrWidget را mount کند، توکن Runtime محیط را دریافت کند یا صحنهٔ میزبان را بازرسی کند.

نتیجه#

در پایان خواهید داشت:

• یک revision از App که با یک فهرست تغییرناپذیر باندل منتشر شده است؛
• revision دقیقِ منتشرشده که توسط یک مدیر برای استفادهٔ Runtime فعال شده است؛
• archive، سند entry و تک‌تک فایل‌های فهرست‌شدهٔ تأییدشده؛
• اجرای اثبات‌شدهٔ همان revision دقیق توسط یک principal مصرف‌کنندهٔ مستقل.

انتشار به‌تنهایی App را در دسترس نمی‌کند. یک مدیر جداگانه revision دقیق را فعال می‌کند؛ دسترس‌پذیری App را ببینید.

انواع پشتیبانی‌شده#

نوع	اعلان	یادداشت
Compact	"modes": ["compact"]	سطح محصول اجباری به عرض موبایل؛ هر App باید آن را پشتیبانی کند
Compact + Workspace	"modes": ["compact", "workspace"]	افزودن سطح بزرگ Widget برای دسکتاپ با حاشیهٔ صحنه، نه تمام‌صفحه

بک‌اند App اختیاری است؛ @al-amr/backend کتابخانه‌ای برای اعتبارسنجی و کمک به کد سمت سرور است، نه سرویسی که هر App باید اجرا کند. اعلان‌ها اختیاری‌اند و بدون بک‌اند، فقط از App باز کار می‌کنند؛ تحویل پس‌زمینه‌ای واگذارشده اعلان جداگانه‌ای است که بازبینی می‌شود.

پیش‌نیازهای ساخت و انتشار#

همهٔ بلوک‌های قابل کپی، فرمان کامل و نسخه‌دار npx @al-amr/cli@0.1.0-alpha.7 را نشان می‌دهند. این نسخه برای مسیر انسانی/CLI آماده است؛ فعال‌شدن Context Pack رسمی Agent به ترفیع Release Set وابسته است.

• نسخه و integrity دقیق CLI عمومی که صفحهٔ شروع اعلام می‌کند؛ فایل package.json تولیدشده package manager انتخاب‌شده را ثبت می‌کند؛ فرمان‌های بعدی پروژه را با همان manager دقیق اجرا کنید؛
• حساب توسعه‌دهندهٔ الامر و دسترسی به Registry مقصد؛
• کلاینت دسکتاپ الامر برای پیش‌نمایش محلی و اثبات launch مصرف‌کننده. frontend اپ به دامنه، گواهی TLS، callback URL یا حساب میزبانی نیاز ندارد.

گام‌های دقیق#

۱. اسکلت را بسازید و اجرا کنید#

npx @al-amr/cli@0.1.0-alpha.7 create app my-app --yes --json
cd my-app
pnpm install
pnpm build
npx @al-amr/cli@0.1.0-alpha.7 dev --json
# Run the `open` command returned in nextActions.

اسکلت شامل al-amr.app.json، ورودی باندل، تابع createEmbeddedAppClient و یک چیدمان اجباری Compact است و به‌طور پیش‌فرض نه بک‌اند دارد و نه قابلیت درخواستی. در هر تکرار build کنید، alamr dev --json را اجرا و فرمان open در nextActions را هم اجرا کنید؛ لینک توسعه پیش‌نمایش loose قبلی را می‌بندد و بایت‌های تازه را با اختیار صریح پیش‌نمایش محلی باز می‌کند.

۲. به AppHost دسکتاپ متصل شوید#

پروژهٔ آغازین به‌طور پیش‌فرض https://registry.al-amr.com را دارد و Registry انتخاب‌شده هنگام ساخت را در .env.example می‌نویسد. issuer متفاوت را از سمت استقرار App پیکربندی کنید، نه از صفحهٔ والد:

import { createEmbeddedAppClient } from "@al-amr/sdk";

const client = createEmbeddedAppClient({
  appId: manifest.appId,
  registryBaseUrl: import.meta.env.VITE_REGISTRY_URL,
});

const session = await client.connect();

SDK مقدار verifier و توکن App را در حافظه نگه می‌دارد. برای انتخاب چیدمان Compact یا Workspace از session.displayMode یا client.snapshot.hostSession.displayMode استفاده کنید. پیش از استفاده از یک قابلیت اختیاری، مقدار client.snapshot.hostSession.grantedCapabilities را بررسی کنید.

۳. نخست Compact طراحی کنید، سپس در صورت نیاز Workspace#

حالت Compact اجباری است و باید بدون اسکرول افقی و بدون فرض hover قابل استفاده بماند. Workspace را فقط وقتی اضافه کنید که محصول از چیدمان پهن دسکتاپ بهره می‌برد:

{
  "display": {
    "modes": ["compact", "workspace"],
    "preferredMode": "workspace",
    "background": "none"
  }
}

تعویض حالت دیگر App را بارگیری مجدد نمی‌کند: با client.subscribePresentation(...) مشترک شوید و دوباره ترکیب کنید. state پایدار را به هر حال در بک‌اند خود نگه دارید — تغییر نسخه یا بازیابی از خطا همچنان شما را دوباره راه‌اندازی می‌کند — و برای پیش‌نویس‌های ذخیره‌نشده از handler خروجِ محدود استفاده کنید؛ مهلت میزبان یک ثانیه است و UI تأیید متعلق به میزبان است:

client.setBeforeExitHandler(async () => {
  if (!draft.dirty) return { disposition: "allow" };
  return (await saveDraft())
    ? { disposition: "allow" }
    : { disposition: "confirm", message: "Discard the unsaved draft?" };
});

۴. فقط قابلیت‌های لازم را درخواست کنید#

درخواست‌های قابلیت، اعلان‌های دقیقِ محصولی هستند که بازبینی می‌شوند:

{
  "capabilities": {
    "required": [
      {
        "id": "platform.environment.identity.read@1",
        "versionRange": "^1.0.0"
      },
      {
        "id": "host.spatial.context.read@1",
        "versionRange": "^1.0.0"
      }
    ],
    "optional": [
      {
        "id": "host.spatial.locations.read@1",
        "versionRange": "^1.0.0"
      }
    ]
  }
}

رد یک قابلیت اجباری مانع اجرا می‌شود. رد یک قابلیت اختیاری باید تجربهٔ محدودِ مفیدی باقی بگذارد. وابستگی‌ها — مانند هویت Environment برای context فضایی — باید در همان سطح یا سطح قوی‌تر اعلان شوند. Registry پیش از اجرا disclosureها را نشان می‌دهد و رضایت را ثبت می‌کند. برای متدهای فضایی و الزام‌های آداپتر Environment، خدمات میزبان App را دنبال کنید. هرگز Zone یا مکان را از URL استنباط نکنید و مختصات میزبان را به‌عنوان هویت قابل‌انتقال ذخیره نکنید.

۵. در صورت نیاز محصول، اعلان اضافه کنید#

هر نوع رویداد را اعلان کنید:

{
  "notifications": {
    "eventTypes": [
      {
        "type": "task.completed",
        "label": "Task completed",
        "policy": {
          "family": "generic",
          "subject": {
            "mode": "per_occurrence",
            "revision": "event_identity"
          },
          "effects": ["raise"],
          "preferenceKey": "task.completed",
          "pulse": "none",
          "presentation": { "kind": "source" }
        }
      }
    ],
    "backgroundDelivery": "none"
  }
}

قابلیت platform.notifications.publish.self@1 را هم درخواست کنید و سپس واقعیت تغییرناپذیر منبع را از App باز signal کنید:

await client.signalNotificationOccurrence({
  eventId: "task-job_42-completed",
  eventType: "task.completed",
  occurredAt: completedAt,
  effect: "raise",
  content: {
    kind: "source",
    title: "Export complete",
    action: { kind: "open_app" },
  },
});

در retry، eventId و occurredAt را تغییر ندهید. این مسیر بدون بک‌اند App کار می‌کند، اما فقط تا وقتی session مربوط به App فعال است. برای تحویل آفلاین یا زمان‌بندی‌شده، تحویل پس‌زمینه‌ای واگذارشده و هر دو قابلیت اعلان را درخواست کنید، delegation کاربر را از App بسازید و یک outbox پایدار commit کنید که workload.signal(...) را از راه @al-amr/backend retry کند. اعلان‌های پلتفرم را دنبال کنید؛ هرگز شناسهٔ خام کاربر را به بک‌اند خود نفرستید. publishNotification(...) فقط به‌عنوان متد additive قدیمی برای caller تغییرناپذیر باقی مانده، نه مسیر authoring اپ جدید.

۶. اعتبارسنجی، پیوند، build و test کردن revision تغییرناپذیر#

npx @al-amr/cli@0.1.0-alpha.7 validate --json
npx @al-amr/cli@0.1.0-alpha.7 login --device --json
npx @al-amr/cli@0.1.0-alpha.7 link --yes --json
npx @al-amr/cli@0.1.0-alpha.7 build --json
npx @al-amr/cli@0.1.0-alpha.7 test --yes --json

فرمان validate همان schema اجرایی Registry را اعمال می‌کند، از جمله حالت اجباری Compact، عضویت حالت ترجیحی، وابستگی‌های قابلیت، اعلان‌های notification و الزام‌های تحویل پس‌زمینه‌ای.

alamr build پس از همگام‌شدن هویت Registry، build واقعی production پروژه را اجرا می‌کند. alamr test همان بایت‌های دقیق را در یک workflow غیرتعاملی inventory، pack، upload، bind و بررسی می‌کند. وقتی نسل build عوض شود revision تغییرناپذیر تازه می‌سازد تا انتشار فقط-کدی با بایت‌های قدیمی برخورد نکند. inventory هنگام alamr test ساخته می‌شود و فایل تألیف محلی جاری با نام .al-amr/app-build.json وجود ندارد.

۷. باندل آزموده‌شده را ارسال کنید#

npx @al-amr/cli@0.1.0-alpha.7 publish --yes --json

publish همان revision و build digestای را ارسال می‌کند که alamr test پاس کرده است. دوباره build نمی‌کند، بایت دیگری upload نمی‌کند و با host ناشر تماس نمی‌گیرد. بایت تغییریافته build و test تازه می‌خواهد تا نسل تغییرناپذیر متناظر ساخته یا انتخاب شود.

۸. revision دقیقِ منتشرشده را فعال و اجرای مستقل را اثبات کنید#

پس از بازبینی انسانی و انتشار، یک مدیر Registry صریحاً revision فعال دقیق را فعال می‌کند — از صفحهٔ App در Admin Panel یا از گردش‌کار معادلِ CLI عمومی:

npx @al-amr/cli@0.1.0-alpha.7 admin apps list --json
npx @al-amr/cli@0.1.0-alpha.7 admin apps enable app_example rev_example_1 \
  --reason "Approved for platform-wide Runtime use" --json

در نسخهٔ v0.x این دسترس‌پذیری سراسری است: App فعال‌شده به هر Environment سازگار پیشنهاد می‌شود. دسترس‌پذیری مخصوص یک Environment پیاده‌سازی نشده است. revision تازهٔ App هرگز به‌طور ضمنی فعال نمی‌شود؛ پس از بازبینی و انتشار، یک مدیر باید همان revision دقیق را فعال کند.

در پایان، App فعال‌شده را از Widget یک Environment سازگار با حسابی که مالک پروژه نیست اجرا کنید. Journey نوشتاری تا اثبات آن اجرا با کد ALAMR_APP_LAUNCH_MISSING و وقتی principal مصرف‌کننده همان مالک ناشر باشد با کد ALAMR_APP_CONSUMER_PRINCIPAL_NOT_INDEPENDENT شکست می‌خورد.

فایل‌ها و قراردادهای عمومی#

• al-amr.app.json — manifest مربوط به App؛ schema در مرجع manifest آمده است؛
• createEmbeddedAppClient از @al-amr/sdk — تنها سطح پشتیبانی‌شدهٔ اتصال به Widget؛ مرجع SDK را ببینید؛
• client.authorizationHeader() — اعتبارنامه‌ای که بک‌اند App شما پیش از کلید زدن رکوردهای پایدار با appActorSub تأییدشده، از طریق Registry introspect می‌کند.

دروازه‌های انسانی#

دروازه	عامل	چه چیزی تأیید می‌شود
handoff مرورگر یا دستگاه در alamr login	مالک انسانی حساب	کد دستگاه و نشانی دقیقِ نمایش‌داده‌شده
alamr link	مالک پروژه	پیوند این دایرکتوری به Project دقیق در Registry
alamr publish --yes	مالک پروژه	ارسال چکیده‌های دقیق snapshot و build
تصمیم بازبینی	یک بازبین انسانی مستقل	شواهد منجمد؛ مالک و ارسال‌کننده نمی‌توانند خودبازبینی کنند
گذار انتشار	یک مدیر انتشار مستقل	چکیده‌های دقیق تأییدشده؛ بازبین نمی‌تواند منتشر کند
فعال‌سازی دسترس‌پذیری	یک مدیر Registry	فعال‌سازی revision دقیقِ منتشرشده با دلیل ثبت‌شده

خروجی‌های ساختاریافتهٔ مورد انتظار#

فرمان	شواهد موفقیت
alamr validate --json	کد خروج 0، مقدار ok: true و پیام اعتبار manifest
alamr build --json	build پروژه پس از همگام‌سازی هویت Registry کامل شده است
alamr test --yes --json	بررسی انتشار با buildDigest متصل‌شده، شناسهٔ درخواست و نتایج بررسی کامل شده است
alamr publish --yes --json	پیام Publication submission sent for review.
alamr admin apps enable ... --json	رکورد دسترس‌پذیری: appId، revisionId، enabled: true و updatedAt
alamr status --json	وضعیت معتبر درخواست در Registry و اقدام‌های مجاز بعدی

خطاهای پایدار و رفع آن‌ها#

کد	معنی	قابل تلاش مجدد؟	رفع
ALAMR_USAGE	آرگومان یا گزینهٔ نامعتبر	خیر	alamr --help را اجرا و فراخوانی را اصلاح کنید
ALAMR_AUTH_REQUIRED	اعتبارنامهٔ گمشده یا منقضی	خیر	alamr login را اجرا کنید یا توکن پروژهٔ scopeدار بدهید
ALAMR_NETWORK_ERROR	Registry در دسترس نیست	بله	DNS/TLS/proxy و سلامت Registry را بررسی و دوباره تلاش کنید
app_build_artifact_required	revision مربوط به App اتصال build تغییرناپذیر ندارد	خیر	build تازه و alamr test --yes --json را اجرا کنید
app_build_snapshot_changed	درخواست به چکیدهٔ build متفاوتی اشاره می‌کند	خیر	هرگز بایت‌های متفاوت را به revision ارسال‌شده متصل نکنید؛ revision تازه بسازید
app_build_artifact_invalid	فهرست متصل دیگر به چکیدهٔ خودش نمی‌رسد	خیر	revision تازهٔ App بسازید؛ فهرست متصل هرگز در جا ویرایش نمی‌شود
app_contract_incompatible	بازهٔ Contracts در manifest پلتفرم فعلی را رد می‌کند	خیر	revision تازه‌ای با اعلان Contracts ترفیع‌یافته بسازید
app_revision_not_found	فعال‌سازی یا انتشار به revision ناموجود اشاره می‌کند	خیر	appId و revisionId دقیق را با alamr admin apps list --json تأیید کنید
ALAMR_APP_LAUNCH_MISSING	اثبات اجرای مصرف‌کنندهٔ مستقل برای revision فعال‌شده وجود ندارد	بله	revision دقیقِ فعال‌شده را از Widget یک Environment سازگار اجرا کنید

فهرست کامل کدهای پایدار در عیب‌یابی آمده است.

تعریف «تمام‌شده»#

• حالت Compact به‌عنوان محصول کامل به عرض موبایل کار می‌کند؛ Workspace، اگر اعلان شده، به تغییر presentation درجا responsive است و Journey آن را اثبات می‌کند (در غیر این صورت ALAMR_APP_WORKSPACE_MODE_MISSING).
• قابلیت‌های اجباری و اختیاری با رفتار واقعی مطابق‌اند و هر فراخوانی Host Service حالت رد/در‌دسترس‌نبودن دارد.
• نمای محصول App هرگز توکن Runtime والد را نمی‌پذیرد یا نگه نمی‌دارد و رکوردهای پایدار از هویت App-pairwise تأییدشده استفاده می‌کنند.
• انتشار نهایی، فعال‌سازی و rollback فقط بایت‌های باندل تأییدشده و نگه‌داری‌شده را انتخاب می‌کنند.
• یک principal مصرف‌کنندهٔ مستقل، revision دقیقِ فعال‌شده را اجرا کرده است.
• مستندات حریم خصوصی و canonical همهٔ disclosureهای درخواستی را توصیف می‌کنند.

پاک‌سازی و بازیابی#

• هر تغییر در manifest، frontend یا بایت‌ها به revision تازهٔ App و چرخهٔ تازهٔ build/test نیاز دارد؛ هرگز بایت‌های متفاوت را به revision از‌پیش‌ارسال‌شده متصل نکنید.
• رد شدن تصمیم و تاریخچه‌ای تغییرناپذیر باقی می‌گذارد. اگر revision، مانیفست و بایت‌های منجمد build دقیقاً بدون تغییرند، alamr test و alamr publish را دوباره اجرا کنید؛ Registry می‌تواند همان درخواست منطبق را در draft باز کند بی‌آنکه تصمیم قبلی پاک شود. هر تغییر محتوا به revision و درخواست تازهٔ App نیاز دارد.
• فرمان alamr rollback app_revision <revisionId> --reason <text> فقط یک revision واجد شرایطِ همچنان‌منتشرشده با شواهد build تغییرناپذیر را می‌پذیرد و پیش از فعال‌سازی، باندل نگه‌داری‌شدهٔ آن را دوباره بررسی می‌کند.
• revisionهای قدیمی فقط-manifest همچنان خواندنی‌اند، اما نمی‌توان آن‌ها را دوباره ارسال، منتشر، فعال یا به‌عنوان مقصد rollback انتخاب کرد.
• یک مدیر می‌تواند دسترس‌پذیری Runtime را با alamr admin apps disable app_example rev_example_1 --reason <text> --json پس بگیرد.

روش‌های بازیابی برای هر وضعیت انتشار در بازیابی و ماشین وضعیت کامل در چرخهٔ انتشار آمده است. پیش از انتشار، Appها و اعتماد و امنیت را بخوانید.