یادداشت‌های همسایه ۲: «مدیر» یک ستون نیست

یادداشت‌های همسایه ۲: «مدیر» یک ستون نیست

روزی که اولین کد وارد شد،‏ UserRole در همسایه سه مقدار داشت: Admin،‏ Builder و Resident. هر فرد یک نقش داشت که روی ردیف کاربر ذخیره می‌شد و در توکن همراهش بود. محصول مدیریت ساختمان خیلی زود به این مدل فشار می‌آورد،‏ چون یک نفر می‌تواند در یک ساختمان زندگی کند،‏ ساختمان دیگری را مدیریت کند و سیستم را هم بگرداند. مدیریت هم از یک نفر به نفر بعدی می‌رسد و سوابق باید از این تحویل سالم بیرون بیایند.

صفحهٔ مطالعهٔ موردی فقط می‌گوید نقش‌ها به ساختمان بستگی دارند. رسیدن به آن چند تغییر بین آوریل و ژوئن لازم داشت و یک تکه داده در شش روز دو بار جابه‌جا شد. نیمهٔ دوم این نوشته به مسئلهٔ مرتبطی می‌پردازد: APIای که بر اساس مخاطب تقسیم شد،‏ برای مخاطبانی که صفحه‌هایشان مشترک است.

آنچه مدل قدیمی نمی‌توانست بگوید

چک‌لیستی که ۵ آوریل،‏ روز شروع بازنویسی،‏ اضافه شد مشکل‌ها را نام می‌برد. User.Role «یک نقش سراسری واحد» بود. از Building.CreatedByUserId «هم به‌عنوان متادیتای ایجاد و هم برای کنترل دسترسی فعال» استفاده می‌شد. دسترسی ساکن از عضویت‌های فعال در واحدها استنتاج می‌شد و توکن یک نقش را نشان می‌داد.

همان فایل هدف را هم تعیین می‌کند. یک نفر می‌تواند هم‌زمان چند انتساب در ساختمان‌های مختلف داشته باشد،‏ یک ساختمان می‌تواند هم‌زمان چند مدیر داشته باشد و تاریخچهٔ ساکنان به شکل بازه‌های تاریخی نگه داشته می‌شود که با asOfUtc قابل کوئری است. همچنین می‌گوید هنگام انتقال مدیریت،‏ تاریخچهٔ ساختمان تغییرناپذیر بماند،‏ «با پایان دادن به یک انتساب و ایجاد انتسابی دیگر». پرسونای مدیر داوطلب همین را به زبان محصول می‌خواهد: تحویل به مدیر جدید با حفظ همهٔ سوابق.

دو خانه برای یک نقش ساختمانی

در ۵ آوریل،‏ چهار کامیت در حدود دو ساعت و نیم اولین حرکت را انجام دادند. UserAccessAssignment به‌عنوان رکوردی زمان‌دار همراه با یک مایگریشن backfill آمد (۱۳ فایل،‏ ۲٬۶۴۲ خط اضافه‌شده). نشست‌ها به اسنپ‌شات‌های دسترسی رفتند،‏ مدیریت ساختمان از انتساب‌های زمانی resolve شد و فرانت‌اند هم اسنپ‌شات‌ها را پذیرفت. در ۷ آوریل enum به Admin و User کوچک شد.

در ۱۱ آوریل نقش‌های ساختمان دوباره جابه‌جا شدند،‏ این بار به اگریگیت و جدول خودشان یعنی BuildingRole،‏ و برای UserAccessAssignment فقط دسترسی سطح سیستم ماند. آن کامیت به ۳۵ فایل دست زد. پیامش نتیجه را توصیف می‌کند و به کپسوله‌سازی اشاره دارد. ثبت نمی‌کند طراحی‌ای که شش روز از عمرش می‌گذشت چه ایرادی داشت. اگریگیت این شکلی است،‏ خلاصه‌شده به فیلدهایی که اینجا مهم‌اند:

public sealed class BuildingRole : AggregateRoot
{
    public Guid BuildingId { get; private set; }
    public Guid UserId { get; private set; }
    public BuildingRoleType RoleType { get; private set; }
    public Guid? GrantedByUserId { get; private set; }
    public Guid? EndedByUserId { get; private set; }
    public DateTime EffectiveFromUtc { get; private set; }
    public DateTime? EffectiveToUtc { get; private set; }

    public bool IsActiveAt(DateTime atUtc)
        => EffectiveFromUtc <= atUtc && (!EffectiveToUtc.HasValue || EffectiveToUtc > atUtc);
}

BuildingRoleType دو مقدار دارد،‏ Manager و BoardMember. ساکن بودن واقعیتی جداست که با تاریخ‌های ورود و خروج خودش روی UnitMembership نگه داشته می‌شود. پس یک نفر در یک ساختمان می‌تواند ردیف نقش،‏ ردیف عضویت،‏ هر دو یا هیچ‌کدام را داشته باشد،‏ و AuthAccessSnapshotFactory این منابع را برای یک لحظهٔ مشخص با هم ترکیب می‌کند،‏ همراه با انتساب‌های سیستمی و پیوندهای سازمانی.

انتقال همان‌طور کار می‌کند که چک‌لیست خواسته بود. یک هندلر نقش فعلی را پایان می‌دهد و نقش تازه‌ای برای جانشین می‌سازد،‏ پس ردیف قدیمی به‌عنوان تاریخچه می‌ماند. بررسی هم‌پوشانی به ازای هر نفر،‏ ساختمان و نوع نقش اجرا می‌شود و به همین دلیل دو نفر متفاوت می‌توانند هم‌زمان یک ساختمان را مدیریت کنند. این بررسی در کد اپلیکیشن است. ایندکس‌های جدول یکتا نیستند،‏ پس اگر دو نوشتن با هم رقابت کنند،‏ چیزی در پایگاه داده جلوی دو ردیف هم‌پوشان برای یک نفر را نمی‌گیرد.

کنترلری بدون [Authorize]

بین آن دو حرکت،‏ در ۹ آوریل،‏ کامیتی که دسترسی مدیر سیستم و مدیر ساختمان را از هم جدا می‌کرد ثبت کرد که SystemAdminsAdminController «اصلاً [Authorize] نداشت». تا جایی که کد در آن کامیت نشان می‌دهد،‏ درخواست‌ها با این حال رد می‌شدند: خواندن شناسهٔ کاربر فعلی برای فراخوان ناشناس با خطای ۴۰۱ شکست می‌خورد و هر پنج هندلر پشت کنترلر نقش مدیر سیستم را بررسی می‌کردند. آنچه کم بود اعلام در لایهٔ HTTP بود. کامیت [Authorize(Roles = "Admin")] را اضافه کرد و چهار کنترلر سیستمی دیگر را از [Authorize] ساده به همین نقش برد. این اتریبیوت امروز روی آن کنترلر هست.

چک‌لیست جهت دیگری را نشان داده بود و قصد داشت [Authorize(Roles = ...)] را با دسترسی احراز هویت‌شده به‌علاوهٔ بررسی‌های سطح اپلیکیشن جایگزین کند. کد به هر دو رسید. کنترلرهای سیستمی مثل همین یکی اتریبیوت نقش دارند و هندلرها دسترسی ساختمان را با کمک‌کننده‌هایی مثل AdminAccessHelper،‏ TicketAccessHelper و DocumentAccessScopeResolver دوباره بررسی می‌کنند.

فرضی که زنده ماند

چک‌لیست در ۵ آوریل از CreatedByUserId نام برده بود،‏ اما ایدهٔ پشت آن تا اواخر مه دوام آورد. هر کسی که ثبت‌نام می‌کرد مدیر آینده فرض می‌شد و هر کسی که ساختمانی می‌ساخت مدیر دائمی آن. در ۱۹ مه یک صفحهٔ انتظار جای فرض مدیر خودکار را گرفت. در ۲۱ مه کامیت دیگری بقیه‌اش را بست و پیامش رفتار قدیمی را می‌گوید: سه متد ریپازیتوری «هر سازنده‌ای را،‏ فارغ از نقشی که انتخاب کرده بود،‏ مدیر دائمی حساب می‌کردند». همان پیام اثر اصلاح را هم می‌گوید: «ساکنی که ساختمان را ساخته دیگر بعد از رفرش صفحه به پنل ادمین نمی‌رسد.»

کوئری فعلی را بررسی کردم و دسترسی سازنده حالا فقط تا وقتی IsOnboardingComplete برابر false است اعمال می‌شود. در این مدت،‏ فکتوری اسنپ‌شات دسترسی مدیر را می‌سازد. بعد از آن فقط یک نقش مدیر صریح و فعال حساب است. قسمت ۳ به ویزاردی می‌پردازد که به این نیاز دارد.

نقش‌هایی که کس دیگری اعطا کرده یک قاعدهٔ دیگر هم دارند:

public static bool RequiresAcceptance(BuildingRole role)
    => role.GrantedByUserId.HasValue && role.GrantedByUserId.Value != role.UserId;

public static bool IsAccepted(BuildingRole role, IReadOnlyDictionary<Guid, DateTime?> lastLoginByUser)
    => !RequiresAcceptance(role)
        || (lastLoginByUser.TryGetValue(role.UserId, out var lastLoginAtUtc)
            && lastLoginAtUtc.HasValue
            && lastLoginAtUtc.Value >= role.EffectiveFromUtc
            && lastLoginAtUtc.Value >= role.CreatedAtUtc);

چنین نقشی تا وقتی شخص در زمان اعطا یا بعد از آن با موفقیت لاگین نکند Pending گزارش می‌شود،‏ بعد Active و سپس Ended. پس پذیرش در اینجا یعنی یک لاگین بعدی. این هلپر اکشن جداگانه‌ای برای پذیرش ندارد و لاگینی که به هر دلیل دیگری هم انجام شود حساب است.

این قاعده قبلاً به‌صورت inline در سه کوئری ریپازیتوری بود و فعالیت لاگین را از کانتکست هویت داخل یک کوئری ساختمان join می‌کرد. کامیتی در ۴ ژوئن آن را با سه مرحله جایگزین کرد: بارگذاری نقش‌های کاندید،‏ بارگذاری زمان‌های لاگین و فیلتر در حافظه. پیامش دلیلی نمی‌دهد. تا جایی که diff نشان می‌دهد،‏ یک عبارت LINQ روی دو کانتکست به خواندن‌های جداگانه تبدیل شد و قسمت ۴ به هزینهٔ جدا شدن کانتکست‌ها در جاهای دیگر می‌پردازد. این قاعده حالا دو جا هست،‏ در BuildingRoleAcceptanceHelper و در متد خصوصی IsAcceptedRole در BuildingRepository،‏ به شکل دو تکه کد جدا.

دو هاست،‏ یک دسته صفحه

ساعت ۲۳:۰۸ روز ۱۰ آوریل،‏ API واحد به Hamsayeh.Api.Admin و Hamsayeh.Api.User تبدیل شد و زیرساخت مشترک به Hamsayeh.Api.Shared رفت. آن کامیت به ۸۰ فایل دست زد و این جدایی را چنین توصیف کرد: «Api.Admin برای SystemAdmin و Api.User برای BuildingManager و ساکنان».

اولین اصلاح ۳۵ دقیقه بعد آمد: «SubscriptionController فقط در Admin API بود اما BuildingManagerها به آن نیاز دارند». دومی ساعت ۰۰:۰۷ آمد و endpointهای داشبورد و وضعیت دسترسی را جابه‌جا کرد،‏ چون صفحه‌های داشبورد و پرداخت‌های در انتظار «برای BuildingManagerها در دسترس‌اند (بدون requiredScope="system") اما endpointهای Admin API را صدا می‌زدند».

علت در فرانت‌اند است. پورتال مدیریت یک کدبیس است که به مدیران سیستم و مدیران ساختمان خدمت می‌دهد و این دو با یک scope از هم جدا می‌شوند:

export type AdminAccessScope = 'building' | 'system'

مسیری که requiredScope آن روی scope سیستم باشد مدیران ساختمان را به جای دیگری ریدایرکت می‌کند. این گارد یک ریدایرکت است و چیزی را در سرور ثابت نمی‌کند. با این حال ثبت می‌کرد کدام صفحه‌ها فقط مخصوص سیستم‌اند و هر صفحه‌ای که آن را نداشت،‏ در هر پوشه‌ای که بود،‏ مال مدیران هم بود. این صفحه‌ها نمی‌توانستند داده‌شان را از هاستی بگیرند که برای مدیران سیستم توصیف شده بود.

اگر اتریبیوت‌های متد HTTP را با grep بشماریم،‏ که اکشنی با دو اتریبیوت دو بار حساب می‌شود،‏ Api.Admin امروز ۸ کنترلر و ۳۰ اتریبیوت دارد و Api.User ۲۷ کنترلر و ۲۰۹ اتریبیوت. تقریباً همهٔ داده‌های پورتال مدیریت روی User API است و از ۹ مه زیر پیشوند مسیر building-manager قرار دارد. تا جایی که کد نشان می‌دهد،‏ هاست‌ها در نهایت بیشتر به «اپراتور سیستم در برابر بقیه» نزدیک شدند تا «پورتال ادمین در برابر پورتال ساختمان». مرزی که تعیین‌کننده بود scope در سطح صفحه بود و هاست‌ها مجبور شدند دنبالش بروند.

احراز هویت تا ۱۵ مه به شکل کنترلر در هر دو هاست تکرار شده بود،‏ تا اینکه هشت مسیر Minimal API در Api.Shared جای آن‌ها را گرفتند و در هر دو هاست map شدند (۵ فایل،‏ ۱۴۹ خط اضافه،‏ ۲۲۸ خط حذف). کلاینت‌های فرانت‌اند نتیجه را در سه خط نشان می‌دهند:

export const adminApiClient = createApiClient(ADMIN_API_BASE_URL)
export const userApiClient = createApiClient(USER_API_BASE_URL)
export const buildingApiClient = userApiClient

یک اسکریپت بیلد به نام check-default-api-client-imports.mjs ایمپورت پیش‌فرض کلاینت را رد می‌کند،‏ پس هر فیچر باید نام کلاینتی را که استفاده می‌کند بیاورد. این کار انتخاب را در بازبینی قابل دیدن می‌کند. تشخیص نمی‌دهد انتخاب درست است یا نه و صفحه‌ای که به هاست اشتباه وصل شده باشد باز هم از این بررسی می‌گذرد.

آنچه ناتمام مانده

چک‌لیست گفته بود User.Role «باید از دامنه،‏ احراز هویت و فرض‌های رابط کاربری حذف شود». حذف نشد. این enum کوچک‌تر شده و هنوز در بررسی‌های سطح سیستم نقش دارد،‏ پس مدل قدیمی و مدل جدید در آن گوشه کنار هم زندگی می‌کنند.

شواهد تست برای این‌ها محدود است. AuthAccessSnapshotFactoryTests سه تست دارد: مدیری بدون عضویت ساکن،‏ یک ساکن و فردی که هنوز دسترسی ندارد. چهار سناریوی امنیتی و یک تست دسترسی بین‌پورتالی به‌صورت اسپک Playwright وجود دارند. مخزن نتیجهٔ CI ندارد و قسمت ۷ به این برمی‌گردد که تست‌ها چه چیزی را ثابت می‌کنند و چه چیزی را نه.

قسمت ۳ می‌رود سراغ ویزارد آنبوردینگ،‏ جایی که صفحهٔ انتظار از آن آمد و بخش بزرگی از ماه مه خرجش شد.

این یادداشت به انگلیسی هم منتشر شده است: نسخهٔ انگلیسی.

بازگشت به همهٔ یادداشت‌ها