پرش به محتویات

واحدها و ورود اطلاعات Excel

این ماژول مالک رجیستری واحدها، رابطه اشخاص با واحد و Import اطلاعات واحد است. این صفحه قرارداد کنترل منابع Import در OBM-WF-05 و قاعده اتمیک BR-SET-06C را توضیح می‌دهد. بازبینی انتقال مالکیت و پایان زمان‌بندی‌شده رابطه هنوز کامل نیست؛ این صفحه آن تصمیم‌ها را نهایی نمی‌کند.

مسیر درخواست و مرز داده

در POST /api/v1/buildings/{buildingId}/unit-imports، هویت و مجوز unit.import پیش از ورود به صف بررسی می‌شوند. پس از رسیدن نوبت، مجوز دوباره بررسی می‌شود و سپس فایل خوانده و اعتبارسنجی می‌شود. درخواست منتظر، فایل را در حافظه برنامه Parse نمی‌کند و اتصال یا Transaction پایگاه داده را در صف نگه نمی‌دارد.

اعتبارسنجی XLSX و نگاشت ورودی در HTTP adapter، قواعد ردیف و شمارش در application و ثبت Attempt در PostgreSQL adapter قرار دارند. نتیجه ثبت‌شده با 202 و شناسه Import برمی‌گردد؛ ثبت نهایی واحدها همچنان Action جداگانه Confirm و یک Transaction اتمیک است. فایل دارای خطای مسدودکننده هیچ واحد یا شخصی را به‌صورت جزئی ثبت نمی‌کند. Import پیامک یا Invitation ایجاد نمی‌کند.

تنظیم منابع و انتظار

متغیر محیطی معنا مقدار پیش‌فرض
UNIT_IMPORT_MAX_CONCURRENT بیشترین تعداد Import فعال هم‌زمان در هر API instance؛ عدد صحیح مثبت 1
UNIT_IMPORT_TIMEOUT مهلت کل درخواست Import شامل مجوز، انتظار، دریافت فایل، Parse و ثبت Attempt؛ با قالب Go duration 30s

مقادیر از .env توسعه یا environment فرایند خوانده و در startup اعتبارسنجی می‌شوند. مقدار صفر، منفی یا نامعتبر پذیرفته نمی‌شود. Compose محلی و استقرار همین دو مقدار را به API منتقل می‌کنند. این پیش‌فرض‌ها ادعای ظرفیت اندازه‌گیری‌شده نیستند؛ انتخاب ظرفیت عملیاتی به حافظه و CPU همان instance وابسته است.

  • حداکثر ۳۲ درخواست علاوه بر Importهای فعال، به ترتیب ورود در حافظه همان instance منتظر می‌مانند. این سقف داخلی، تعداد درخواست‌های منتظر را محدود می‌کند؛ بار فایل‌های منتظر وارد parser نمی‌شود.
  • با آزاد شدن ظرفیت، درخواست بعدی بدون Submit مجدد کاربر شروع می‌شود. لغو Client یا پایان مهلت، درخواست منتظر را از صف حذف می‌کند.
  • مهلت Excel مستقل از HTTP_REQUEST_TIMEOUT سایر APIها است؛ deadline خواندن و نوشتن همان درخواست نیز تنظیم می‌شود. لغو محاسبه در نقاط بررسی context انجام می‌شود و thread به‌صورت اجباری متوقف نمی‌شود.
  • Proxy و Client نیز باید مهلتی سازگار داشته باشند؛ timeout کوتاه‌تر آن‌ها با تنظیم Backend قابل افزایش نیست.
  • صف Job پایدار نیست و با restart بازیابی نمی‌شود. پیش از دریافت 202، Frontend نباید ایجاد Import را قطعی بداند. نتیجه نامشخص با همان Idempotency-Key و فایل بازیابی می‌شود.
  • سقف هم‌زمانی و مهلت در development نیز برقرارند و با bypass محدودیت نرخ حذف نمی‌شوند.

خطا، امنیت و بازیابی

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

صف پر یا پایان مهلت پیش از شروع، پاسخ موجود 503 با کد unit_operation_unavailable و پیام امن دو‌زبانه دارد. تا زمانی که درخواست در صف پذیرفته شده و مهلت دارد، فقط وضعیت Processing نمایش داده می‌شود و از کاربر Submit مجدد خواسته نمی‌شود. Client لغوشده پاسخ تضمین‌شده ندارد. هیچ فایل، نام شخص، موبایل یا payload در Log صف نوشته نمی‌شود.

متن موجود خطا: عنوان انگلیسی Unit operation unavailable و متن Try again later.؛ عنوان فارسی «عملیات واحد در دسترس نیست» و متن «بعدا دوباره تلاش کنید.». خطاهای ورودی و Idempotency قرارداد قبلی را حفظ می‌کنند.

آزمون و Rollback

آزمون‌ها سقف هم‌زمانی، ترتیب صف، ادامه خودکار، لغو، پایان مهلت، صف پر، آزاد شدن ظرفیت پس از شکست، بررسی مجوز پیش و پس از انتظار و نخواندن body در صف را پوشش می‌دهند. آزمون HTTP اثبات می‌کند timeout اختصاصی، مهلت سایر endpointها را تغییر نمی‌دهد و از deadline کوتاه‌تر Client عبور نمی‌کند.

این تغییر Schema یا State جدیدی ندارد. Rollback باینری، کنترل جدید صف را حذف می‌کند؛ Attemptهای ثبت‌شده و قرارداد GET/Confirm باقی می‌مانند. تا اجرای آزمون و استقرار نسخه جدید، این کنترل در سرور مستقر فعال فرض نمی‌شود.

مراجع