
روزی که اولین کد وارد شد، 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 ندارد و قسمت ۷ به این برمیگردد که تستها چه چیزی را ثابت میکنند و چه چیزی را نه.
قسمت ۳ میرود سراغ ویزارد آنبوردینگ، جایی که صفحهٔ انتظار از آن آمد و بخش بزرگی از ماه مه خرجش شد.
این یادداشت به انگلیسی هم منتشر شده است: نسخهٔ انگلیسی.
