برنامه‌ریزی، تحلیل و عملیات پلتفرم · فصل ۴ — Adapter، Capability، Shadow/Direct Publish و Quota · 212
Platform Capability Registry
داده و event دارد اما آن‌ها را به مدل تصمیم، attention، experiment یا platform policy قابل توضیح تبدیل نمی‌کند. موضوع جاری: «Platform Capability Registry». می‌تواند برای «Platform Capability Registry» model، signal و guardrail لازم را در یک workflow محدود تعریف و ارزیابی کند.
خلاصهٔ درس
داده و event دارد اما آن‌ها را به مدل تصمیم، attention، experiment یا platform policy قابل توضیح تبدیل نمی‌کند. موضوع جاری: «Platform Capability Registry».
می‌تواند برای «Platform Capability Registry» model، signal و guardrail لازم را در یک workflow محدود تعریف و ارزیابی کند.
خروجی این درس
می‌تواند برای «Platform Capability Registry» model، signal و guardrail لازم را در یک workflow محدود تعریف و ارزیابی کند.
پیش‌نیازها
1. مسئله: Feature visibility با API capability یکی نیست
وقتی کاربر در UI یک پلتفرم دکمه‌ای برای «آپلود ویدئو»، «ویرایش پست» یا «گزارش‌گیری» می‌بیند، هنوز معلوم نیست همان عمل از API رسمی، در نسخه فعلی، برای همان نوع حساب و با scope لازم قابل انجام باشد. خروجی این درس Platform Capability Registry v1 است؛ رجیستری‌ای که هر قابلیت را به evidence رسمی و نسخه‌دار متصل می‌کند.
2. مرز درس
PLN-021 فقط capability evidence را مدل می‌کند. Adapter و Policy Snapshot درس PLN-020، Shadow Validation درس PLN-022 و Direct Publish درس PLN-023 خارج از Scope هستند. این درس هیچ publish واقعی یا تماس شبکه‌ای انجام نمی‌دهد.
3. FACT خارجی و MAKNOW DESIGN
GitHub برای REST API یک OpenAPI machine-readable منتشر می‌کند. LinkedIn Marketing API نسخه‌دار است و تغییرات ماهانه می‌تواند رفتار resourceها را تغییر دهد. YouTube برای هر method پارامترها و quota impact را مستند می‌کند؛ videos.list در بررسی 2026-09-16 هزینه 1 quota unit دارد. اما stateهای SUPPORTED / CONDITIONAL / UNSUPPORTED / STALE_EVIDENCE / UNKNOWN MAKNOW DESIGN هستند.
4. requested action را به operation دقیق تبدیل کن
عبارت‌هایی مثل «پلتفرم X از ویدئو پشتیبانی می‌کند» برای Registry کافی نیست. باید مشخص شود action دقیق چیست: read_video_metadata، create_video، update_video یا delete_video. هر operation capability مستقل دارد و موفقیت یک operation، operation دیگر را ثابت نمی‌کند.
5. resource و media type را جدا نگه دار
resource_type مشخص می‌کند روی چه شیئی کار می‌کنیم و media_type نوع داده یا رسانه را محدود می‌کند. پشتیبانی از text post دلیل پشتیبانی از video upload نیست؛ پشتیبانی از video read هم دلیل video update نیست.
6. API version جزو evidence است
Capability بدون api_version ناقص است. اگر مستندات برای نسخه دیگری باشند یا نسخه مورد استفاده sunset/changed شده باشد، state قبلی را reuse نکن. LinkedIn نمونه خوبی است: version header و چرخه نسخه بخشی از قرارداد درخواست‌اند.
7. endpoint/method باید از evidence رسمی بیاید
endpoint_or_method باید به operation مورد درخواست اشاره کند، نه به یک صفحه عمومی یا UI. OpenAPI GitHub می‌تواند شکل operation و schema را نشان دهد؛ در YouTube نیز صفحه‌ی method پارامترهای مجاز همان method را ثبت می‌کند.
8. Auth scope و Account prerequisite دو Gate جدا هستند
داشتن endpoint مستند کافی نیست. ممکن است scope لازم در credential نباشد یا account/product tier prerequisite را نداشته باشد. در این حالت capability می‌تواند CONDITIONAL باشد، نه SUPPORTED.
9. Constraints و Quota را داخل همان row نگه دار
اندازه فایل، نوع media، required parameters، visibility rules و quota relevance باید قابل مشاهده باشند. Quota نامعلوم را صفر یا نامحدود فرض نکن؛ آن را QUOTA_REVIEW کن. Constraint صریحاً ناسازگار می‌تواند capability را UNSUPPORTED کند.
10. Evidence locator، Retrieved At و Provenance
هر row باید evidence_locator، زمان retrieval و provenance_ref داشته باشد. لینک بدون زمان برای APIهای volatile کافی نیست. Evidence قدیمی یا version-mismatched باید STALE_EVIDENCE شود و نیاز به recheck داشته باشد.
11. State machine محدود
SUPPORTED یعنی operation مستند، نسخه منطبق، scope/account/constraint معتبر، quota evidence قابل دفاع و provenance حاضر است. CONDITIONAL یعنی capability مستند است اما یک Gate اجرایی مثل scope، account prerequisite یا quota review باز است. UNSUPPORTED فقط با evidence صریح منفی صادر می‌شود. نبود evidence را UNKNOWN نگه دار؛ evidence قدیمی را STALE_EVIDENCE.
12. Baseline: operation مستند و evidence کامل
در baseline یک operation مستند GitHub با version، endpoint، scope، account prerequisite، constraints، quota relevance و provenance کامل ثبت می‌شود و به SUPPORTED می‌رسد. تصمیم بعدی فقط EXECUTE_SHADOW است؛ این lesson مجوز publish واقعی نمی‌دهد.
| case_id | platform_id | operation | api_version | endpoint_or_method | auth_scope_granted | quota_relevance | availability_state | fallback_state | next_decision |
|---|---|---|---|---|---|---|---|---|---|
| baseline_github_documented | github | create_issue | 2022-11-28 | POST /repos/{owner}/{repo}/issues | True | KNOWN | SUPPORTED | NONE | EXECUTE_SHADOW |
| ui_only_feature | provider-x | auto_magic_edit | 2026-09 | — | False | NONE | UNKNOWN | EVIDENCE_REQUIRED | BLOCKED_EVIDENCE |
| missing_auth_scope | update_campaign | 202608 | PATCH /rest/adCampaigns/{id} | False | KNOWN | CONDITIONAL | REAUTH_REQUIRED | DEFER_SCOPE_REPAIR | |
| version_mismatch | read_campaign | 202607 | GET /rest/adCampaigns/{id} | True | KNOWN | STALE_EVIDENCE | REVERIFY_VERSION | DEFER_RECHECK | |
| unsupported_media_type | provider-y | create_media | v3 | POST /media | True | KNOWN | UNSUPPORTED | ALT_MEDIA_OR_MANUAL | REJECT_AUTOMATION |
| missing_provenance | github | create_issue | 2022-11-28 | POST /repos/{owner}/{repo}/issues | True | KNOWN | UNKNOWN | EVIDENCE_REQUIRED | BLOCKED_EVIDENCE |
| quota_unknown | provider-z | create_post | v1 | POST /posts | True | UNKNOWN | CONDITIONAL | QUOTA_REVIEW | DEFER_QUOTA_REVIEW |
| transfer_youtube_videos_list | youtube | read_video_metadata | v3 | GET /youtube/v3/videos | False | KNOWN | SUPPORTED | NONE | EXECUTE_SHADOW |
13. Shortcutهای خطرناک
UI-visible را به API-supported تبدیل نکن؛ generic supports_video=true نساز؛ read را write فرض نکن؛ scope مفقود را نادیده نگیر؛ version قدیمی را current معرفی نکن؛ و quota نامعلوم را unlimited نکن. این shortcutها باعث false platform confidence می‌شوند.
14. Transfer: همان platform، operation یا media جدید
در transfer یک capability جدید از صفر ساخته می‌شود. مثال این درس videos.list در YouTube است: method و quota impact مستندند، پس read metadata می‌تواند SUPPORTED شود؛ اما از آن نتیجه نمی‌گیریم که upload/update همان evidence را دارد.
15. Lab، Assessment و Freshness
در lab/PLN-021-LAB1/learner/ دستور python run_checks.py را اجرا کن. هشت fixture شامل baseline، UI-only، missing scope، version mismatch، unsupported media، missing provenance، unknown quota و transfer هستند. منابع GitHub، LinkedIn و YouTube در 2026-09-16 دوباره بررسی شده‌اند؛ تغییر bytes پذیرفته‌شده نیازمند package version جدید است.
ارزیابی
پاسخ‌نامه‌ی این درس در بسته‌ی آموزش وجود ندارد؛ خودت جواب بده و صادقانه علامت بزن. «نیاز به مرور» درس را به صف تکرار می‌فرستد.
PLN-021-S1 retrieval
Why does a provider UI feature not prove the corresponding API capability?
PLN-021-S2 application
Build a capability row for a documented operation with version, scope, constraints, quota evidence and provenance.
PLN-021-S3 diagnosis
Diagnose a row whose operation is documented but the required auth scope is not granted.
PLN-021-S4 transfer
Rebuild the registry row for YouTube videos.list without inferring create/update capability from the read method.
ملاک‌های ارزیابی (rubric)
- Identity and boundary: capability registry is owned; adapter, shadow, and direct publish remain separate.
- Exact evidence binding: operation, version, method, scope, constraints, quota relevance and provenance are explicit.
- Typed negative states: UNKNOWN, STALE_EVIDENCE, CONDITIONAL and UNSUPPORTED are not coerced to success.
- Bounded decision: only SUPPORTED routes to the separate shadow gate.
- Transfer: changed platform/operation evidence is recomputed rather than copied.
منابع و تازگی
مطالعهٔ موارد (case studies)
فایل‌های آزمایشگاه
دستور python run_checks.py را اجرا کنید. هر fixture را بررسی کنید و سپس rowهای محدود خودتان را بسازید. Lab آفلاین و synthetic است: API key، تماس Provider یا Publish واقعی ندارد.
هدف: capability مستند را از UI visibility جدا کنید و stateهای non-success را صریح نگه دارید.