Client Approval States و Revision Branching

1) چرا یک فیلد «Approved» کافی نیست؟

در پروژه‌های واقعی، بازخورد مشتری از چند کانال می‌رسد: کامنت، ایمیل، پیام‌رسان، review tool یا جلسه. اگر نتیجه‌ی همه‌ی این‌ها در یک فیلد mutable مثل Approved=true خلاصه شود، خیلی زود معلوم نیست چه کسی، دقیقاً کدام revision، با چه scope و چه اختیاری را تأیید کرده است. بعد یک ویرایش کوچک انجام می‌شود و همان approval قبلی ظاهراً روی نسخه‌ی جدید باقی می‌ماند؛ در حالی که مشتری هرگز نسخه‌ی جدید را ندیده است.

در این درس Client Approval Revision Branch Ledger v1 را می‌سازیم: یک ledger محدود و قابل‌ممیزی که approval، rejection و request-changes را به revision دقیق، branch lineage، reviewer role، authority و rationale متصل می‌کند.

قانون مرکزی: approval یک ویژگی شناور روی «آیتم» نیست؛ یک decision record روی revision مشخص است.

2) مرز درس

COM-018 مالک Client Approval States و Revision Branching است. COM-017 مالک Content Workflow States و COM-019 مالک Safe Workflow Lab است. این درس workflow کلی را از نو طراحی نمی‌کند و آزمایشگاه safety هم نمی‌سازد؛ تمرکز فقط روی این است که تصمیم مشتری در برابر revision و branch چگونه معتبر یا نامعتبر می‌شود.

همچنین این درس authority واقعی مشتری، قرارداد حقوقی، انتشار production، billing یا دسترسی tenant را ایجاد نمی‌کند. ما فقط یک مدل evidence-backed برای تصمیم‌گیری می‌سازیم.

3) مدل ذهنی: Case → Revision → Authority → Decision → Branch → Fresh Review

هر approval case باید حداقل این زنجیره را داشته باشد:

1. approval_case_id؛
2. content_item_id؛
3. baseline و branch مشخص؛
4. revision_id و revision_digest؛
5. reviewer و role؛
6. decision_authority؛
7. state تصمیم؛
8. scope و rationale؛
9. requested changes؛
10. supersession relation؛
11. conflict/reopen state؛
12. audit event و evidence ref.

اگر یکی از اجزای حیاتی گم باشد، تصمیم نباید به‌زور «Approved» شود. stateهای محدود مثل HOLD، DISPUTED یا BLOCKED بخشی از طراحی درست‌اند.

4) Fact بیرونی را از طراحی MAKNOW جدا کن

مستندات فعلی Contentful نشان می‌دهد workflow stepها می‌توانند مشخص کنند چه کاربران یا تیم‌هایی حق edit، publish یا تغییر step را دارند. همچنین workflow می‌تواند حرکت رو به جلو یا عقب برای revision بیشتر داشته باشد. این‌ها FACT درباره‌ی رفتار پلتفرم هستند.

اما این نتیجه از Contentful درنمی‌آید که approval باید دقیقاً با چه branch naming، چه state vocabulary یا چه merge rule ذخیره شود. binding تصمیم به revision و branch، و این‌که edit بعد از approval نیازمند fresh review است، DESIGN داخلی MAKNOW است.

5) approval باید به revision identity متصل باشد

دو شناسه را از هم جدا کن:

• revision_id: شناسه‌ی منطقی نسخه؛
• revision_digest: fingerprint محتوای همان نسخه.

اگر مشتری revision r17 با digest مشخص را approve کرده و بعد محتوای همان item تغییر کرده، تصمیم قدیمی نباید روی r18 یا digest جدید حمل شود. حتی اگر عنوان آیتم و URL ثابت باشند، evidence عوض شده است.

در ledger، یک approval فقط وقتی معتبر است که revision تصمیم با revision فعال برابر باشد و lineage آن قابل‌ردیابی باشد. mismatch باید state را به BLOCKED_STALE_APPROVAL ببرد، نه این‌که «تقریباً approved» فرض شود.

6) branch lineage جلوی approvalِ اشتباه را می‌گیرد

فرض کن از baseline یک branch برای طراحی و یک sibling branch برای اصلاح حقوقی ساخته شده است. approval روی branch طراحی، خودکار روی sibling حقوقی معتبر نیست. ممکن است diff کوچک باشد، اما evidence مستقل است.

بنابراین branch_id، branch_parent و merge_target باید قابل‌ردیابی باشند. اگر approval از branch دیگری reuse شود، نتیجه باید BLOCKED_CROSS_BRANCH_APPROVAL باشد تا یک تصمیم تازه ثبت شود.

7) authority با role یکی نیست

داشتن role مثل Editor یا Designer لزوماً به معنی حق نهایی تأیید مشتری نیست. reviewer_role توصیف می‌کند فرد چه نقشی دارد؛ decision_authority می‌گوید آیا همان فرد می‌تواند این نوع decision را صادر یا supersede کند.

اگر یک reviewer بدون authority تصمیم client approver را supersede کند، ledger باید آن را مسدود کند. نام کاربر، seniority یا دسترسی UI جای authority evidence را نمی‌گیرد.

8) state vocabulary باید معنی عملی داشته باشد

برای این درس stateهای اصلی چنین‌اند:

• APPROVED_REVISION_BOUND: revision دقیق با authority معتبر تأیید شده؛
• CHANGES_REQUESTED: تغییرات مشخص درخواست شده‌اند؛
• REJECTED: تصمیم رد با rationale ثبت شده؛
• HOLD_MISSING_EVIDENCE: evidence حیاتی ناقص است؛
• BLOCKED_STALE_APPROVAL: approval مربوط به revision قدیمی است؛
• BLOCKED_CROSS_BRANCH_APPROVAL: تصمیم از branch دیگری reuse شده؛
• BLOCKED_UNAUTHORIZED_SUPERSESSION: actor حق override ندارد؛
• DISPUTED_CONFLICT: تصمیم‌های متعارض بدون resolution وجود دارد؛
• PARTIAL_SCOPE_REOPENED: فقط scope مشخصی دوباره برای review باز شده است.

این vocabulary قرار نیست تمام سیستم workflow را مالک شود؛ فقط outcome محدود این درس را پوشش می‌دهد.

9) conflict و supersession را پاک نکن

وقتی دو reviewer تصمیم متفاوت می‌دهند، overwrite کردن رکورد قبلی audit trail را خراب می‌کند. تصمیم جدید باید supersedes_decision_id داشته باشد، و conflict قبلی باید قابل‌ردیابی بماند.

اگر conflict هنوز باز است، merge نباید نتیجه‌ی نهایی بسازد. conflict_state=OPEN باید یک state مثل DISPUTED_CONFLICT ایجاد کند. فقط بعد از resolution مستند، branch می‌تواند به merge candidate تبدیل شود.

10) درخواست تغییر هم باید evidence داشته باشد

requested_change_ids نباید متن مبهمی مثل «یه کم بهترش کن» باشد. هر change بهتر است شناسه، scope و rationale داشته باشد تا معلوم شود کدام بخش approval قبلی را invalidate کرده است.

اگر تغییر فقط بخشی از محتوا را تحت‌تأثیر قرار داده، می‌توان accepted scope را حفظ کرد و فقط همان scope را reopen کرد. این دقیقاً جایی است که revision branching از دوباره‌کاری کامل جلوگیری می‌کند.

11) Lab: هشت fixture برای failure path واقعی

Lab این درس آفلاین، synthetic و بدون credential است. هشت fixture داریم و برای هر fixture شش invariant deterministic بررسی می‌شود؛ در مجموع 48 assertion.

Failureها شامل این موارد‌اند:

• edit بعد از approval بدون fresh revision review؛
• reuse approval روی sibling branch؛
• supersession توسط reviewer بدون authority؛
• missing evidence؛
• conflict unresolved؛
• merge قبل از resolution؛
• transfer case که یک clause حقوقی بعداً reopen می‌شود.

هدف این نیست که فقط baseline را سبز کنیم؛ باید دقیقاً ببینیم چرا shortcutها blocked یا disputed می‌شوند.

12) تمرین انتقال: فقط scope آسیب‌دیده را دوباره باز کن

سناریوی انتقال: مشتری کل campaign bundle را approve کرده، اما legal reviewer بعداً فقط یک clause را reopen می‌کند. طراحی ضعیف یا approval کل bundle را معتبر نگه می‌دارد، یا برعکس همه‌چیز را از صفر وارد review می‌کند.

طراحی درست این است:

• accepted scopeهای دست‌نخورده حفظ شوند؛
• clause بازشده در revision branch جدید قرار گیرد؛
• reopen_reason و requested change ثبت شوند؛
• فقط همان scope نیازمند fresh approval باشد؛
• merge نهایی تا resolution همان scope متوقف بماند.

این fixture باید به PARTIAL_SCOPE_REOPENED برسد، نه approval کامل و نه reset کامل.

13) جمع‌بندی و معیار عبور

Client Approval States زمانی قابل‌اعتمادند که تصمیم را از یک flag mutable به رکورد نسخه‌دار و authority-bound تبدیل کنیم. برای عبور از این درس باید بتوانی ثابت کنی: revision و digest دقیق‌اند، branch lineage روشن است، reviewer authority معتبر است، conflict overwrite نشده، requested changes قابل‌ردیابی‌اند و edit بعد از approval به fresh review منجر می‌شود.

Artifact نهایی این درس Client Approval Revision Branch Ledger v1 است؛ publication یا release authority نیست.

منابع و تازگی

• Contentful Help Center, Workflows — rechecked 2026-09-15.
• Contentful Help Center, Workflow rules: editing and publishing permissions — rechecked 2026-09-15.
• Contentful Help Center, Workflow step change permissions — rechecked 2026-09-15.
• revision binding، branch semantics، supersession و partial-scope reopen در این درس DESIGNهای MAKNOW هستند و به vendor نسبت داده نمی‌شوند.