تقسیم قبض آب بین واحدها در نرم‌افزار ساختمان: API چه می‌دهد و چه نه

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

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

سناریو

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

API چه می‌دهد

با شناسه قبض، این‌ها برمی‌گردد: مبلغ، شناسه قبض، شناسه پرداخت، نام مشترک، نشانی، نوع اشتراک، و سه تاریخ (قبلی، جاری، مهلت پرداخت). همین. در پاسخ نیست:

• تعداد واحدهای پشت انشعاب
• اینکه انشعاب مشترک است یا اختصاصی
• مصرف به مترمکعب یا هر کنتور دیگر
• سهم کسی از مبلغ

اگر از «نوع اشتراک» انتظار دارید بگوید ساختمان چندواحدی است، نمی‌گوید. این فیلد تعرفهٔ مشترک را نشان می‌دهد و ساختار لوله‌کشی ساختمان را نه. شما آن را باید از ساختمان بدانید و در سامانهٔ خودتان نگه دارید.

قاعدهٔ تقسیم مال کیست

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

مدل داده‌ای که پیشنهاد می‌کنم

چهار جدول ساده کفایت می‌کند:

1. ساختمان و شناسه‌ها. هر ساختمان یک یا چند billId دارد.
2. عکس لحظه‌ای از قبض. هر بار که استعلام می‌زنید یک ردیف جدید بسازید: مبلغ، سه تاریخ، نام و نشانی، fetchedAt، requestId و پاسخ خام. ردیف قبلی را ویرایش نکنید.
3. قاعدهٔ تقسیم. نسخه‌دار: «از دورهٔ فلان، سهم بر اساس متراژ».
4. تخصیص. برای هر واحد، سهمی که با قاعدهٔ همان نسخه از همان عکس لحظه‌ای حساب شده.

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

جاهایی که این طراحی خراب می‌شود

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

استعلام دوباره در یک ساعت. پاسخ‌های قبض در کش مشترک فعلاً یک ساعت تازه می‌مانند. بنابراین استعلام فوری بعد از پرداخت شاید همان عدد قبلی را با source.cached: true برگرداند. fetchedAt را کنار تخصیص نشان دهید تا ساکن بداند عدد مال چه زمانی است.

نشانی را کلید نکنید. نشانی را برای تطبیق ساختمان‌ها به‌کار نبرید. املای آن یکدست نیست. کلید ساختمان در سامانهٔ شما همان billId باشد.

نوع اشتراک را شمارش‌شده فرض نکنید. این فیلد در نمونهٔ پاسخ متن آزاد (مثل «مسکونی») است. خام ذخیره کنید و برای گزارش، خودتان نگاشت بسازید؛ مقدار ناشناخته را به «سایر» ببرید.

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

نمونهٔ محاسبه

فرض کنید قاعدهٔ ساختمان «تقسیم بر اساس متراژ» است. اگر قبض ۱۰۰ واحد پولی و متراژ واحد الف ۲۰ درصد کل باشد، سهم او ۲۰ می‌شود. اینها اعداد ساختگی برای نمایش‌اند. مهم این است که ورودی «۱۰۰» از amount همان عکس لحظه‌ای می‌آید و «۲۰ درصد» از قاعده؛ دو منبع جدا و هر دو ثبت‌شده.

آنچه این سرویس نمی‌کند

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

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

صورتجلسه و شفافیت برای ساکنان

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

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

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

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

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

اگر عجله دارید

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