نشانی و تصویر ساختمان
این سند برای Backend، Frontend و QA است و فقط جریان اطلاعات تکمیلی در SET-06، OBM-UF-02 و OBM-WF-04 را پوشش میدهد. مرجع بصری اطلاعات تکمیلی، node 1349-6973 و مرجع محصول بسته راهاندازی ساختمان و عضویت است. تغییر Flutter، امکانات، تیم و مالی خارج این کار است.
تصمیم تأییدشده
کاربر در 2026-09-19 تأیید کرد که نشانی اختیاری بماند؛ ذخیره موفق آواتار آماده یا عکس ساختمان، ADDITIONAL_INFORMATION را COMPLETED کند و کاربر به Dashboard راهاندازی همان ساختمان برگردد. همچنین MinIO خصوصی برای محیط Development و بهروزرسانی مستندات همین جریان تأیید شد. این تصمیم، تکمیلشدن صرفاً بر اساس وجود نشانی را جایگزین میکند.
این صفحه قرارداد اجرای کار است؛ وجود آن به معنی اتمام پیادهسازی، تست یا استقرار نیست. شواهد تحویل باید جدا ثبت شوند.
مالکیت و دسترسی
buildingsمالک نشانی، انتخاب تصویر و ارتباط تصویر با ساختمان است. Binary در PostgreSQL ذخیره نمیشود.- Actor حساب دارای عضویت و Role فعال در همان Building و Permission موجود
setup.manageاست. این تغییر Permission یا Role جدید اعطا نمیکند. - خواندن تصویر نهایی همان بررسی عضویت فعالِ خواندن ساختمان را دارد. شناسه Upload به Account ایجادکننده و همان Building محدود است.
- Browser فقط BFF هممبدأ را صدا میزند؛ Token، کلید MinIO، Object Key و URL خصوصی وارد DTO مرورگر نمیشوند.
- ثبت نشانی و تصویر اعلان یا پیامک ایجاد نمیکند. Actor، Building، نوع تغییر و زمان در Audit ثبت میشوند؛ نشانی، نام فایل و محتوای تصویر در Log عملیاتی نمیآیند.
قواعد نشانی و چکلیست
نشانی و تصویر دو ثبت مستقلاند. عبور از فرم خالی، Upload ناموفق یا انتخاب Preview نباید داده معتبر قبلی را پاک کند. اجزای نشانی برای ورود مجدد جداگانه نگهداری میشوند؛ مقدار قدیمی address برای Client قدیمی حفظ میشود و نباید با تحلیل متن آزاد، استان یا شهر حدس زده شود. کد پستیِ واردشده ده رقم است؛ ارقام فارسی و عربی به ASCII نرمال میشوند.
انتخاب آواتار از چهار شناسه ثابت محلی است: house-modern، house-town، apartment و tower. URL دلخواه Client پذیرفته نمیشود. انتخاب تصویر ذخیرهشده در پاسخ Building برمیگردد و Dashboard همان انتخاب را نمایش میدهد.
| داده پایدار | وضعیت مشتق اطلاعات تکمیلی |
|---|---|
| بدون نشانی و بدون تصویر | NOT_STARTED |
| نشانی ذخیرهشده، بدون تصویر | IN_PROGRESS با ۵۰ درصد |
| آواتار ذخیرهشده یا عکس بررسیشده و انتخابشده | COMPLETED، مستقل از نشانی |
| Upload در انتظار یا ردشده | وضعیت قبلی بدون تغییر |
تصمیم DEFERRED تا اقدام صریح کاربر حفظ میشود؛ ذخیره نهایی تصویر همان اقدام صریح تکمیل است و وضعیت بخش را همراه انتخاب تصویر اتمیک به حالت تکمیل برمیگرداند. تکمیل اطلاعات تکمیلی، بخش دیگری را تکمیل نمیکند. تعداد بخشهای جاری پنج است؛ Front مقدار پیشرفت را از API میگیرد.
Upload خصوصی و شبکه ضعیف
جزئیات جداسازی Worker، Decoder، Credential و تراکنشهای RLS در ADR-0003 ثبت شدهاند. MinIO فقط برای Development خصوصی تأیید شده و انتشار به Scan موفق Digest وابسته است.
Allowlist برابر JPEG، PNG و WebP با حداکثر 2097152 بایت است. نام، پسوند و MIME اعلامی بهتنهایی معتبر نیستند؛ اندازه واقعی، SHA-256 و Magic Byte مستقل بررسی میشوند. تصویر اولیه در قرنطینه خصوصی باقی میماند. Decode و تولید نسخه نمایشی باید در Sandbox محدود از نظر حافظه، CPU و زمان انجام شود و Metadata تصویر اصلی به خروجی نمایشی منتقل نشود.
جریان به شروع Upload، ارسال محتوا، بررسی و انتخاب تصویر آماده تقسیم میشود. وضعیتهای Upload از انتخاب تصویر ساختمان مستقلاند: PENDING، PROCESSING، READY و REJECTED. دریافت فایل یا پاسخ 202 موفقیت نهایی نیست. فقط READY متعلق به همین Tenant قابل انتخاب است. پیشنمایش محلی Blob پس از تغییر فایل یا خروج آزاد میشود.
شروع Upload کلید Idempotency با Scope حساب، ساختمان و عملیات دارد؛ Retry همان Payload نتیجه قبلی را میخواند و Payload متفاوت با همان کلید 409 میدهد. ثبت نشانی و انتخاب تصویر از Version ساختمان استفاده میکنند. درخواست تکراری انتخاب همان تصویر اثر دوباره ندارد. Conflict نیازمند دریافت و بازبینی نسخه جاری است؛ بازنویسی خاموش ممنوع است.
قطع شبکه Draft را در حافظه همان صفحه نگه میدارد؛ Mutation خودکار تکرار نمیشود. بررسی وضعیت Upload با فاصله و سقف زمانی محدود انجام میشود. شکست Storage یا پردازش تصویر، تصویر قبلی و Checklist را حفظ میکند. Upload ناقص و قرنطینه با Lifecycle پاک میشوند؛ حذف تصویر قبلی فوری نیست و بازیابی Release را مختل نمیکند.
خطا و متن
همه خطاها Problem Details با messages.fa/en دارند. متن Field و Summary یکسان است.
| وضعیت | Code | پیام فارسی | پیام انگلیسی | بازیابی |
|---|---|---|---|---|
422 |
invalid_building_address |
نشانی معتبر نیست. اطلاعات واردشده را بررسی کنید. | The address is invalid. Check the entered information. | اصلاح ورودی |
422 |
invalid_building_image |
تصویر معتبر نیست. یک فایل JPG، PNG یا WebP تا ۲ مگابایت انتخاب کنید. | The image is invalid. Choose a JPG, PNG or WebP file up to 2 MB. | انتخاب فایل دیگر |
409 |
building_version_conflict |
اطلاعات ساختمان تغییر کرده است. نسخه جدید را دریافت و دوباره بررسی کنید. | The building information has changed. Reload and review the latest version. | دریافت و بازبینی |
409 |
building_image_not_ready |
بررسی تصویر هنوز تمام نشده است. کمی بعد دوباره تلاش کنید. | The image is still being checked. Try again shortly. | انتظار محدود |
409 |
building_image_upload_conflict |
این درخواست با اطلاعات دیگری ثبت شده است. انتخاب تصویر را دوباره انجام دهید. | This request was recorded with different information. Select the image again. | Intent جدید |
429 |
building_image_rate_limited |
درخواستهای زیادی ارسال شده است. کمی بعد دوباره تلاش کنید. | Too many requests. Try again shortly. | رعایت Retry-After |
503 |
building_image_unavailable |
تصویر ذخیره نشد. انتخاب شما حفظ شده است؛ دوباره تلاش کنید. | The image could not be saved. Your selection is preserved; try again. | Retry دستی |
503 |
building_additional_information_unavailable |
عملیات انجام نشد. اطلاعات واردشده حفظ شده است؛ دوباره تلاش کنید. | The operation could not be completed. Your input is preserved; try again. | Retry دستی؛ خطای عمومی برای خواندن یا ثبت اطلاعات |
خطاهای 401، نبود Scope معتبر 404 و Permission ناکافی 403 از قرارداد مشترک موجود استفاده میکنند. جزئیات Provider، Bucket یا وجود ساختمان دیگر افشا نمیشود.
پذیرش و انتشار
- آواتار و عکس معتبر بدون نشانی، بخش را تکمیل و به Dashboard همان ساختمان برمیگردانند.
- Refresh و ورود دوباره، اجزای نشانی و تصویر واقعی را بازمیگردانند.
- فایل جعلی، خالی، بزرگ، خراب و Upload متعلق به Tenant یا Actor دیگر رد میشود.
- Timeout، Double-submit، پاسخ گمشده، Version Conflict و تغییر Tenant تصویر قبلی را از بین نمیبرند.
- عضویت غیرفعال، Role غیرفعال و Permission ناکافی پیش از دسترسی Storage رد میشوند.
- Migration افزایشی است و Rollback کد به حذف Binary یا داده جدید وابسته نیست.
- تست MinIO واقعی، PostgreSQL واقعی، مسیر BFF، نامهای دوزبانه و UI در عرض مرجع
402و حداقل320لازم است. - انتشار Development با CI و Digest تغییرناپذیر انجام میشود. Bucket و Console عمومی نمیشوند. Production همچنان نیازمند آزمون سازگاری Arvan طبق استاندارد ذخیرهسازی است.