معماری یک SaaS فارسی و RTL برای مدیریت ساختمان چه چالش‌هایی دارد؟

SaaS مدیریت ساختمان اگر فقط «پنل شارژ» دیده شود، از روز اول کج طراحی می‌شود. یک سمت مدیر ساختمان است که باید وضعیت واحدها، هزینه‌ها و پیگیری را ببیند. سمت دیگر ساکن است که باید بدهی خودش، رسید و اعلان را بفهمد، نه دفترکل کل مجموعه را. این دو کار در یک دامنه و یک دیتابیس زندگی می‌کنند، اما محصول واحد نیستند. اگر مجوز را در کامپوننت مخفی کنید، دیر یا زود API همان داده را به نقش اشتباه می‌دهد.

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

دو نقش یعنی دو مرز داده، نه دو قالب رنگ

مدیروار دیدن یعنی فهرست واحدها، تجمیع بدهی، ثبت هزینه و صدور اعلان برای مجموعه. ساکن‌وار دیدن یعنی «واحد من»، «بدهی من»، «رسید من». اگر یک مدل ساختمان و یک مدل کاربر داشته باشید و بقیه را با شرط نقش در UI حل کنید، فردا نقش سومی می‌آید — حسابدار ساختمان، مالک غیرساکن، اپراتور پشتیبانی — و همهٔ شرط‌ها می‌ترکند.

نمونهٔ عمومی همین جداسازی را در نرم‌افزار مدیریت ساختمان خانه‌بان می‌بینید: مسیر مدیریت و مسیر ساکن روی یک محصول. از ظاهر عمومی متریک کاربر یا نتیجهٔ مالی نمی‌سازیم؛ فقط الگوی دو مرز داده را به‌عنوان زمینهٔ معماری ذکر می‌کنیم. نمونه‌های اجراشده را در پروژه‌های NODE ببینید؛ آن صفحه ویترین است، نه جایگزین ماتریس مجوز شما.

مرز را در لایهٔ مجوز بگذارید، نه در مخفی کردن دکمه. هر درخواست باید زمینه داشته باشد: کدام ساختمان، کدام واحد، کدام نقش در آن ساختمان. عضویت چندساختمانی رایج است؛ یک نفر ممکن است ساکن یکجا و مدیر جای دیگر باشد. نشست کاربر را با «نقش سراسری» قاطی نکنید. نقش به عضویت در یک محدوده وابسته است.

ورود را هم جدا فکر کنید. مدیر و ساکن ممکن است از یک URL وارد شوند، اما onboarding و اولین صفحه باید کار همان نقش را نشان دهد. اگر ساکن بعد از ثبت‌نام به داشبورد مدیریت خالی برسد، محصول را نفهمیده؛ شما قیف را خراب کرده‌اید. طراحی این مسیر را در قیف ورود و فعال‌سازی کاربر SaaS دنبال کنید؛ اینجا فقط پیامد معماری‌اش مهم است: هویت، عضویت، و صفحهٔ خانه باید از یک منبع حقیقت نقش خوانده شوند.

مدیریت نقش کاربران را مثل ماتریس مجوز مدل کنید

مدیریت نقش در این دامنه از RBAC کلاسیک پیچیده‌تر می‌شود چون منبع هم ساختمان است هم واحد. حداقل این محورها را نام‌گذاری کنید: سوژه (کاربر)، محدوده (ساختمان یا واحد)، فعل (خواندن تجمیع، ثبت سند، پرداخت، ارسال اعلان)، و منبع (سند مالی، فایل، پیام). نقش برچسب است؛ مجوز، اجازهٔ فعل روی منبع در محدوده است.

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

API را با همان ماتریس ببندید. الگوی خطرناک: فرانت مسیر مدیر و ساکن دارد اما هر دو به یک endpoint دفترکل بدون فیلتر محدوده می‌رسند. تست یکپارچگی باید با توکن ساکن، تجمیع ساختمان را نگیرد. این تست محصول است، نه جزئیات پیاده‌سازی.

دعوت و اتصال واحد را هم در مدل ببینید. ساکن معمولاً با کد دعوت، لینک، یا تأیید مدیر به واحد وصل می‌شود. این جریان هویت می‌سازد. اگر هر کسی با ایمیل وارد شود و شماره واحد را خودش بگوید، مرز داده از بین می‌رود. معماری باید اتصال را یک رویداد قابل‌حسابرسی بداند: چه کسی، چه واحدی، چه زمانی.

سابقهٔ مالی دادهٔ مهندسی است، نه صفحهٔ اکسل

در محصول مدیریت ساختمان، عدد روی صفحه فقط نمایش نیست. سند بدهی، پرداخت، هزینه و تصحیح، سابقه هستند. از نظر مهندسی یعنی چند قانون سخت، مستقل از اینکه سهم واحد چطور حساب شده باشد.

سند را به‌جای فیلد قابل‌ویرایش، رویداد ببینید. ثبت پرداخت یک رویداد است؛ ویرایش مبلغ پرداخت‌شده باید رویداد تصحیح یا برگشت باشد، نه به‌روزرسانی همان ردیف بدون ردپا. اگر مدیر بتواند عدد را درجا عوض کند و تاریخچه نماند، پشتیبانی و اختلاف واحد غیرقابل‌حل می‌شود. این را با نرم‌افزار حسابداری کامل اشتباه نگیرید؛ حداقل چیزی که لازم دارید ردپای تغییر است: قبل، بعد، عامل، زمان.

مبلغ را با نوع پول و مقیاس مشخص ذخیره کنید. اعشار شناور برای پول مناسب نیست. واحد پول را در سند قفل کنید، نه در تنظیمات لحظه‌ای که گذشته را بازنویسی کند.

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

گزارش را از سند بسازید، سند را از گزارش نسازید. خروجی PDF یا اکسل باید همان داده‌ای را نشان دهد که API می‌خواند. دو مسیر محاسبه یعنی دو حقیقت.

این بخش را با تفسیر قانون تملک یا نحوهٔ تقسیم هزینه عوض نکنید. نرم‌افزار باید آنچه کاربر ثبت می‌کند را درست نگه دارد و نشان دهد؛ مسئولیت قواعد کسب‌وکار با محصول و مشتری است، با مقالهٔ معماری نیست.

اعلان سه کانال است؛ صف داخلی منبع حقیقت است

مدیر می‌خواهد «خبر بده». ساکن می‌خواهد «دیر نفهمم». اگر ارسال را مستقیم به درگاه پیامک یا ربات گره بزنید، شکست شبکه یعنی پیام از دست رفته و UI تیک خورده. معماری درست: رویداد اعلان در محصول ثبت می‌شود، سپس تحویل به کانال‌ها تلاش می‌شود.

کانال‌های رایج در ایران برای این محصول: اعلان درون‌برنامه، پیامک، و گاهی پیام در پیام‌رسان. هر کانال محدودیت و هزینه دارد. اولویت را در محصول تعریف کنید: بدهی جدید ممکن است درون‌برنامه کافی باشد؛ قطعی پرداخت ممکن است پیامک بخواهد. این تصمیم محصول است؛ زیرساخت باید هر کانال را جدا و قابل‌غیرفعال‌سازی مدل کند.

وضعیت تحویل را ذخیره کنید: صف، ارسال‌شده، شکست، لغو. متن پیام را قالب‌بندی کنید اما متن نهایی را برای اختلاف بعدی نگه دارید؛ بدون ذخیرهٔ دادهٔ پرداخت حساس. تلاش مجدد برای پیامک باید idempotent باشد تا پیام تکراری ارسال نشود.

اگر تلگرام در معماری شما هست، آن را مثل VPN فرض نکنید. برای سروری که به Bot API دسترسی پایدار ندارد، الگوی درگاه لایهٔ کاربرد جداست. در SaaS ساختمان، تلگرام یک کانال تحویل است نه هستهٔ دفتر مالی.

RTL فارسی لایهٔ قرارداد است، نه dir روی یک جعبه

SaaS فارسی RTL یعنی تمام مسیر کاربر راست‌به‌چپ فکر شده: چینش، تایپوگرافی، اعداد، تاریخ، و ورودی پول. اگر جهت را روی بدنه بگذارید و کتابخانهٔ نمودار و تقویم را چپ‌به‌راست رها کنید، مدیر در گزارش ماهانه گیج می‌شود و اعتمادش به عدد کم می‌شود حتی وقتی عدد درست باشد.

اعداد را سیاست‌گذاری کنید. نمایش فارسی برای کاربر، ذخیرهٔ لاتین برای محاسبه. تاریخ را با تقویم مورد استفادهٔ محصول یکدست کنید؛ مخلوط شمسی در UI و میلادی در سند بدون تبدیل صریح، گزارش دوره‌ای را خراب می‌کند. این را در مدل داده بنویسید: هر سند یک لحظهٔ مطلق دارد و یک نمایش محلی.

ورودی مبلغ، شماره واحد و شماره تماس را برای صفحه‌کلید فارسی و لاتین تحمل کنید، اما قبل از ذخیره نرمال کنید. نیم‌فاصله در نام ساختمان برای جست‌وجو مسئله است؛ یک شکل نرمال برای ایندکس داشته باشید و شکل نمایش را جدا نگه دارید.

کامپوننت‌های آماده را قبل از ورود به محصول برای RTL ارزیابی کنید. جدول داده، انتخابگر تاریخ، پلهٔ پرداخت و اعلان لحظه‌ای. وصلهٔ CSS بعد از انتخاب کتابخانه گران‌تر از انتخاب موجودیت سازگار با راست‌به‌چپ است. فونت فارسی را هم بخشی از سیستم طراحی بدانید؛ عرض رقم روی تراز ستون مالی اثر می‌گذارد.

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

پرداخت و پیامک ایرانی را پشت آداپتور بگذارید

اتصال به درگاه پرداخت و سرویس پیامک در ایران بخشی از معماری نرم‌افزار SaaS است، نه افزونهٔ هفتهٔ آخر. هر دو سیستم بیرونی‌اند: تاخیر، تکراری شدن بازگشت، و تغییر وضعیت دارند.

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

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

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

لاگ این آداپتورها نباید شماره کارت یا متن کامل پیامک را نگه دارد. شناسهٔ جلسه، وضعیت، و کد خطای ارائه‌دهنده کافی است. جزئیات مشاهده‌پذیری را در ساخت تست، CI/CD و مانیتورینگ قابل دفاع ببینید؛ در SaaS مالی، لاگ پرحرف خودش حادثه است.

چندمستأجری و پشتیبانی را از روز اول محدود کنید

هر ساختمان یک مستأجر منطقی است حتی اگر روی یک دیتابیس باشید. هر کوئری باید با کلید محدوده فیلتر شود. ابزار پشتیبانی محصول حق دیدن همهٔ ساختمان‌ها را دارد، اما آن مسیر باید نقش جدا، حسابرسی جدا و UI جدا داشته باشد. ورود پشتیبانی با حساب مدیر مشتری، مرز را پاک می‌کند.

پشتیبان باید بتواند نمای ساکن و نمای مدیر را بدون عوض کردن رمز مشتری ببیند؛ در غیر این صورت برای دیباگ از مشتری رمز می‌گیرد. impersonation را رویداد کنید و زمان‌دار کنید.

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

تست معماری یعنی تست نقش، سند و کانال

واحد برای تابع نرمال‌سازی مبلغ لازم است. یکپارچگی برای مجوز لازم است: ساکن تجمیع نخواند، مدیر ساختمان دیگر را نبیند. انتهابه‌انتها برای دو مسیر طلایی لازم است: مدیر یک اعلان یا سند ثبت می‌کند و ساکن همان را در محدودهٔ خودش می‌بیند؛ ساکن پرداخت را شروع می‌کند و سند به وضعیت قابل توضیح می‌رسد.

این تست‌ها را به دادهٔ واقعی نزدیک کنید: نام فارسی، RTL، و مبلغ با جداکننده. تست با نام انگلیسی و مبلغ فرضی لاتین، معماری فارسی را اثبات نمی‌کند.

رویداد محصول را هم از همین مرزها طراحی کنید. «سند ثبت شد» و «ساکن رسید را دید» دو سیگنال جدا هستند. اگر فقط بازدید صفحه داشته باشید، قیف فعال‌سازی را حدس می‌زنید. قرارداد نام‌گذاری را در طراحی رویدادهای تحلیلی محصول ببینید تا داشبورد از روی نقش اشتباه تجمیع نشود.

پرسش‌های متداول

آیا مدیر و ساکن باید دیتابیس جدا داشته باشند؟

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

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

چون اختلاف بعدی قابل‌بازسازی نمی‌ماند. تصحیح باید رویداد جدید باشد تا مشخص شود چه عددی، با چه دلیلی، توسط چه کسی عوض شده است. صفحهٔ «ویرایش سلول» برای دفتر ساختمان بدهی اعتماد می‌سازد.

RTL را با ترجمهٔ انگلیسی حل کنیم؟

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

معماری SaaS فارسی مدیریت ساختمان یعنی دو محصول روی یک هستهٔ حسابرسی‌شده: نقش در محدوده، سند مالی به‌صورت رویداد، اعلان در صف، رابط راست‌به‌چپ به‌عنوان قرارداد، و درگاه‌های پرداخت و پیامک پشت آداپتور. اگر یکی از این‌ها را به فرانت یا افزونه بسپارید، بعداً فقط ظاهر را تعمیر می‌کنید. قدم بعدی نوشتن ماتریس نقش‌محدوده و دو مسیر طلایی تست است، قبل از انتخاب رنگ داشبورد.